Component mappings

By default, each visualizer reads its input components from the - for example, the Points3D visualizer reads colors from Points3D:colors. Component mappings let you override this, redirecting any visualizer input to a different component on the same entity. This makes it possible to store multiple variants of the same data and switch between them per view.

To learn more about how visualizers are set up in general, also have a look at the concept page on customizing Views.

This guide uses a point cloud with two color sets as a running example, but the same technique works for any component!

Full example full-example

You can find the full example here:

🐍 Python
🦀 Rust

How it works how-it-works

Storing multiple component variants with custom archetypes storing-multiple-component-variants-with-custom-archetypes

A standard archetype like Points3D assigns a fixed column name, as well as component type & archetype metainformation, to every component it logs (Points3D:colors, Points3D:positions, etc.). To store additional variants of a component on the same entity, log them as custom archetypes. The easiest way to do this is to use the DynamicArchetype utility.

# --- Log positions once, then each color set as a separate custom archetype ---
rr.log(
    "pointcloud",
    rr.Points3D(positions, radii=0.06),
    rr.DynamicArchetype("HeightColors", components={"colors": rr.components.ColorBatch(height_rgba)}),
    rr.DynamicArchetype("SpinColors", components={"colors": rr.components.ColorBatch(spin_rgba)}),
)

After this call, the entity's component list contains four components:

Points3D:positions, Points3D:radii — from the standard archetype
HeightColors:colors — the first custom variant
SpinColors:colors — the second custom variant

You can inspect this in the viewer by selecting the entity in the streams panel:

Configuring component mappings in blueprint configuring-component-mappings-in-blueprint

To make a visualizer read from an arbitrary source, we need to explicitly set the component mapping for a visualizer. The mapping specifies a target (the component the visualizer expects) and a source (the component to actually read from). Everything that isn't explicitly mapped keeps its default behavior.

# --- Blueprint: two side-by-side 3D views with different color mappings ---
blueprint = rrb.Blueprint(
    rrb.Horizontal(
        rrb.Spatial3DView(
            name="Height Colors",
            origin="/",
            overrides={
                "pointcloud": [
                    rr.Points3D.from_fields().visualizer(
                        mappings=[
                            VisualizerComponentMapping(
                                target="Points3D:colors",
                                source_kind=ComponentSourceKind.SourceComponent,
                                source_component="HeightColors:colors",
                            ),
                        ]
                    ),
                ],
            },
        ),
        rrb.Spatial3DView(
            name="Spin Colors",
            origin="/",
            overrides={
                "pointcloud": [
                    rr.Points3D.from_fields().visualizer(
                        mappings=[
                            VisualizerComponentMapping(
                                target="Points3D:colors",
                                source_kind=ComponentSourceKind.SourceComponent,
                                source_component="SpinColors:colors",
                            ),
                        ]
                    ),
                ],
            },
        ),
    ),
    collapse_panels=True,
)

rr.send_blueprint(blueprint)

In this example, each view overrides only the color source for the Points3D visualizer - positions, radii, and everything else are still read from their default sources automatically.

In the viewer you can access and this in the visualizer settings, presented when selecting an entity in a view:

Configuring component mappings in the UI configuring-component-mappings-in-the-ui

You can set up the same mappings interactively without writing any blueprint code: