Debug Physics

When to Use

• Visual / kinematic glitch on launch (swing, drift, float, sink).
• Contact behaviour wrong (tunnelling, no contact, no friction).
• Solver-specific symptoms — works on PhysX but not Newton, or vice versa.
• Render proxy showing instead of visual mesh (convex-hull look).
• Joint exceeds URDF <limit> and MoveIt rejects the start state.

Do not use for:

• Launch errors before physics even runs → check build-workspace skill output first.
• MoveIt planning failures with sane physics → that's moveit-wbc, in particular the fix_start_state + start_state_max_bounds_error knobs.
• Performance tuning (low FPS, JIT compile time) — different topic.

Critical Patterns

1. init_base_pose / init_joint_pos are non-physics teleport. The engine writes them to USD attributes before world.reset() on PhysX and to model.joint_q + control.joint_target_pos before the first solver tick on Newton — drive error is zero at t=0, so no startup swing. If you see a swing, your launcher / scene yaml is bypassing this path.
2. init_joint_pos is JSON-encoded, not a launch list. launch_ros mangles list-typed params; the engine reads init_joint_pos_json and decodes. Always edit it in scene yaml, not on the CLI.
3. The convex-hull look means the visual mesh was stripped. The engine blocks the physics:approximation token when collisionEnabled=False, so the GL viewer renders the visual mesh. If you still see the proxy, the USD set collisionEnabled=True with a convexDecomposition approximation and the visual mesh is missing.
4. Backend swap is one-arg. Whenever you suspect engine bugs, re-launch with the other launcher: launcher_ovrtx_isaac_physx (stable) vs launcher_newton_mjwarp (rigid, mujoco-warp). If only one backend reproduces, the issue is solver-side, not asset-side.
5. Use the GL viewer for ground truth. Newton-standalone + inline OVRtx can mask geometry issues with photoreal lighting. The Newton GL viewer renders raw visual + collision meshes, so it's the right tool for "is the asset actually there".

Decision tree

Symptom: robot swings violently on spawn

Symptom: contact tunnelling / objects sink through floor

Symptom: shelf / object renders as a convex hull

Symptom: gripper poses wrong / EEF off

Common one for omnipicker / swiftpicker — verify:

• Scene yaml gripper: matches the URDF you built MoveIt for.
• MoveIt's (arm, gripper) matches the engine's. See moveit-wbc.
• EEF_ABS payloads use arm_base_link framing (not base_link) — this was the most common confusion before commit 6391cdcf6.

Toggles & visualizers

# Newton GL viewer (rigid only, kit-free) — see raw geometry:
ros2 launch genie_sim_bringup app.launch.py \
  scene:=<SCENE> \
  launcher_config:=launcher_newton_mjwarp \
  headless:=false   # local workstation with a screen; flip to true on a remote/headless host

# Debug marker / pointcloud publishers (enabled in the launcher yaml):
ros2 topic list | grep -E "marker|pointcloud|debug"
ros2 topic echo /debug/contacts                      # contact normals + impulses
ros2 topic echo /debug/init_pose                     # confirms init_* applied

# Compare runtime USD against source:
cat assets/scenes/<scene>/robot_runtime.usda | head  # post-strip / post-overrides

Per-scene viewer-camera pose is configurable in the scene yaml:

viewer_camera:
  pos:    [1.6, -1.6, 1.2]
  lookat: [0.0,  0.0, 0.8]

Backend swap as a bisection tool

When in doubt, run the same scene through both stable launchers and diff the behaviour:

ros2 launch genie_sim_bringup app.launch.py scene:=<S> launcher_config:=launcher_ovrtx_isaac_physx
ros2 launch genie_sim_bringup app.launch.py scene:=<S> launcher_config:=launcher_newton_mjwarp

• Same misbehaviour on both → asset / scene yaml bug (URDF inertia, init_pose, collision flags).
• Different misbehaviour → solver-tuning bug (gains, contact compliance, integrator step).

Commands (copy-paste summary for the user)

# 1. Force scene regenerate to rule out a stale cache
rm -rf assets/scenes/<scene>/
# OR:
ros2 launch genie_sim_bringup app.launch.py scene:=<S> launcher_config:=launcher_ovrtx_isaac_physx always_regenerate_robot_usd:=true

# 2. Try the other backend (bisection) — flip headless to true on a remote/headless host
ros2 launch genie_sim_bringup app.launch.py scene:=<S> launcher_config:=launcher_newton_mjwarp headless:=false

# 3. Inspect debug topics
ros2 topic list | grep -E "marker|debug|contacts"
ros2 topic echo /debug/contacts

# 4. Inspect the runtime USD
cat assets/scenes/<scene>/robot_runtime.usda

Notes

• All launcher_newton_* rows except launcher_newton_mjwarp are experimental — physics, perf, and yaml schema can break between commits. Use them when you specifically need cloth / soft body or are intentionally testing a solver, not as a general fallback.
• The _apply_init_base_pose helper writes to the session layer with a unique suffix, so re-launching doesn't accumulate xformOpOrder ops. Safe to relaunch repeatedly.
• The OVRtx first-frame banner is one-shot, not a heartbeat — shader compile holds the GIL inside a C extension, so there's nothing to tick. If the banner sits without progress for >2 min, the compile cache is missing (rebuild the docker image's shader cache mount).

Resources

• Engine entry: source/geniesim_ros/src/ros_ws/src/genie_sim_engine/
• Init pose pipeline: genie_sim_engine/scripts/engine/newton/setup/init_pose.py, kit/stage.py
• Scene yamls: source/geniesim_ros/src/ros_ws/src/genie_sim_bringup/config/
• Engine overview: source/geniesim_ros/README.md
• Related skills: launch-scene, moveit-wbc, add-robot