Debug

Visualization overlays for debugging simulations

Renders debug overlays for MuJoCo simulation elements — geom wireframes, site markers, joint axes, camera frustums, contact forces, center of mass, and more.

For the distinction between viewer cameras, MuJoCo cameras, offscreen capture poses, and virtualCameras, see Cameras and Captures.

Usage

<MujocoCanvas config={config}>
  <Debug showSites showJoints showContacts />
</MujocoCanvas>

Props

showGeoms · boolean · default: "false"

Show wireframe outlines of collision geoms.

showSites · boolean · default: "false"

Show MuJoCo sites as small octahedrons.

showJoints · boolean · default: "false"

Show joint axes as colored arrows.

showContacts · boolean · default: "false"

Show contact force vectors as arrows.

showCameras · boolean · default: "false"

Show MuJoCo camera positions, frustums, labels, and forward rays from the live cam_xpos / cam_xmat frame.

virtualCameras · DebugVirtualCamera[] · default: "[]"

Show explicit virtual camera poses that are not declared as MJCF cameras, such as fixed policy/offscreen render viewpoints created from position, lookAt, up, fov, width, and height.

showCOM · boolean · default: "false"

Show center of mass markers for each body.

showInertia · boolean · default: "false"

Show inertia ellipsoids.

showTendons · boolean · default: "false"

Show tendon paths.

geomColor · string · default: "#00ff00"

Color for wireframe geoms.

siteColor · string · default: "#ff00ff"

Color for site markers.

contactColor · string · default: "#ff4444"

Color for contact force arrows.

comColor · string · default: "#ff0000"

Color for center of mass markers.

How It Works

• Static geometry (geoms, sites, joints) is created once when the model loads
• Positions are updated every frame using preallocated temp vectors to minimize GC pressure
• Camera frustums are derived from MuJoCo camera state and are excluded from mounted camera captures
• Explicit virtual camera frustums from virtualCameras are also excluded from camera captures, so visual debugging does not contaminate policy images
• Contact arrows use a pre-created pool of 50 ArrowHelper objects — they are shown/hidden and repositioned each frame rather than created and disposed

Example: Debug Panel Toggle

function App() {
  const [debug, setDebug] = useState({
    sites: false, joints: false, contacts: false, cameras: false,
  });

  return (
    <MujocoCanvas config={config}>
      <Debug
        showSites={debug.sites}
        showJoints={debug.joints}
        showContacts={debug.contacts}
        showCameras={debug.cameras}
        virtualCameras={[
          {
            name: "policy front",
            position: [0.72, 0, 1.08],
            lookAt: [0.4, 0, 0.43],
            up: [0, 0, 1],
            fov: 50,
            width: 640,
            height: 480,
          },
        ]}
      />
    </MujocoCanvas>
  );
}

Example: Custom Colors

<Debug
  showSites
  showContacts
  showCOM
  siteColor="#00ffff"
  contactColor="#ff8800"
  comColor="#ffff00"
/>