---
title: Scenes
slug: api-guide/scenes
docTags: 
createdAt: 2025-05-15T06:11:08.419Z
---

:::hint{type="info"}
This applies to users of kognic-io>2.5.0. If you're using a earlier version, look at the [legacy documentation](docId\:yUnPNPwUhZlGG9Wb9Qnk8)  or upgrade.
:::

The scene is how Kognic groups sensor resources together across a period of time (frames).

The scene model starts with a `SceneRequest` :

```python
class SceneRequest:
    """A scene request is used to create a scene in the Kognic platform.

    Attributes:
        workspace_id (str): The ID of the workspace where the scene will be created.
        external_id (str): The external ID of the scene.
        frames (List[Frame]): A list of frames that make up the scene.
        sensor_specification (Optional[SensorSpecification]): Sensor specification let's the user set the order and display names of the sensors.
        calibration_id (Optional[Calibration]): Calibration of the scene, required if the scene contains pointclouds.
        metadata (Optional[dict]): Metadata for the scene.
        imudata_resource (Optional[Resource]): IMU data of the scene, required for aggregation and motion compensation.
        should_motion_compensate (Optional[bool]): Whether to motion compensate the scene.
        postpone_external_resource_import (Optional[bool]): Whether to postpone the import of external resources. Only available for scenes with external resources.
    """
    workspace_id: str
    external_id: str
    frames: List[Frame]
    sensor_specification: Optional[SensorSpecification] = None
    calibration_id: Optional[str] = None
    metadata: Optional[dict] = None
    imudata_resource: Optional[Resource] = None
    should_motion_compensate: Optional[bool] = None
    postpone_external_resource_import: Optional[bool] = None
```

The **workspace id** is used to specify in which workspace to create the scene, you can read more about workspaces [here](docId\:YBgkK5zAWzVfUHnD9Sq-L) .

The **external id** helps the user to communicate about the scene without refering to the long UUID generated by kognic. The UUID is however the primary key and will be needed to take actions on the scene.

**Frames** is how time is captured by the scene, each frame corresponds to a timestamp with  sensor data (IMU data is not included in these sensors as it's usually much higher frequency). We will look closer at frames below.

**Sensor specifications** is a configuration for how to display the sensors. Here you can set an order of your different sensors and give them human friendly display names.

**Calibrations** are used when 1 or more lidar resource is provided. The calibration has to exist before you can create a scene with it. You can read more about calibrations [here](docId:4mFC9aTWcxuPfLNE7V1Iz).

**Metadata** is just a flat dictionary where you can add additional data about the scene.

**IMU data** is used for motion compensation of multi-lidar pointclouds. You can find the IMU format [here](docId\:rJCFQbi_5Abkcad_j7Mcw).

**Should motion compensate flag** is used to determine if the scene should be motion compensated or not.

**Postpone external resource import** determines if the Kognic platform should start processing the scene immediatly and thus read the cloud resource that you have provided. Therefore this flag only has effect if using external resources. If set to `true` the scene will be created in the indexed status. You can read more about indexed scenes here.

## Frame

The frame object contains most of the information of the scene, and looks as follows:

```python
class Frame:
    """A frame is a collection of images and pointcloud at a given timestamp.

    Attributes:
        frame_id (str): The ID of the frame.
        timestamp_ns (int): The timestamp of the frame in nanoseconds.
        images (List[ImageResource]): A list of images in the frame.
        pointclouds (Optional[List[SensorResource]]): A list of pointclouds in the frame.
        ego_vehicle_pose (Optional[EgoVehiclePose]): The pose of the ego vehicle at the time of the frame, required if providing
         pointclouds.
        metadata (Optional[dict]): Metadata for the frame.
    """

    frame_id: str
    timestamp_ns: int
    images: List[ImageResource]
    pointclouds: Optional[List[SensorResource]] = None
    ego_vehicle_pose: Optional[EgoVehiclePose] = None
    metadata: Optional[dict] = None
```

## Resouces

The resource are all extensions of the base resource. The base resource exists to provide a few different modes of specifying data. The modell looks as follows:

```python
class Resource:
    external_resource_uri: Optional[str]
    local_file: Optional[LocalFile]
    
class LocalFile:
    filename: str
    data: Optional[bytes] = None
    callback: Optional[Callback] = None
```

The resource can either have an external\_resource\_uri, which is a URI pointing to a [data integration](docId\:L93_PNIEAhqPK-6j-OuEF), or a local file. For the external\_resource\_uri to work you need to have set up a data integration as specified in the link.
A local file can be provided in three ways, by filename, by bytestream (data) or by a callback that returns a byte stream. In all cases the filename needs to be provided as it's used to identify the resource by the Kognic platform.

## Indexed scenes

Sometimes it's useful to not to have to upload data to Kognic before you need it. For example if you have a huge dataset of which you might only want to look at a subset, but you don't know at upload time which scenes you need to look at. Uploading your entire dataset would incur a large amount of egress as data moves from your cloud to the Kognic cloud. Therefore we have introduced indexed scenes, where you can specify the scene and only import it when you need it.
For an indexed scene you need to have created a [data integration](docId\:L93_PNIEAhqPK-6j-OuEF), which tells kognic how to access data in your cloud.
This lets you just create the specification for the scene, which resources belongs to which frame, if it has a calibration etc and Kognic can store it but don't have to read the resources just yet.
When you need to do something with the scene in the Kognic platform you can make it available with a click or a button or through an API call. Kognic will then read the resources from your cloud and process and store them in Kognic's cloud.

# Examples

## Creating scenes

For examples check out [Scene examples](docId\:HxbEKMQTar-nCcl7pmGxr)

## Listing scenes

```python
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)
```

## Import indexed scene

When a scene is in the indexed state it can be imported or "made available". There is a method for this in kognic-io

```python
client.scene.import_indexed_scene("cca60a67-cb68-4645-8bae-00c6e6415555"
```

## Reindex scene

If you no longer want Kognic to store the data for an indexed scene but do not want to delete the scene entirely you can reindex it i.e. put it back to the indexed state by running:

```python
client.scene.reindex_scene("cca60a67-cb68-4645-8bae-00c6e6415555"
```