Documentation
Search…
Sample formats
A sample is a data point you want to label. Samples come in different types, like an image, a 3D point cloud, or a video sequence. When uploading (client.add_sample()) or downloading (client.get_sample()) a sample using the Python SDK, the format of the attributes field depends on the type of sample. The different formats are described here.
The section Import data shows how you can obtain URLs for your assets.

Image

Supported image formats: jpeg, png, bmp.
{
"image": {
"url": "https://example.com/image.jpg"
}
}

Image sequence

Supported image formats: jpeg, png, bmp.
{
"frames": [
{
"image": {
"url": "https://example.com/frame_00001.jpg"
},
"name": "frame_00001" // optional
},
{
"image": {
"url": "https://example.com/frame_00002.jpg"
},
"name": "frame_00002"
},
{
"image": {
"url": "https://example.com/frame_00003.jpg"
},
"name": "frame_00003"
}
]
}

3D point cloud

{
"pcd": {
"url": "https://example.com/pointcloud.bin",
"type": "kitti" // optional, "pcd" by default
},
"name": "frame_00001", // optional
"timestamp": "00001", // optional
"ego_pose": {
"position": {
"x": -2.7161461413869947,
"y": 116.25822288149078,
"z": 1.8348751887989483
},
"heading": {
"qx": -0.02111296123795955,
"qy": -0.006495469416730261,
"qz": -0.008024565904865688,
"qw": 0.9997181192298087
}
},
"default_z": -1 // optional, 0.5 by default
}
Name
Type
Description
pcd
Required. Point cloud data.
name
string
Name of the sample.
timestamp
string
Timestamp of the sample.
ego_pose
Ego pose
Pose of the sensor that captured the point cloud data.
default_z
float
Default z-value of a cuboid. 0.5 by default. Only valid in the point cloud cuboid editor. A cuboid has a height of 1 by default, so the ground plane is located 0.5 under the default z-value.

Point cloud data

See 3D point cloud formats for the supported file formats.
{
"url": "https://example.com/pointcloud.bin",
"type": "kitti" // optional, "pcd" by default
}
Name
Type
Description
url
string
Required. URL of the point cloud data.
type
string: "pcd" | "binary-xyzi" | "kitti" | "binary-xyzir" | "nuscenes"
Type of the point cloud data. "pcd" by default. See 3D point cloud file formats for the list of supported file formats.

Ego pose

The pose of the sensor used to capture the 3D point cloud data. This can be helpful if you want to obtain cuboids in world coordinates, or when your sensor is moving. In the latter situation, supplying an ego pose with each frame will ensure that static objects do not move when switching between frames.
{
"position": {
"x": -2.7161461413869947,
"y": 116.25822288149078,
"z": 1.8348751887989483
},
"heading": {
"qx": -0.02111296123795955,
"qy": -0.006495469416730261,
"qz": -0.008024565904865688,
"qw": 0.9997181192298087
}
},
Name
Type
Description
position
object: { "x": float, "y": float, "z": float }
XYZ position of the sensor in world coordinates.
heading
object: { "qx": float, "qy": float, "qz": float,
"qw": float }
Orientation of the sensor. Defined as a rotation quaternion.

3D point cloud sequence

{
"frames": [
{ ... },
{ ... },
{ ... }
]
}
Name
Type
Description
frames
array of 3D point clouds
Required. List of 3D point cloud frames in the sequence.

Text

{
"text": "Example text sample."
}
Name
Type
Description
text
string
Required. Text data.
To upload text samples in bulk, see file formats.