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.

Scenes can be created in Encord by either:

• Referencing a single .mcap file (Beta)
• Creating a Composite Scene to reference existing files in your cloud bucket.

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

Upload an .mcap file directly

MCAP support is in Beta. Contact your Encord support representative to enable the feature for your Organization.

If your sensor data is already in an .mcap recording, you can upload the file directly. Upload the file in Encord Files & Folders, or use the SDK to upload a local file or register a file from cloud storage:

Upload an MCAP file to Encord

# Import dependencies
from encord import EncordUserClient
from encord.storage import StorageFolder

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique ID for the folder in Files & Folders
MCAP_FILE_PATH = "/Users/chris-encord/recording.mcap"  # Replace with the file path to your MCAP recording
SCENE_TITLE = "Robot recording"  # Replace with the title for the Scene

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get the folder
folder: StorageFolder = user_client.get_storage_folder(FOLDER_ID)

# Upload the MCAP recording as a Scene
scene_uuid = folder.upload_scene_file(file_path=MCAP_FILE_PATH, title=SCENE_TITLE)
print(f"Uploaded Scene item {scene_uuid}")

See MCAP Support for supported schemas, size guidance, custom layouts, and label import/export.

Register a Composite Scene with the SceneBuilder

Use the SceneBuilder when your sensor streams live in separate files that you want to combine into a composite Scene. See Scene SDK workflow for the full documentation on the SceneBuilder

To register a composite Scene with the Python SDK:

1. Get the StorageFolder to register the Scene in, and the ID of a cloud integration that can read every file in the Scene.
2. Build the Scene with SceneBuilder: add a stream for each sensor, then add one event per file. Timestamps are whole-number frame indices that start at 0.
3. Register the Scene with StorageFolder.upload_scene. It returns the new Scene item’s UUID.

For a complete example, see Build and Upload a Composite Scene. For method-level details, see the SceneBuilder reference.

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