Beta.scene.builder

Builder API for constructing Encord scene payloads.

Provides a multi-stage builder pattern for assembling scene data. Each stream type has its own nested builder, and event timestamps are assigned sequentially.

Stages:

1. Create a SceneBuilder and (optionally) configure global settings.
2. Add one or more streams — each add_*_stream call returns a nested stream builder.
3. Populate streams with events via the stream-specific method (add_pcd, add_image, add_camera_params, add_pose).
4. Pass the builder to SDK upload/create methods, which validates and serializes internally.

Every mutator returns self, so stream-local calls can be chained fluently::

scene = SceneBuilder() scene.add_pcd_stream(“lidar”).add_pcd(uri=“s3://bucket/frame0.pcd”)

SceneBuilder Objects

class SceneBuilder()

Top-level builder for constructing an Encord scene payload.

Supported stream types:

• Point cloud — add_pcd_stream()
• Camera parameters — add_camera_stream()
• Frame of reference — add_for_stream()
• Image — add_image_stream()

Stream names must be unique. Re-using a name raises an error.

The scene must contain at least one point-cloud or image stream, and every stream must have at least one event. _build validates and serializes builders internally for SDK upload/create methods.

set_world_convention

def set_world_convention(*, x: Direction, y: Direction,
                         z: Direction) -> SceneBuilder

Set the world coordinate-system convention.

The three directions must map to three distinct spatial axes, forming a valid orthogonal coordinate system. The convention’s handedness (right-handed when cross(x, y) == z) must match the camera convention.

Available directions: Direction.UP, Direction.DOWN, Direction.LEFT, Direction.RIGHT, Direction.FORWARD, Direction.BACKWARD.

set_camera_convention

def set_camera_convention(*, x: Direction, y: Direction,
                          z: Direction) -> SceneBuilder

Set the camera coordinate-system convention.

The three directions must map to three distinct spatial axes, forming a valid orthogonal coordinate system. The convention’s handedness must match the world convention.

Available directions: Direction.UP, Direction.DOWN, Direction.LEFT, Direction.RIGHT, Direction.FORWARD, Direction.BACKWARD.

add_pcd_stream

def add_pcd_stream(name: str,
                   *,
                   frame_of_reference: str | FoRStreamBuilder | None = None,
                   pose: Pose | None = None) -> PCDStreamBuilder

Add a point-cloud stream.

Arguments:

• name - Unique stream name.
• frame_of_reference - Optional FoR stream to link to.
• pose - Optional static pose for the sensor mount.

add_camera_stream

def add_camera_stream(name: str,
                      *,
                      frame_of_reference: str | FoRStreamBuilder | None = None,
                      pose: Pose | None = None) -> CameraStreamBuilder

Add a camera-parameters stream.

Arguments:

• name - Unique stream name.
• frame_of_reference - Optional FoR stream to link to.
• pose - Optional static pose for the sensor mount.

add_for_stream

def add_for_stream(name: str,
                   *,
                   parent_for_id: str | FoRStreamBuilder | None = None
                   ) -> FoRStreamBuilder

Add a frame-of-reference stream.

Arguments:

• name - Unique stream name. Other streams reference this stream via this name.
• parent_for_id - Optional parent FoR — either the stream name or a FoRStreamBuilder. If omitted, the stream is attached to the scene root.

add_image_stream

def add_image_stream(name: str,
                     *,
                     camera: str | None = None,
                     width: int | None = None,
                     height: int | None = None,
                     intrinsics: Intrinsics | None = None,
                     timestamp: float | None = None,
                     frame_of_reference: str | FoRStreamBuilder | None = None,
                     pose: Pose | None = None) -> ImageStreamBuilder

Add an image stream.

There are two modes:

1. Existing camera: pass camera="cam_stream_name" to link to an already-registered camera stream.
2. Inline camera: pass width, height, and intrinsics to auto-create a camera stream named {name}/camera.

Arguments:

• name - Unique stream name.
• camera - The stream name of a camera-parameters stream. Mutually exclusive with width/height/intrinsics.
• width - Image width in pixels (inline camera mode).
• height - Image height in pixels (inline camera mode).
• intrinsics - Camera intrinsics (inline camera mode).
• timestamp - Camera-parameters event timestamp (inline camera mode).
• frame_of_reference - Optional FoR linkage for the auto-created camera stream (only used in inline camera mode).
• pose - Optional static pose for the auto-created camera stream (only used in inline camera mode).