unilab.visualization.debug_primitives

Interactive-viewer injection for unisim.backend.base.DebugPrimitive.

The offline record pipeline renders debug overlays inside unisim’s render workers. Interactive MuJoCo viewers instead own a live viewer.user_scn (mjvScene), so this module converts the same typed primitives into user-scene geoms for that path. It is UniLab-owned until unisim exposes a public interactive-path helper (single env, already-loaded model, caller-owned mjvScene); see ADR-0008 and unilabsim/wuji_unilab#21.

Functions

append_debug_primitives_to_scene(scene, ...)

Inject debug primitives into a caller-owned mjvScene (viewer.user_scn).

quat_from_z_axis(direction)

Return the unit wxyz quaternion rotating the +z axis onto direction.

segment_arrow(p0, p1, *, rgba[, min_length])

Build an arrow primitive spanning p0 → p1 (None when degenerate).
unilab.visualization.debug_primitives.append_debug_primitives_to_scene(scene, primitives, *, mesh_ids=None)[source]

Inject debug primitives into a caller-owned mjvScene (viewer.user_scn).

mesh_ids resolves ghost_geom mesh assets to mesh ids in the loaded viewer model; a ghost primitive without a resolvable mesh raises ValueError. text primitives are a documented no-op (mjvScene has no text channel), matching the offline renderer. Returns the number of geoms appended; injection stops at scene.maxgeom.

Parameters:
Return type:

int

unilab.visualization.debug_primitives.quat_from_z_axis(direction)[source]

Return the unit wxyz quaternion rotating the +z axis onto direction.

Parameters:

direction (Sequence[float])

Return type:

tuple[float, float, float, float]

unilab.visualization.debug_primitives.segment_arrow(p0, p1, *, rgba, min_length=1e-06)[source]

Build an arrow primitive spanning p0 → p1 (None when degenerate).

Parameters:
Return type:

DebugPrimitive | None