Transform metadata

A transform’s metadata field is a protobuf Struct of rendering attributes. The 3D scene reads seven keys from it and ignores every other key. If a visual renders with default styling, check the key names and formats on this page first: an unrecognized key fails silently.

Metadata affects rendering only. The motion planner reads its geometry from the frame system and the WorldState you pass to Move, so no metadata key changes what the planner plans around.

The keys the scene reads

KeyTypeWhat it controls
colorsstring (base64)Fill color, or one color per point for point cloud geometry.
color_formatnumberHow the color bytes are laid out. The draw library writes the RGB format.
opacitiesstring (base64)Transparency, 0 (invisible) to 255 (opaque). One byte, or one byte per point.
show_axes_helperboolDraws a coordinate triad at the visual’s origin.
invisibleboolHides the visual by default; the viewer can re-enable it in the World panel.
chunksobjectStreams a large entity in pieces: chunk_size, total, and stride.
relationshipslistLinks this entity to others, which powers features such as HoverLink.

Color and opacity wire format

The binary values travel as base64-encoded strings, because a protobuf Struct has no bytes type:

  • colors packs 3 bytes per color, in R, G, B order. A single color styles the whole shape; for point cloud geometry, supply one color per point.
  • opacities packs 1 byte per value. A single byte applies one opacity to the whole visual; a byte per point sets per-point transparency.

Produce metadata with the draw library

The draw library encodes these formats for you, so producer code sets options instead of packing bytes:

import "github.com/viam-labs/motion-tools/draw"

// Red at half opacity. WithName, WithHex, WithRGB, and WithHSV also build colors.
drawn, err := draw.NewDrawnGeometry(
    box,
    draw.WithGeometryColor(draw.NewColor(draw.WithRGBA(255, 0, 0, 128))),
)

WithMetadataColors, WithMetadataAxesHelper, and WithMetadataInvisible set the corresponding keys on a drawing. When you assemble the Struct in another language, follow the wire formats in the table above.

What’s next