> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sdk-documentation/sdk-references/beta.scene.builder#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

```python theme={"dark"}
class SceneBuilder()
```

Top-level builder for constructing an Encord scene payload.

Supported stream types:

* **Point cloud** -- [add\_pcd\_stream()](/sdk-documentation/sdk-references/add_pcd_stream#add_pcd_stream)
* **Camera parameters** -- [add\_camera\_stream()](/sdk-documentation/sdk-references/add_camera_stream#add_camera_stream)
* **Frame of reference** -- [add\_for\_stream()](/sdk-documentation/sdk-references/add_for_stream#add_for_stream)
* **Image** -- [add\_image\_stream()](/sdk-documentation/sdk-references/add_image_stream#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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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](/sdk-documentation/sdk-references/beta.scene.builder#forstreambuilder). If omitted, the stream is
  attached to the scene root.

#### add\_image\_stream

```python theme={"dark"}
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).