Create and Register Scenes

A Scene is the Encord data unit that contains 3D sensor data. It can contain point clouds, such as LiDAR and radar point clouds, camera images, camera calibration, and vehicle or robot poses. Annotators open Scenes as tasks for 3D labeling and review.

For the supported point cloud and container formats, see Supported data formats.

Goal	Scene shape	Use when
Label one scan	Single point cloud stream	You have one .pcd, .ply, .las, .laz, .e57, or similar point cloud asset.
Label a sequence	Point cloud stream with frame timestamps	You have multiple point cloud frames from the same sensor.
Label multimodal sensor data	Point clouds plus image streams, camera parameters, and frames of reference	You need camera projections, synchronized views, or vehicle/sensor calibration.

Register a Scene with the SceneBuilder

Use the SceneBuilder for Scene registration whenever possible. It validates stream references before upload and keeps you from hand-maintaining large JSON payloads. See Scene SDK workflow for the full documentation on the SceneBuilder

Create or load a StorageFolder and cloud integration ID with the Python SDK, then use the SceneBuilder to build and upload the Scene. For method-level details, see the SceneBuilder reference.

Build and Upload a Scene

from uuid import UUID

from encord.beta.scene import SceneBuilder, identity_pose, intrinsics_pinhole
from encord.storage import StorageFolder


def build_scene() -> SceneBuilder:
    scene = SceneBuilder()

    # Anchor the sensor streams to the moving platform.
    ego = scene.add_for_stream("ego")
    ego.add_pose(identity_pose(), timestamp=0)

    # Matching timestamps make the point cloud and image appear together.
    scene.add_pcd_stream("lidar", frame_of_reference=ego).add_pcd(
        uri="s3://my-bucket/scenes/scene-001/lidar/000000.pcd",
        timestamp=0,
    )

    # Inline camera parameters create a camera stream named "front/camera".
    scene.add_image_stream(
        "front",
        width=1920,
        height=1080,
        intrinsics=intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        timestamp=0,
        frame_of_reference=ego,
    ).add_image(
        uri="s3://my-bucket/scenes/scene-001/front/000000.jpg",
        timestamp=0,
    )

    return scene


def register_scene(storage_folder: StorageFolder, integration_id: str) -> UUID:
    scene = build_scene()

    # Pass the SceneBuilder itself. upload_scene validates and serializes it internally.
    return storage_folder.upload_scene(
        scene=scene,
        title="scene-001",
        integration_id=integration_id,
        client_metadata={"source": "sample"},
    )

After registration, add the Scene item to a Dataset and create an annotation Project as you would for other data types.