Shared Renderer Configuration¶

RendererConfig groups settings into five sections: scene, camera, colors, geometry and output. Start with a scene preset, then adjust the sections needed for your visualization. Compare the presets in the preset gallery.

RendererConfig¶

Every renderer accepts config=RendererConfig(...). The renderer copies and validates the supplied configuration at construction. Preset results are editable; configure them before creating the renderer. Independent defaults use 800 × 600 pixels, 80 backbone samples and 48 cross-section samples.

from soromox.rendering import (
    RendererConfig, SceneConfig, GeometryConfig, RenderOutputConfig, ViserRenderer,
)

config = RendererConfig(
    scene=SceneConfig.studio("neutral", scene_extent=1.2),
    geometry=GeometryConfig(num_points=100, cross_section_resolution=64),
    output=RenderOutputConfig(width=1920, height=1080),
)
config.scene.material.roughness = 0.8
renderer = ViserRenderer(robot, config=config, port=8080)

The sections are scene, camera, colors, geometry and output. Backend controls, such as the Viser server port, are constructor arguments. Trajectories, placement offsets, recording paths and playback controls belong to rendering operations. Per-call camera_config, color_config and video_config replace the corresponding complete default section without modifying it.

Scene configuration¶

Presets¶

Clay overrides backbone, base and actuator colors. Helper objects retain their semantic colors. Studio presets preserve the supplied robot palette.

Lighting and materials¶

Directional lights use illuminance_lux; point lights use intensity_candela and world positions in metres. PointLightConfig.from_lumens(flux) divides isotropic flux by 4*pi. Open3D converts candela back to lumens. Ambient illumination uses relative strength: Open3D uses its environment map, and Viser approximates it with a world-up hemisphere light. Preset scene_extent scales point positions linearly and intensities quadratically; explicit light settings are never resized during camera fitting or playback. Public colors are sRGB.

config.scene.material controls lit/unlit or toon shading, roughness, metallicity, reflectance, opacity, face normals and wireframe. config.scene.shadows and config.scene.ambient_occlusion enable shadow and occlusion effects where supported.

Robot base¶

Robot poses come from the model's fixed base or floating runtime coordinates. Open3D and Viser support four circular mounting shapes through config.geometry.base_plate_style: "disk", "beveled_disk", "truncated_cone" and "flared_collar" (the default). The flared collar has a lower flange, tapered body and upper rim; the beveled disk provides a smaller visual accent. Matplotlib uses a simple filled disk in 3D and a transverse marker in 2D, independently of the selected mount style. OpenCV uses its planar base marker.

base_plate_radius_scale multiplies the proximal cross-section's maximum radial extent: the circle radius, larger ellipse semi-axis, or rectangle half-diagonal. The default multiplier is 2.0. base_plate_thickness specifies the total mount height in metres (default 0.06), independently of the radius. The mount extends behind the robot's proximal point along its base axis.

config.geometry.base_plate_style = "flared_collar"
config.geometry.base_plate_radius_scale = 2.0
config.geometry.base_plate_thickness = 0.024

The disk and beveled disk above use a 28 mm radius and 12 mm height; the cone and collar use a 32 mm radius and 24 mm height. Each style can use either size.

Ground plane and backdrop¶

The independent config.scene.ground describes the floor:

from soromox.rendering import GroundPlaneConfig

config.scene.ground = GroundPlaneConfig(
    visible=True, surface=True, alignment="world", height=0.0,
    height_reference="world", size=1.2,
    color=(0.85, 0.85, 0.85), opacity=1.0,
    grid=True, grid_spacing=0.1, grid_major_every=5, receive_shadow=True,
)

The technical default uses surface=False: a grid without a filled slab. surface=True adds a shadow-receiving plane. Grid spacing is fixed in metres, anchored to the world origin and shared between backends. Automatic spacing selects a ½/5 decimal step; grid_major_every and grid_major_color control the major lines. Planar renderers show this reference as a line.

A world floor uses +Z for spatial robots and +Y for planar robots. normal selects an explicit world normal; height is measured along the selected reference in metres. The default height_reference="world" keeps the current world-origin height behavior. height_reference="base_mounting_face" uses the configured base plate thickness and the current robot base position, so height=0 places a world-aligned floor at the mounting face of the base plate. A world-aligned base-referenced floor requires all robot bases to share one height; alignment="base" creates one plane per robot when they do not. Base alignment already anchors each plane at its corresponding base mounting face, and height offsets that plane along the base normal. The base_mounting_face reference requires a fixed base; selecting it for a floating-base robot raises ValueError. It also requires every fixed base axis to be parallel or antiparallel to the floor normal: +Z shifts the floor down by the plate thickness, while -Z shifts it up by the same amount.

The existing normal field represents the ground direction, so spatial z-up and z-down planes are selected with normal=(0, 0, 1) and normal=(0, 0, -1). For a hanging composition, rotate the camera position and look-at with the mounting orientation and keep camera up at +z. The gallery provides this as --mounting hanging, preserving the curved studio surface above the robot.

scene = SceneConfig.studio(
    ground=GroundPlaneConfig(height_reference="base_mounting_face")
)

Automatic sizing fits the whole robot trajectory and helper bounds. Scenery is excluded from camera fitting. Live visualization retains its initial bounds. A curved backdrop uses the same resolved floor height.

BackdropConfig.radius controls the bend's horizontal reach; vertical_radius controls its height and defaults to the same value. curvature_easing ranges from 0 (an elliptical arc) to 1 (a curve that gradually flattens into the floor and wall). wall_offset places the start of the bend behind the scene center. These dimensions are multiples of the fitted scene extent.

The studio and clay presets use a low, gradually curved transition:

scene = SceneConfig.studio()
scene.backdrop.radius = 0.40
scene.backdrop.vertical_radius = 0.23
scene.backdrop.wall_offset = 0.02
scene.backdrop.curvature_easing = 0.80

Its key light illuminates both the floor and wall, with ambient illumination and point fills reducing the contrast across the bend. Bright and dark retain their distinct lighting settings. Clay uses neutral studio lighting with an additional cool rim light and a uniform matte robot material.

Camera configuration¶

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)

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.

Exposure and tone mapping¶

CameraConfig.exposure_ev100 defaults to 15. Increasing it by one halves light strength in the modern Open3D adapter and the Viser approximation. This scales illumination because their public APIs do not expose a shared photographic camera exposure control. It does not simulate aperture, shutter blur or depth of field. Choose scene.tone_mapping="backend-default", "linear" or "aces". The patched Open3D build uses Filament’s Filmic mapper for backend-default, preserving neutral highlights, and supports explicit linear and ACES selection. The technical preset selects linear mapping to retain a white background; studio presets use the default Filmic mapping. Older builds warn when this support is unavailable. The flat unlit path bypasses post-processing. Viser uses its browser tone mapper.

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),
    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)

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
)

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, config=RendererConfig(colors=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

Geometry and multi-robot layouts¶

config.geometry sets backbone and cross-section sample counts, swept or discrete geometry, base plate dimensions, line widths and automatic robot spacing. Base poses and runtime configurations determine the robot geometry; scene settings only control its display. Increase sample counts for smoother exported surfaces.

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 config.geometry.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 interactive 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 uses instanced or color-grouped meshes for animation and PBR meshes for static output. Automatically sized ground planes use the complete trajectory and helper bounds.

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

Output and recording¶

RenderOutputConfig selects image dimensions and default video encoding:

from soromox.rendering import RenderOutputConfig, VideoEncodingConfig

config.output = RenderOutputConfig(
    width=1920, height=1080,
    video=VideoEncodingConfig(codec="libx264", crf=18, pix_fmt="yuv420p"),
)

Set this before constructing the renderer. A per-call video_config replaces config.output.video for that operation. Supply record_path to render_sequence() to export a video or, where supported, an image sequence. Open3D export is synchronous; a sequence without a recording path opens animated playback. See the renderer API for backend-specific operations.

Backend support¶

Unsupported requested features produce one warning per renderer and mode.

On the tested patched Open3D 0.20 macOS build, opening a legacy OpenGL preview after a modern Metal GUI window can crash upstream GLFW. SoRoMoX rejects that transition with a clear error; launch the animated preview in a fresh Python process. Modern image and video exports and static windows are available independently.

Physical light units do not imply identical images: environment illumination, material models, tone mapping and shadow algorithms differ. Filament supports one dominant directional light; additional directional lights produce a warning. Presets use one directional key plus point lights for fill and rim illumination; they do not reproduce area-light reflections, subsurface scattering or reference-image compositing.

See the preset comparison gallery for actual tentacle renders, references and backend differences.

Configuration API¶

All public settings are available from soromox.rendering.config and re-exported from soromox.rendering. Their implementation is organized by responsibility:

base.py implements shared rendering behavior. Backend scene handles and recording state stay with their renderers; video_encoding.py implements the FFmpeg writer.

CameraConfig(exposure_ev100: float = 15.0, 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 = 1.5, 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 with more space around the scene
camera = CameraConfig(distance_factor=2.0)

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

compute_up() -> ndarray

ActuatorStyleConfig(default_color: tuple[float, float, float] = (0.9, 0.15, 0.15), default_radius: float | None = None, scalar_colormap: str = 'viridis', kind_colors: Mapping[str, tuple[float, float, float]] = dict(), kind_radii: Mapping[str, float] = dict())

color_for_kind(kind: str) -> tuple[float, float, float]

radius_for_kind(kind: str) -> float | None

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)

RendererColorConfig(robot_override: tuple[float, float, float] | None = None, backbone: BackboneColorConfig = BackboneColorConfig(), base_plate_color: tuple[float, float, float] = (0.2, 0.2, 0.2), actuators: ActuatorStyleConfig = ActuatorStyleConfig())

RenderOutputConfig(width: int = 800, height: int = 600, video: VideoEncodingConfig = VideoEncodingConfig())

__post_init__() -> None

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, ...] = ())

GeometryConfig(num_points: int = 80, cross_section_resolution: int = 48, backbone_style: Literal['swept', 'discrete'] = 'swept', base_plate_style: Literal['disk', 'beveled_disk', 'truncated_cone', 'flared_collar'] = 'flared_collar', base_plate_radius_scale: float = 2.0, base_plate_thickness: float = 0.06, line_width: float | None = 4.0, actuator_line_width: float = 2.0, grid_spacing: tuple[float, float] = (0.5, 0.5))

__post_init__() -> None

RendererConfig(scene: SceneConfig = technical(), camera: CameraConfig = CameraConfig(), colors: RendererColorConfig = RendererColorConfig(), geometry: GeometryConfig = GeometryConfig(), output: RenderOutputConfig = RenderOutputConfig())

clay(color: RGB = (0.72, 0.65, 0.56), *, scene_extent: float = 1.2, **overrides: Any) -> RendererConfig

AmbientLightConfig(strength: float = 0.6, color: RGB = (1.0, 1.0, 1.0))

__post_init__() -> None

BackdropConfig(enabled: bool = False, width: float = 5.0, depth: float = 2.5, height: float = 2.5, radius: float = 0.5, wall_offset: float = 0.42, vertical_radius: float | None = None, curvature_easing: float = 0.0)

__post_init__() -> None

DirectionalLightConfig(direction: Vector3 = (-0.25, 0.15, -1.0), illuminance_lux: float = 60000.0, color: RGB = (1.0, 0.97, 0.94), cast_shadow: bool = True, reference: Literal['world', 'ground'] = 'world')

__post_init__() -> None

GroundPlaneConfig(visible: bool = True, surface: bool = True, alignment: Literal['world', 'base'] = 'world', height: float = 0.0, height_reference: Literal['world', 'base_mounting_face'] = 'world', normal: Vector3 | None = None, size: float | None = None, color: RGB = (0.94, 0.95, 0.96), opacity: float = 1.0, grid: bool = True, grid_spacing: float | None = None, grid_color: RGB = (0.86, 0.86, 0.86), grid_major_every: int = 5, grid_major_color: RGB = (0.72, 0.72, 0.72), receive_shadow: bool = True)

__post_init__() -> None

MaterialConfig(shading: Literal['standard', 'unlit', 'toon3', 'toon5'] = 'standard', roughness: float = 0.72, metallic: float = 0.0, reflectance: float = 0.35, opacity: float = 1.0, flat_shading: bool = False, wireframe: bool = False)

__post_init__() -> None

PointLightConfig(position: Vector3 = (-0.3, -0.4, 1.1), intensity_candela: float = 2785.21, color: RGB = (1.0, 0.98, 0.96), range_m: float = 4.0, cast_shadow: bool = False, reference: Literal['world', 'ground'] = 'world')

from_lumens(lumens: float, **kwargs: Any) -> PointLightConfig

__post_init__() -> None

SceneConfig(background: RGB = (1.0, 1.0, 1.0), ground: GroundPlaneConfig = (lambda: GroundPlaneConfig(surface=False))(), backdrop: BackdropConfig = BackdropConfig(), ambient: AmbientLightConfig = (lambda: AmbientLightConfig(strength=0.8))(), lights: tuple[DirectionalLightConfig | PointLightConfig, ...] = (lambda: (DirectionalLightConfig(reference='ground', illuminance_lux=80000, color=(1.0, 1.0, 1.0)), from_lumens(250000, reference='ground', position=(0.0, -0.8, 0.8), range_m=6.0)))(), material: MaterialConfig = MaterialConfig(), shadows: bool = False, ambient_occlusion: bool = False, tone_mapping: Literal['backend-default', 'linear', 'aces'] = 'backend-default', backbone_cast_shadow: bool = True, sphere_cast_shadow: bool = True)

__post_init__() -> None

technical(*, scene_extent: float = 1.2, **overrides: Any) -> SceneConfig

flat(**overrides: Any) -> SceneConfig

studio(style: Literal['neutral', 'bright', 'dark'] = 'neutral', *, scene_extent: float = 1.2, **overrides: Any) -> SceneConfig

Light orientation for hanging scenes¶

Preset directional and point lights use reference="ground", resolving their vectors through the same basis as the backdrop. GroundPlaneConfig(normal=(0, 0, -1)) rotates that basis by 180 degrees about world Y. For tilted normals, backdrop depth follows world +Y projected into the ground plane, avoiding a sign flip when the normal crosses the XY plane. At normals parallel to world Y, depth is undefined and the basis uses world +X for width; this reference-axis singularity cannot provide a continuous orientation for every approach direction. Custom lights default to reference="world", preserving explicit world positions and directions. Ground-relative point positions are measured from the world origin; ground height does not translate them. Preset intensity and range retain the existing scene_extent scaling.

The gallery's --mounting hanging also rotates robot placement and camera position, while retaining camera up at +z for an upside-down composition. Merely changing the camera up vector rolls the image; it does not change the robot's world mounting or the ground normal. Open3D's fixed environment map may produce ambient shading differences between mounting orientations.