LiDAR JSON Format

  • Updated On Oct 29, 2025
  • Published on May 1, 2022
Prev Next

This page describes LiDAR JSON, a data format for describing LiDAR data in JavaScript Object Notation (JSON).

Dataloop's LiDAR application supports 3D cubes. Since Dataloop's platform supports LiDAR sequence files, the JSON file contains information about the frames, the start time, and the end time.

For more information on LiDAR, see LiDAR Annotation Studio.

LiDAR JSON Format

{
  "id": "656d78cc97c4a3bd5a863b6b",
  "datasetId": "6458d7e0a4aaff79f2f8e16f",
  "url": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b",
  "dataset": "https://rc-gate.dataloop.ai/api/v1/datasets/6458d7e0a4aaff79f2f8e16f",
  "createdAt": "2023-12-17T16:23:14.232Z",
  "dir": "/",
  "filename": "/name.json",
  "type": "file",
  "hidden": false,
  "metadata": {
    "system": {
      "encoding": "7bit",
      "isBinary": false,
      "mimetype": "application/json",
      "modalities": [],
      "originalname": "frames (69).json",
      "refs": [
        {
          "id": "660d6132ee9acf5df05460c3",
          "type": "task"
        },
        {
          "id": "660d6135ee9acf25955460c5",
          "type": "assignment"
        }
      ],
      "shebang": {
        "dltype": "PCDFrames"
      },
      "size": 499149,
      "tags": {
        "validation": true
      },
      "taskStatusLog": []
    }
  },
  "name": "name.json",
  "creator": "name@dataloop.ai",
  "updatedAt": "2023-12-17T16:23:14.275Z",
  "updatedBy": "name@dataloop.ai",
  "stream": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b/stream",
  "thumbnail": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b/thumbnail",
  "annotations": [
    {
      "id": "6628d0a3d079e474881f026c",
      "datasetId": "6458d7e0a4aaff79f2f8e16f",
      "itemId": "656d78cc97c4a3bd5a863b6b",
      "url": "https://rc-gate.dataloop.ai/api/v1/annotations/6628d0a3d079e474881f026c",
      "item": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b",
      "dataset": "https://rc-gate.dataloop.ai/api/v1/datasets/6458d7e0a4aaff79f2f8e16f",
      "type": "ref_semantic_3d",
      "label": "A",
      "attributes": [],
      "coordinates": {
        "interpolation": "none",
        "mode": "overwrite",
        "ref": "6628d13df44c9ef04c78d6ba",
        "refType": "id"
      },
      "metadata": {
        "system": {
          "attributes": {},
          "automated": false,
          "clientId": "35f92656-7d25-4318-8c0b-888fe093a5f0",
          "coordinateVersion": "v1",
          "endFrame": 80,
          "endTime": 80,
          "frame": 2,
          "frameNumberBased": true,
          "isOnlyLocal": false,
          "isOpen": false,
          "itemLinks": [],
          "objectId": "1",
          "openAnnotationVersion": "1.75.2-rc.38",
          "recipeId": "6614ee52201e826524c523f0",
          "snapshots_": [
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 3,
              "label": "A",
              "namedAttributes": {},
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 5,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 6,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 7,
              "label": "A",
              "namedAttributes": {},
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 8,
              "label": "A",
              "namedAttributes": {},
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 9,
              "label": "A",
              "namedAttributes": {},
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 10,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 11,
              "label": "A",
              "namedAttributes": {},
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 13,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 14,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 15,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 18,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            },
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 19,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            }
          ],
          "startTime": 0,
          "system": false
        },
        "user": {}
      },
      "creator": "name@dataloop.ai",
      "createdAt": "2024-04-24T09:28:03.595Z",
      "updatedBy": "name@dataloop.ai",
      "updatedAt": "2024-04-24T09:31:30.792Z",
      "hash": "2d6705cea186f7c7be259cd517d95ea613b4faa8",
      "source": "ui"
    },
    {
      "id": "6628d173d079e4563d1f03d7",
      "datasetId": "6458d7e0a4aaff79f2f8e16f",
      "itemId": "656d78cc97c4a3bd5a863b6b",
      "url": "https://rc-gate.dataloop.ai/api/v1/annotations/6628d173d079e4563d1f03d7",
      "item": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b",
      "dataset": "https://rc-gate.dataloop.ai/api/v1/datasets/6458d7e0a4aaff79f2f8e16f",
      "type": "ref_semantic_3d",
      "label": "A",
      "attributes": [],
      "coordinates": {
        "interpolation": "none",
        "mode": "overwrite",
        "ref": "6628d21073ec48d85203e026",
        "refType": "id"
      },
      "metadata": {
        "system": {
          "attributes": {},
          "automated": false,
          "clientId": "3c00cf62-4ed7-4b08-a946-d23ae36aa62d",
          "coordinateVersion": "v1",
          "endFrame": 80,
          "endTime": 80,
          "frame": 18,
          "frameNumberBased": true,
          "isOnlyLocal": false,
          "isOpen": false,
          "itemLinks": [],
          "objectId": "2",
          "openAnnotationVersion": "1.75.2-rc.38",
          "recipeId": "6614ee52201e826524c523f0",
          "snapshots_": [
            {
              "attributes": [],
              "data": {},
              "fixed": true,
              "frame": 19,
              "label": "A",
              "namedAttributes": {
                "undefined": null
              },
              "objectVisible": true,
              "type": "ATTRIBUTE_CHANGE"
            }
          ],
          "startTime": 0,
          "system": false
        },
        "user": {}
      },
      "creator": "name@dataloop.ai",
      "createdAt": "2024-04-24T09:31:31.486Z",
      "updatedBy": "name@dataloop.ai",
      "updatedAt": "2024-04-24T09:36:54.282Z",
      "hash": "eb18f38c53a937d871e288ba2ce805ad2abcb8af",
      "source": "ui"
    },
    {
      "id": "6628d2b6403d677a59cbdf91",
      "datasetId": "6458d7e0a4aaff79f2f8e16f",
      "itemId": "656d78cc97c4a3bd5a863b6b",
      "url": "https://rc-gate.dataloop.ai/api/v1/annotations/6628d2b6403d677a59cbdf91",
      "item": "https://rc-gate.dataloop.ai/api/v1/items/656d78cc97c4a3bd5a863b6b",
      "dataset": "https://rc-gate.dataloop.ai/api/v1/datasets/6458d7e0a4aaff79f2f8e16f",
      "type": "cube_3d",
      "label": "A",
      "attributes": [],
      "coordinates": {
        "direction": {
          "x": 1,
          "y": 0,
          "z": 0
        },
        "interpolation": "Linear",
        "position": {
          "x": -5.910163478003942,
          "y": 17.759926650242885,
          "z": 2.0968759090718523
        },
        "rotation": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "scale": {
          "x": 2.8938979884031664,
          "y": 1.949486176458691,
          "z": 1
        }
      },
      "metadata": {
        "system": {
          "attributes": {},
          "automated": false,
          "clientId": "e12714d7-b7a7-4847-8c7c-76443ba46984",
          "endFrame": 80,
          "endTime": 80,
          "frame": 19,
          "frameNumberBased": true,
          "itemLinks": [],
          "objectId": "3",
          "openAnnotationVersion": "1.75.2-rc.38",
          "recipeId": "6614ee52201e826524c523f0",
          "snapshots_": [],
          "startTime": 0,
          "system": false
        },
        "user": {}
      },
      "creator": "name@dataloop.ai",
      "createdAt": "2024-04-24T09:36:54.693Z",
      "updatedBy": "name@dataloop.ai",
      "updatedAt": "2024-04-24T09:36:54.693Z",
      "hash": "c2cdf1f722d6aa5cdc652ce0e1bc69a3058ea481",
      "source": "ui"
    }
  ],
  "annotationsCount": 3,
  "annotated": true,
  "srcItem": "651d221f250b324a6d215941",
  "srcDataset": "6458d7e0a4aaff79f2f8e16f"
}

Instance Segentation Formatting

The instance Segmentation tool segments point clouds.
On the exported JSON format, the indices- the segmented point clouds will diplay below "semanticIndex".

"semanticIndex": {
				"type": "index",
				"frames": {
					"0": [
						22,
						23,
						24,
						28,
						29
]}

Exporting Instance Segmentation

Please be aware that exporting semantic annotations for LiDAR data can only be performed one file at a time. This is due to the large size of the exported files, which can contain millions of indexed point clouds.

Dictionary Table

Key Name

Definition

Parent Key

id

Annotation Id

annotations

datasetId

Dataset Id

annotations

itemId

Id of the item

annotations

url

API URL of the annotation

annotations

item

API URL of the item

annotations

dataset

API URL of the dataset

annotations

type

Annotation type

annotations

label

Annotation label

annotations

attributes

Annotation attributes

annotations

metadata

Information about the annotation

annotations

system

Annotation system information

metadata

status

Annotation status (for example, null/issue/review)

system

startTime

Start time of the annotation in the video

system

endTime

End time of the annotation in the video

system

frame

Frame when the annotation appears in the video

system

endFrame

Last frame the annotation appears in the video

system

snapshots_

Snapshot information relevant to video annotation

system

fixed

Shows if the frame is a fixed frame

snapshots_

frame

Snapshot frame number

snapshots_

objectVisible

Status of annotation (true = visible, false = hidden)

snapshots_

data

Coordination in each snapshot

snapshots_

position

Index of the center of the 3D cube in relation with the center of the world (0,0,0)

Coordinates (3D Cube

rotation

Rotation on each one of the axis: Top view rotation: rotation on the Z axis (Yaw), Front view rotation: rotation on the Y axis (Pitch), Side view rotation:  rotation on the X axis (Roll).

Coordinates (3D Cube)

scale

Scale of the cube on each one of the axis.

Coordinates (3D Cube)

label

Snapshot label

snapshots_

attributes

Snapshots attributes

snapshots_

namedAttributes

The attributes that appear on all annotations

snapshots_

parentId

Id of parent annotation

system

clientId

Annotation created in UI (clientId when not saved)

system

automated

True = Annotation created by automation process

system

objectId

Sequential mark for annotations

system

attributes

Information about the annotation attributes

system

system

Shows if annotation is a system annotation

system

itemLinks

ItemLinks are the connection between ‘snapshot’ annotation (like snapping a frame from a video) to the newly created image item

system

openAnnotationVersion

Platform version

system

recipeId

Id of the recipe

system

user

Metadata added by user via SDK

metadata

creator

User who created the annotation

annotations

createdAt

Date and time when annotation was created

annotations

updatedBy

User who updated the annotation

annotations

updatedAt

Date and time when annotation was last updated

annotations

hash

Used to map annotation’s data to a string

annotations

source

Where the annotation was created: UI/SDK

annotations

coordinates (3D Cube)

Object of includes 3D cube data

annotations

direction

the "direction" field describes the orientation or heading of an annotated object in 3D space.
Dataloop (and most LiDAR formats like KITTI, Waymo, or nuScenes) typically use a right-handed coordinate system, where:

  • X-axis: Points forward (the vehicle’s forward direction)

  • Y-axis: Points to the left of the vehicle

  • Z-axis: Points upward

So in this coordinate frame:

  • x = 1 means the direction is entirely along the X-axis (forward).

  • y = 0 means no sideways (left/right) rotation.

  • z = 0 means no vertical (up/down) tilt.

coordinates

interpolation

this indicates an interpolation was done.

annotations

ref

It displays the reference task ID of the tasks this file was annotated through.

annotations

mode

Whether it is an overwrite mode or not.

annotations

refType

The type of the reference is an ID.

annotations

_id

The item ID

annotations

filename

Name of the file

annotations

mimetype

The mime type of the file

annotations

refs

The references of the task

annotations

shebang dltype

It allows UI to present the annotation as LiDAR instead of a JSON type.

annotations

size

File size

annotations

taskStatusLog

Logs from the task.

annotations