---
title: Scene examples
slug: api-guide/scene-examples
docTags: 
createdAt: 2025-04-16T06:34:02.198Z
---

When uploading raw data to the Kognic Platform, you need to do so in the form of a **Scene**.
A scene is a collection of data from different sources, such as images, point clouds, and other sensor data.

In `kognic-io` 2.5.0 we released a new scene model that infers the scene type from the sensor data; if there are no pointclouds, a camera-only sequence is created.

:::hint{type="warning"}
Scenes created via this new model and its associated API will always be *sequences*, meaning they cannot be added to Requests that require non-sequence inputs. Over time, we expect to standardize on sequences everywhere, so this should become less of a concern over time.
:::

:::hint{type="info"}
There is no need to specify that a scene is aggregated with the new model, and we no longer support creation of so-called "pre-aggregated" scenes which contained a 'fat' pointcloud in the first frame, and nothing in the rest. See [Aggregated Lidars and Cameras Sequence](docId\:Wk30FzM6vJvDcTDkX-Mgh) for details.
:::

You can read more detailed information about this model [here](docId\:ly3sRVEnccTNimJ3b9W-b).

# Create scene from local files

This guide will walk you through the process of uploading a scene where the sources are located on your computer.

## Prerequisites

You have successfully followed the [Quickstart](docId\:b6im5U-kiWn9UkybzJX6D) guide and have the `kognic-io` library installed. For users with access to multiple workspaces you need to [specify a workspace to upload data too.](docId\:xMGM2k-Teox9jtN_otqBM)

To upload scenes using cloud resources you need the following:

- kognic-io >= 2.5.1
- a [calibration](docId:4mFC9aTWcxuPfLNE7V1Iz) for your scene
- data locally in a [file format](docId\:rJCFQbi_5Abkcad_j7Mcw)  that kognic supports

## Examples

:::hint{type="info"}
Note that postpone\_external\_resource\_import has to be false when working with local files since kognic cannot maintain a reference to your local files and fetch them at a later time.
:::

:::ExpandableHeading
### Creating a 2D scene from local files

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225789000000000, # Absolute unix timestamp of frame
      images=[
        ImageResource(
          external_resource_uri=None,
          sensor_name="my_camera",
          local_file=LocalFile(filename="<path to your file>")
        )
      ],
    )
  ],
  postpone_external_resource_import=False
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```
:::

:::ExpandableHeading
### Creating a 2D/3D scene from local files

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource, SensorResource, Resource, EgoVehiclePose

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225790000000000,
      pointclouds=[
        SensorResource(
          external_resource_uri=None,
          sensor_name="my_lidar",
          local_file=LocalFile(filename="<path to your file>")
        )
      ],
      images=[
        ImageResource(
          external_resource_uri=None,
          sensor_name="my_camera",
          start_shutter_timestamp_ns=1742225789000000000,
          end_shutter_timestamp_ns=1742225790000000000,
          local_file=LocalFile(filename="<path to your file>"),
        )
      ],
      ego_vehicle_pose=EgoVehiclePose(
        x=0.0, y=0.0, z=0.0, rotation_x=0.0, rotation_y=0.0, rotation_z=0.0, rotation_w=1.0
      )
    )
  ],
  calibration_id="<calibration_id>",
  imudata_resource=Resource(
      external_resource_uri=None,
      local_file=LocalFile(filename="<path to your file>")
  ),
  sensor_specification=None,
  should_motion_compensate=False,
  postpone_external_resource_import=False
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```


:::

# Create scene from cloud resources

This guide will walk you through the process of uploading a scene where the sources are located on a bucket that you have access to.

## Prerequisites

You have successfully followed the [Quickstart](docId\:b6im5U-kiWn9UkybzJX6D) guide and have the `kognic-io` library installed. For users with access to multiple workspaces you need to [specify a workspace to upload data too.](docId\:xMGM2k-Teox9jtN_otqBM)

To upload scenes using cloud resources you need the following:

- kognic-io >= 2.5.1
- a valid [data integration](docId\:L93_PNIEAhqPK-6j-OuEF)
- a [calibration](docId:4mFC9aTWcxuPfLNE7V1Iz) for your scene
- data on your bucket in a [file format](docId\:rJCFQbi_5Abkcad_j7Mcw)  that kognic supports

## Overview

Instead of providing `local_file=LocalFile(...)` on each resource (image, pointcloud, IMU data) you will instead leave `local_file=None` and provide `external_resource_uri` using the native format of your cloud platform i.e. a `gs://` or `s3://` URL.

## Example

The example shows a full 2D+3D scene with IMU data an Ego vehicle poses. It can be reduced to a 2D-only scene by removing the IMU, ego and pointclouds.

Import may be deferred via `postpone_external_resource_import` creating so called 'Indexed' scenes. ('Indexed' because we only keep an index of what could be in the system and do not fetch the data until the scene is used or manually requested later.)

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource, SensorResource, Resource, EgoVehiclePose

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225790,
      # For 2D-only scenes, omit pointclouds entirely.
      pointclouds=[
        SensorResource(
          external_resource_uri="<uri>",
          sensor_name="my_lidar",
          local_file=None,
        )
      ],
      images=[
        ImageResource(
          external_resource_uri="<uri>",
          sensor_name="my_camera",
          start_shutter_timestamp_ns=1742225789,
          end_shutter_timestamp_ns=1742225790,
          local_file=None,
        )
      ],
      # For 2D-only scenes, omit ego_vehicle_pose entirely.
      ego_vehicle_pose=EgoVehiclePose(
        x=0.0, y=0.0, z=0.0, rotation_x=0.0, rotation_y=0.0, rotation_z=0.0, rotation_w=1.0
      )
    )
  ],
  calibration_id="<calibration_id>",
  # For 2D scenes, omit imudata_resource entirely.
  imudata_resource=Resource(
      external_resource_uri="<uri>",
      local_file=None
  ),
  sensor_specification=None,
  should_motion_compensate=False, # Omit for 2D, optionally set for 3D+2D
  postpone_external_resource_import=False, # Set true if you want to import at a later point in time
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```