pymomentum.rerun_vis

Rerun Visualization Helpers

Helper functions for visualizing momentum characters using the Rerun viewer, providing the Python equivalent of the C++ momentum::logCharacter family of functions in momentum/gui/rerun/logger.h.

The primary entry point is log_character(), which logs the skeleton, mesh, and locators of a character in a structured entity tree:

import rerun as rr
import pymomentum.geometry as geo
from pymomentum.rerun_vis import log_character

character = geo.Character.load_gltf("character.glb")
char, motion, identity, fps = geo.Character.load_gltf_with_motion("motion.glb")
skel_state = geo.joint_parameters_to_skeleton_state(char, motion[0])
posed_mesh = char.pose_mesh(motion[0])

rec = rr.init("pymomentum_viewer", spawn=True)
log_character(rec, "character", char, skel_state, posed_mesh=posed_mesh)

For multi-frame animation, use log_animation() which sends all frames using rerun.send_columns() for dramatically better throughput:

skel_states = geo.joint_parameters_to_skeleton_state(char, joint_params)
posed_meshes = [char.pose_mesh(jp) for jp in joint_params]
log_animation(rec, "character", char, skel_states,
              posed_meshes=posed_meshes, fps=fps)

Individual logging functions are also available for finer control:

pymomentum.rerun_vis.log_animation(rec: rr.RecordingStream, entity_path: str, character: pymomentum.geometry.Character, skel_states: np.ndarray, *, posed_meshes: Sequence[pymomentum.geometry.Mesh] | None = None, fps: float = 30.0, color: tuple[int, int, int] = (200, 200, 200), frame_offset: int = 0, collision_geometry: bool = False) → None

Log a multi-frame character animation using columnar batch sends.

This sends all frames at once using rerun.send_columns(), which is dramatically faster than per-frame log_character() calls for long animations.

For memory-bounded processing of very long animations, call this function in a loop with chunks of frames and matching frame_offset values:

chunk_size = 1000
for start in range(0, n_frames, chunk_size):
    end = min(start + chunk_size, n_frames)
    chunk_meshes = [char.pose_mesh(jp) for jp in joint_params[start:end]]
    log_animation(rec, path, char, skel_states[start:end],
                  posed_meshes=chunk_meshes, fps=fps, frame_offset=start)
Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Root entity path for the character.

  • character – The character to visualize.

  • skel_states – Skeleton state array of shape (n_frames, n_joints, 8) with per-joint [tx, ty, tz, rx, ry, rz, rw, scale]. Use joint_parameters_to_skeleton_state() with a batched (n_frames, n_joint_params) input to compute this efficiently in a single C++ call.

  • posed_meshes – Optional sequence of pre-posed meshes, one per frame. If None, no mesh is logged.

  • fps – Frames per second for the time column.

  • color – RGB color for the mesh albedo factor.

  • frame_offset – Starting frame index for the time columns. Use when sending multiple chunks of the same animation.

  • collision_geometry – If True, log collision proxy capsules, ellipsoids, and boxes.

pymomentum.rerun_vis.log_character(rec: rr.RecordingStream, entity_path: str, character: pymomentum.geometry.Character, skel_state: np.ndarray, *, posed_mesh: pymomentum.geometry.Mesh | None = None, color: tuple[int, int, int] = (200, 200, 200), collision_geometry: bool = False) → None

Log a complete character visualization to Rerun.

This is the top-level convenience function that logs the skeleton, optionally the mesh, and locators as a structured entity tree:

  • {entity_path}/mesh — posed mesh (if posed_mesh is provided)

  • {entity_path}/joints — skeleton bones and per-joint transforms

  • {entity_path}/locators — locator positions (if character has locators)

  • {entity_path}/collision_proxies — collision capsules, ellipsoids, and boxes (when requested)

This is the Python equivalent of the C++ momentum::logCharacter function.

Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Root entity path for the character.

  • character – The character to visualize.

  • skel_state – Skeleton state array of shape (n_joints, 8) with per-joint [tx, ty, tz, rx, ry, rz, rw, scale]. Obtain via joint_parameters_to_skeleton_state() or model_parameters_to_skeleton_state().

  • posed_mesh – An optional pre-posed mesh (from pose_mesh()). If None, no mesh is logged.

  • color – RGB color tuple for the mesh albedo. Defaults to light grey (200, 200, 200).

  • collision_geometry – If True, log collision proxy capsules, ellipsoids, and boxes.

pymomentum.rerun_vis.log_collision_geometry(rec: rr.RecordingStream, entity_path: str, character: pymomentum.geometry.Character, skel_state: np.ndarray, *, color: tuple[int, int, int] = (128, 64, 64)) → None

Log collision proxy primitives to Rerun.

Momentum collision geometry is stored as tapered capsules, ellipsoids, and boxes. Capsules are logged at entity_path (Rerun renders them as ordinary capsules using the larger endpoint radius); ellipsoids and boxes are logged at the {entity_path}/ellipsoids and {entity_path}/boxes sub-paths.

Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Entity path for the collision proxy entity.

  • character – The character whose collision geometry is logged.

  • skel_state – Skeleton state array of shape (n_joints, 8).

  • color – RGB color tuple for the collision proxies.

pymomentum.rerun_vis.log_joints(rec: rr.RecordingStream, entity_path: str, character: pymomentum.geometry.Character, skel_state: np.ndarray) → None

Log skeleton bones and per-joint transforms to Rerun.

Bones are drawn as grey rerun.LineStrips3D connecting parent–child joint pairs. Each joint also gets a rerun.Transform3D logged as a child entity so that the Rerun viewer can display its local coordinate frame.

Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Entity path for the skeleton entity.

  • character – The character whose skeleton is logged.

  • skel_state – Skeleton state array of shape (n_joints, 8) with per-joint [tx, ty, tz, rx, ry, rz, rw, scale].

pymomentum.rerun_vis.log_locators(rec: rr.RecordingStream, entity_path: str, character: pymomentum.geometry.Character, skel_state: np.ndarray) → None

Log locator positions to Rerun as colored 3D points.

Locators whose name contains "Floor_" are shown in green; others are shown in a grey whose intensity is proportional to the locator weight.

Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Entity path for the locators entity.

  • character – The character whose locators are logged.

  • skel_state – Skeleton state array of shape (n_joints, 8).

pymomentum.rerun_vis.log_mesh(rec: rr.RecordingStream, entity_path: str, mesh: pymomentum.geometry.Mesh, *, color: tuple[int, int, int] | None = None) → None

Log a Mesh to Rerun as a 3D mesh.

Parameters:

  • rec – The Rerun recording stream.

  • entity_path – Entity path in the Rerun viewer.

  • mesh – The mesh to log (typically a posed mesh from pose_mesh()).

  • color – Optional RGB color tuple (r, g, b) applied as an albedo factor. If None, per-vertex colors from the mesh are used when available.