Shared Renderer Configuration¶

This page documents camera, base, ground-plane, and color settings shared by multiple SoRoMoX renderers.

Camera Configuration¶

CameraConfig¶

The CameraConfig class provides unified camera configuration across renderers (Matplotlib, Open3D, Viser).

from soromox.rendering import CameraConfig

camera = CameraConfig(
    fov=60.0,                           # Field of view in degrees
    position=(0.6, -0.6, 0.4),          # Camera position (x, y, z)
    look_at=(0.0, 0.0, 0.1),            # Point camera looks at
    up=(0.0, 0.0, 1.0),                 # Camera up vector (default: Z-up)
    distance_factor=2.0,                # Multiplier for auto-positioning
)

renderer.show(q, camera_config=camera)

Parameters¶

Matplotlib applies fov and the viewing direction from position to look_at; its axes limits determine the remaining framing. Open3D and Viser also use the explicit camera distance.

CameraConfig(fov: float = 75.0, position: tuple[float, float, float] | None = None, look_at: tuple[float, float, float] | None = None, up: tuple[float, float, float] = (0.0, 0.0, 1.0), distance_factor: float = 10.0, position_offset: tuple[float, float, float] = (0.8, -0.8, 0.5))

# Default camera with Z-up, auto-positioned
camera = CameraConfig()

# Custom field of view with an explicit position
camera = CameraConfig(
    fov=60.0,
    position=(0.5, -0.5, 0.3),
    look_at=(0.0, 0.0, 0.1),
)

# Auto-positioned but closer to the scene
camera = CameraConfig(distance_factor=5.0)

compute_auto_position(center: ndarray, max_extent: float, reference_transform: ndarray | None = None) -> tuple[ndarray, ndarray]

compute_up() -> ndarray

Robot Base and Ground Plane¶

All renderers obtain the robot origin and orientation from the model's base_pose and base_transform. This keeps the rendered backbone, base, and reference geometry in the same world frame without a renderer-specific pose override.

from soromox.rendering import ViserRenderer

renderer = ViserRenderer(
    robot,
    base_plate_radius_scale=2.0,
    base_plate_thickness=0.06,
    show_ground_plane=True,
    ground_plane_size=0.6,
)

Matplotlib draws a lightweight base marker. Open3D and Viser render base-plate geometry and place the ground plane immediately behind it along the model's base axis. Viser uses its native grid primitive. Specialized Viser renderers, including I-SUPPORT and UMArm, inherit these settings.

Color Configuration¶

Color Hierarchy¶

Colors are configured via RendererColorConfig + BackboneColorConfig and resolved using a consistent hierarchy. More specific inputs override less specific ones:

robot_palette → segment_palette → point_palette
robot_colors → segment_colors → point_colors
robot_segment_colors → robot_point_colors

Alpha values in per-robot colors propagate to more specific colors when those omit alpha.

RendererColorConfig¶

Main color configuration container for all renderers.

from soromox.rendering import ActuatorStyleConfig, BackboneColorConfig, RendererColorConfig

color_config = RendererColorConfig(
    backbone=BackboneColorConfig(
        robot_palette="viridis",
        segment_palette="soromox:ember",
    ),
    base_plate_color=(0.5, 0.5, 0.5),
    ground_plane_color=(0.94, 0.95, 0.96),
    ground_plane_grid_color=(0.72, 0.75, 0.78),
    actuators=ActuatorStyleConfig(
        default_color=(0.8, 0.2, 0.2),
        kind_colors={"tendon": (0.85, 0.2, 0.15)},
        kind_radii={"tendon": 5e-4},
    ),
)

renderer.show(q, color_config=color_config)

RendererColorConfig(backbone: BackboneColorConfig = BackboneColorConfig(), base_plate_color: tuple[float, float, float] = (0.2, 0.2, 0.2), ground_plane_color: tuple[float, float, float] = (0.94, 0.95, 0.96), ground_plane_grid_color: tuple[float, float, float] = (0.72, 0.75, 0.78), actuators: ActuatorStyleConfig = ActuatorStyleConfig())

BackboneColorConfig¶

Backbone-specific color configuration with palette and explicit color support.

from soromox.rendering import BackboneColorConfig

backbone_config = BackboneColorConfig(
    robot_palette="plasma",                    # Colormap for multiple robots
    segment_palette="soromox:ember",           # Per-segment colors
    robot_colors=[(0.2, 0.6, 0.9, 0.5)],       # Explicit robot colors with alpha
)

BackboneColorConfig(segment_palette: ColorSpec = DEFAULT_SEGMENT_PALETTE, robot_palette: ColorSpec = DEFAULT_ROBOT_PALETTE, point_palette: ColorSpec | None = None, robot_colors: ColorSpec | None = None, segment_colors: ColorSpec | None = None, robot_segment_colors: ColorSpec | None = None, point_colors: ColorSpec | None = None, robot_point_colors: ColorSpec | None = None)

Built-in Palettes and Themes¶

Available Palettes¶

SoRoMoX includes publication-friendly color palettes:

You can also use any Matplotlib colormap name (e.g., "viridis", "plasma", "coolwarm").

from soromox.rendering import list_builtin_palettes

print(list_builtin_palettes())

Color Themes¶

Pre-configured themes for consistent styling:

from soromox.rendering import get_color_theme, list_builtin_themes

# List available themes
print(list_builtin_themes())

# Use a theme
theme = get_color_theme("soromox:paper")
renderer = ViserRenderer(robot, color_config=theme)

Color Shape Reference¶

When providing explicit colors, use these shapes:

Color Legend¶

For creating legends in plots:

legend = renderer.get_color_legend(num_robots=3, color_config=color_config)
# Returns ColorLegend with robot labels and colors

ColorLegend(level: Literal['robot', 'segment', 'point'], colors_rgba: ndarray, labels: list[str])

Multi-Robot Layouts¶

Matplotlib, Open3D, and Viser accept batched robot configurations:

• q with shape (N, DOF) for show() and render_frame();
• q_ts with shape (N, T, DOF) for sequence rendering or animation.

Use base_offsets to place each robot explicitly or grid_spacing to control automatically generated layouts. Viser additionally supports multi_robot_layout="overlay" to render robots at a common base pose. Per-robot colors and alpha values can distinguish overlaid configurations.

Open3D automatically merges each robot's backbone primitives into one dynamic mesh when an animated scene contains multiple robots. This removes most backend geometry registrations; set merge_backbone_meshes=True to force merging for one robot or False to disable it for profiling or compatibility. Viser always uses its instanced or color-grouped backbone representation because browser scene-handle and message counts dominate that backend. Automatically sized Viser ground planes are centered on the rendered bases and expanded to cover the layout.

renderer.render_sequence(
    ts,
    q_ts_batched,
    multi_robot_layout="overlay",
    color_config=color_config,
)

Recording and Video Encoding¶

All renderer families accept record_path for sequence output, while their capture mechanisms differ:

• Matplotlib uses its animation writers and requires FFmpeg for MP4 output.
• Open3D and Viser use FFmpeg with VideoEncodingConfig.
• Open3D writes PNG frames when record_path names a directory.
• Viser can capture synchronized browser snapshots with snapshot_paths.
• OpenCV uses FFmpeg when available and otherwise falls back to cv2.VideoWriter.

from soromox.rendering import VideoEncodingConfig

renderer.render_sequence(
    ts,
    q_ts,
    record_path="trajectory.mp4",
    video_config=VideoEncodingConfig(crf=18, pix_fmt="yuv420p"),
)

Use record_every_n to subsample captured frames where supported. Recording depends on the backend, so consult the relevant renderer API for capture-only options.

VideoEncodingConfig(codec: str = 'libx264', pix_fmt: str = 'yuv444p', preset: str | None = 'veryslow', crf: int | None = 12, tune: str | None = 'animation', profile: str | None = None, bitrate: str | None = None, gop: int | None = None, extra_args: tuple[str, ...] = ())