Upload your first scene

4min
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.
This guide will walk you through the process of uploading your first scene, either in 2D (camera only) or 3D (camera and LiDAR/RADAR).
Prerequisites
You have successfully followed the Quickstart﻿ 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.﻿﻿
Code examples
To upload a 2D scene, you need to have the raw images available on your local machine (or create a callback﻿ for remote data).
It is a two-step process:
Build the scene object in Python
Upload the scene object to the Kognic Platform
Below follows examples for a few different cases.
One Image
Multiple Images
Sequence
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras import Cameras, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = Cameras(
    external_id="my-first-scene",
    frame=Frame(images=[Image(filename="path/to/image.jpg")])
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras import Cameras, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = Cameras(
    external_id="my-first-scene",
    frame=Frame(images=[Image(filename="path/to/image.jpg")])
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras import Cameras, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = Cameras(
    external_id="my-first-scene",
    frame=Frame(
        images=[
          # Sensor names must be unique
          Image(sensor_name = "CAM1", filename="path/to/image1.jpg"),
          Image(sensor_name = "CAM2", filename="path/to/image2.jpg")
        ],
    )
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras import Cameras, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = Cameras(
    external_id="my-first-scene",
    frame=Frame(
        images=[
          # Sensor names must be unique
          Image(sensor_name = "CAM1", filename="path/to/image1.jpg"),
          Image(sensor_name = "CAM2", filename="path/to/image2.jpg")
        ],
    )
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras_sequence import CamerasSequence, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = CamerasSequence(
    external_id="my-first-scene",
    frames=[
        # Relative timestamps must be unique and strictly increasing
        Frame(
            relative_timestamp=0,
            frame_id="1",
            images=[Image(filename="path/to/image1.jpg")],
        ),
        Frame(
            relative_timestamp=100,
            frame_id="2",
            images=[Image(filename="path/to/image2.jpg")],
        ),
        Frame(
            relative_timestamp=200,
            frame_id="3",
            images=[Image(filename="path/to/image3.jpg")],
        ),
    ]
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras_sequence.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.scene.cameras_sequence import CamerasSequence, Frame
from kognic.io.model.scene.resources import Image

# 1. Build scene object
scene = CamerasSequence(
    external_id="my-first-scene",
    frames=[
        # Relative timestamps must be unique and strictly increasing
        Frame(
            relative_timestamp=0,
            frame_id="1",
            images=[Image(filename="path/to/image1.jpg")],
        ),
        Frame(
            relative_timestamp=100,
            frame_id="2",
            images=[Image(filename="path/to/image2.jpg")],
        ),
        Frame(
            relative_timestamp=200,
            frame_id="3",
            images=[Image(filename="path/to/image3.jpg")],
        ),
    ]
)

# 2. Upload scene
client = KognicIOClient()
scene_uuid = client.cameras_sequence.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
﻿
To upload a 2D/3D scene, you need to have the raw images and point clouds available on your local machine (or create a callback﻿ for remote data).
In addition you need to have calibration data available.
It is a three-step process:
Create a calibration﻿ 
Build the scene object in Python, referencing the calibration from the previous step
Upload the scene object to the Kognic Platform
Below follows examples for a few different cases.
One Image
Multiple Images
Sequence
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras import LidarsAndCameras, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCameras(
    external_id=f"my-first-scene",
    calibration_id = created_calibration.id,
    frame=Frame(
        images=[Image(sensor_name = "CAM", filename="path/to/image.jpg")],
        point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud.pcd")]
    )
)

# 3. Upload scene
scene_uuid = client.lidars_and_cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras import LidarsAndCameras, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCameras(
    external_id=f"my-first-scene",
    calibration_id = created_calibration.id,
    frame=Frame(
        images=[Image(sensor_name = "CAM", filename="path/to/image.jpg")],
        point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud.pcd")]
    )
)

# 3. Upload scene
scene_uuid = client.lidars_and_cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras import LidarsAndCameras, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM1": PinholeCalibration(...),
        "CAM2": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCameras(
    external_id="my-first-scene",
    calibration_id = created_calibration.id,
    frame=Frame(
        images=[
          Image(sensor_name = "CAM1", filename="path/to/image1.jpg"),
          Image(sensor_name = "CAM2", filename="path/to/image2.jpg"),
        ],
        point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud.pcd")]
    )
)

# 3. Upload scene
client = KognicIOClient()
scene_uuid = client.lidars_and_cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras import LidarsAndCameras, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM1": PinholeCalibration(...),
        "CAM2": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCameras(
    external_id="my-first-scene",
    calibration_id = created_calibration.id,
    frame=Frame(
        images=[
          Image(sensor_name = "CAM1", filename="path/to/image1.jpg"),
          Image(sensor_name = "CAM2", filename="path/to/image2.jpg"),
        ],
        point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud.pcd")]
    )
)

# 3. Upload scene
client = KognicIOClient()
scene_uuid = client.lidars_and_cameras.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
Python
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras_sequence import LidarsAndCamerasSequence, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
calibration = { "CAM": PinholeCalibration(...), "lidar": LidarCalibration(...) }
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCamerasSequence(
    external_id="my-first-scene",
    calibration_id = created_calibration.id,
    frames=[
        # Relative timestamps must be unique and strictly increasing
        Frame(
            relative_timestamp=0,
            frame_id="1",
            images=[Image(sensor_name = "CAM", filename="path/to/image1.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud1.pcd")]
        ),
        Frame(
            relative_timestamp=100,
            frame_id="2",
            images=[Image(sensor_name = "CAM", filename="path/to/image2.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud2.pcd")]
        ),
        Frame(
            relative_timestamp=200,
            frame_id="3",
            images=[Image(sensor_name = "CAM", filename="path/to/image3.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud3.pcd")]
        ),
    ]
)

# 3. Upload scene
scene_uuid = client.lidars_and_cameras_sequence.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
from kognic.io.client import KognicIOClient
from kognic.io.model.calibration import SensorCalibration, PinholeCalibration, LidarCalibration
from kognic.io.model.scene.lidars_and_cameras_sequence import LidarsAndCamerasSequence, Frame
from kognic.io.model.scene.resources import Image, PointCloud

client = KognicIOClient()

# 1. Create calibration (see calibration section for more details)
calibration = { "CAM": PinholeCalibration(...), "lidar": LidarCalibration(...) }
sensor_calibration = SensorCalibration(
    external_id = "my-first-calibration",
    calibration = {
        "CAM": PinholeCalibration(...),
        "lidar": LidarCalibration(...)
    }
)
created_calibration = client.calibration.create_calibration(sensor_calibration)

# 2. Build scene object
scene = LidarsAndCamerasSequence(
    external_id="my-first-scene",
    calibration_id = created_calibration.id,
    frames=[
        # Relative timestamps must be unique and strictly increasing
        Frame(
            relative_timestamp=0,
            frame_id="1",
            images=[Image(sensor_name = "CAM", filename="path/to/image1.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud1.pcd")]
        ),
        Frame(
            relative_timestamp=100,
            frame_id="2",
            images=[Image(sensor_name = "CAM", filename="path/to/image2.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud2.pcd")]
        ),
        Frame(
            relative_timestamp=200,
            frame_id="3",
            images=[Image(sensor_name = "CAM", filename="path/to/image3.jpg")],
            point_clouds=[PointCloud(sensor_name = "lidar", filename="path/to/pointcloud3.pcd")]
        ),
    ]
)

# 3. Upload scene
scene_uuid = client.lidars_and_cameras_sequence.create(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
﻿
Multiple point clouds is also supported, but not shown in the examples above since that requires a bit more data. See the Motion compensation﻿ section for more details.
﻿
We have exemplar code and a tutorial for uploading scenes using Zenseact Open Dataset (ZOD) data, including 2D, 3D, and aggregated 3D scenes. Check out the guide document and exemplar code here!﻿﻿
If you have the ZOD data downloaded, and have Kognic API credentials, the examples will run out of the box to create functional scenes!
To use the below install koginc io version >=2.5.1
The model and method used for creating a scene this way is slightly different from the above. All scenes are considered sequences and there is no need to use a specific model for different scene types.
To use this feature need to have configured a data integration﻿ .
If you have your data in a kognic supported format on bucket that you have set up a data integration for, then there is no need for you to download you data locally to then upload it to kognic. Instead it's sufficent to point out the files in your bucket.
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=1742225790, # Absolute unix timestamp of frame
      images=[
        ImageResource(
          external_resource_uri="<uri>", # Matching your data integration, e.g s3://my-bucket/some_image.jpg
          sensor_name="my_camera",
          local_file=None
        )
      ],
    )
  ],
  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)
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=1742225790, # Absolute unix timestamp of frame
      images=[
        ImageResource(
          external_resource_uri="<uri>", # Matching your data integration, e.g s3://my-bucket/some_image.jpg
          sensor_name="my_camera",
          local_file=None
        )
      ],
    )
  ],
  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)
﻿
To use this feature need to have configured a data integration﻿ .
If you have your data in a kognic supported format on bucket that you have set up a data integration for, then there is no need for you to download you data locally to then upload it to kognic. Instead it's sufficent to point out the files in your bucket.
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,
      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,
        )
      ],
      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="<uri>",
      local_file=None
  ),
  sensor_specification=None,
  should_motion_compensate=False,
  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)
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,
      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,
        )
      ],
      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="<uri>",
      local_file=None
  ),
  sensor_specification=None,
  should_motion_compensate=False,
  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)
﻿
This model also allows you to upload imu data, which is expected as a json file containing the following format:
JS
[
 {
  "postion": {
   "x": 0.0,
   "y": 0.0,
   "z": 0.0
  },
  "rotationQuaternion": {
   "w": 0.0,
   "x": 0.0,
   "y": 0.0,
   "z": 0.0
  }
  "timestamp": <unix timestamp in nano seconds>
 },
 ...
]
[
 {
  "postion": {
   "x": 0.0,
   "y": 0.0,
   "z": 0.0
  },
  "rotationQuaternion": {
   "w": 0.0,
   "x": 0.0,
   "y": 0.0,
   "z": 0.0
  }
  "timestamp": <unix timestamp in nano seconds>
 },
 ...
]
﻿
﻿
﻿
﻿
﻿
Key concepts
Cameras
Upload your first scene

Prerequisites

Code examples

Uploading a 2D scene

Uploading a 2D/3D scene

Uploading using ZOD Data

Creating a 2D scene from bucket

Creating a 2D/3D scene from buckets
