Export DICOM annotations

How to export DICOM data and sample export formats.

Open this Colab for an interactive tutorial on exporting annotations.

Export JSON annotations

# Set the export params to include/exclude certain fields. Make sure each of these fields are correctly grabbed 
export_params= {
  "attachments": True,
  "metadata_fields": True,
  "data_row_details": True,
  "project_details": True,
  "label_details": True,
  "performance_details": True
}

# You can set the range for last_activity_at and label_created_at. 
# For context, last_activity_at captures the creation and modification of labels, metadata, status, comments and reviews.
# Note: This is an AND logic between the filters, so usually using one filter is sufficient.

filters= {
  "last_activity_at": ["2000-01-01 00:00:00", "2050-01-01 00:00:00"],
  "workflow_status": "Done"
}

export_task = project.export_v2(params=export_params, filters=filters)
export_task.wait_till_done()

if export_task.errors:
  print(export_task.errors)

export_json = export_task.result
print("results: ", export_json)
labels = project.export_labels(download=True)

# Optionally, provide a date range as an optional parameter
# This will export only labels created between the supplied dates
# Date range can be formatted as "YYYY-MM-DD" or "YYYY-MM-DD hh:mm:ss"
labels = project.export_labels(download=True, start="2022-09-28", end="2022-10-04")

Annotation export formats

Polyline

{
  "feature_id": "cldnz5eto00053b6jqxb2rzm7",
  "name": "line",
  "annotation_kind": "DICOMPolyline",
  "classifications": [],
  "line": [
    {
      "x": 180.156,
      "y": 138.502
    },
    {
      "x": 259.096,
      "y": 181.804
    },
    {
      "x": 293.148,
      "y": 245.211
    }
  ]
}
{ // This is from the frame data of the DICOM file for one of the axes
  "frameNumber": 185,
  "classifications": [],
  "objects": [
    {
      "featureId": "cl2y5hjr200073g6cidkf0pqj",
      "schemaId": "ckzohkul206420z974x2q4a9h",
      "title": "Tool 2",
      "value": "tool_2",
      "color": "#FF34FF",
      "keyframe": true,
      "line": [
        {
          "x": 95.237,
          "y": 117.232
        },
        {
          "x": 223.735,
          "y": 196
        },
        {
          "x": 262.608,
          "y": 124.785
        }
      ],
      "classifications": []
    }
  ],
  "relationships": []
}

Mask

Regardless of which tool you use to create a segmentation mask, the annotation will appear in the following form in the export. Whether you use the pen tool or the brush tool, all masks will take the same format in exports.

{
  "feature_id": "cldnz5k2z000b3b6j7rr1padw",
  "name": "segmentation",
  "annotation_kind": "DICOMSegmentationMask",
  "classifications": [],
  "mask": {
    "url": "https://api.lb-stage.xyz/api/v1/projects/cldnyx07w0dcg071ahdgx2y3h/annotations/cldnz5k2z000b3b6j7rr1padw/index/256/mask"
  }
}
}
{ // This is from the frame data of the DICOM file for one of the axes
  "frameNumber": 172,
  "classifications": [],
  "objects": [
    {
      "featureId": "cl2y5hdq200053g6cklrdauj7",
      "schemaId": "ckzohkul206400z976bjrguy3",
      "title": "Tool 1",
      "value": "tool_1",
      "color": "#1CE6FF",
      "keyframe": true,
      "instanceURI": "https://api.labelbox.com/masks/feature/cl2y5hdq200053g6cklrdauj7/172",
      "classifications": []
    }
  ],
  "relationships": []
}

Sample project export

{
  "data_row": {
    "id": "cldnyuj4z1qjk083c202478df",
    "global_key": "https://storage.googleapis.com/labelbox-datasets/dicom-sample-data/sample-dicom-1.dcm",
    "row_data": "https://storage.googleapis.com/labelbox-datasets/dicom-sample-data/sample-dicom-1.dcm",
    "details": {
      "dataset_id": "cldnyuicb07oh07y1219z1pmm",
      "created_at": "2023-02-03",
      "updated_at": "2023-02-03",
      "created_by": "[email protected]"
    }
  },
  "media_attributes": {
    "mime_type": "application/dicom"
  },
  "attachments": [
    {
      "type": "VIDEO",
      "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4",
      "id": "cldnyuj4z1qjo083chbarelsa"
    }
  ],
  "metadata_fields": [
    {
      "schema_id": "cko8s9r5v0001h2dk9elqdidh",
      "schema_name": "tag",
      "value": "tag_string"
    }
  ],
  "projects": {
    "cldnyx07w0dcg071ahdgx2y3h": {
      "project_name": "test_dicom_export_project",
      "labels": [
        {
          "label_kind": "DICOM",
          "version": "1.0.0",
          "id": "cldnz52so08ef07zr5ee19dch",
          "label_details": {
            "created_at": "2023-02-03T03:36:30+00:00",
            "updated_at": "2023-02-03T03:36:30+00:00",
            "created_by": "[email protected]",
            "reviews": []
          },
          "performance_details": {
            "seconds_to_create": 22,
            "seconds_to_review": 0,
            "skipped": false
          },
          "annotations": {
            "groups": {
              "Axial": {
                "name": "Axial",
                "classifications": [],
                "frames": {
                  "6": {
                    "objects": {
                      "cldnz5eto00053b6jqxb2rzm7": {
                        "feature_id": "cldnz5eto00053b6jqxb2rzm7",
                        "name": "line",
                        "annotation_kind": "DICOMPolyline",
                        "classifications": [],
                        "line": [
                          {
                            "x": 180.156,
                            "y": 138.502
                          },
                          {
                            "x": 259.096,
                            "y": 181.804
                          },
                          {
                            "x": 293.148,
                            "y": 245.211
                          }
                        ]
                      }
                    },
                    "classifications": []
                  }
                }
              },
              "Sagittal": {
                "name": "Sagittal",
                "classifications": [],
                "frames": {
                  "256": {
                    "objects": {
                      "cldnz5k2z000b3b6j7rr1padw": {
                        "feature_id": "cldnz5k2z000b3b6j7rr1padw",
                        "name": "segmentation",
                        "annotation_kind": "DICOMSegmentationMask",
                        "classifications": [],
                        "mask": {
                          "url": "https://api.lb-stage.xyz/api/v1/projects/cldnyx07w0dcg071ahdgx2y3h/annotations/cldnz5k2z000b3b6j7rr1padw/index/256/mask"
                        }
                      }
                    },
                    "classifications": []
                  }
                }
              },
              "Coronal": {
                "name": "Coronal",
                "classifications": [],
                "frames": {}
              }
            },
            "segments": {
              "Axial": {
                "cldnz5eto00053b6jqxb2rzm7": [
                  [
                    6,
                    6
                  ]
                ]
              },
              "Sagittal": {
                "cldnz5k2z000b3b6j7rr1padw": [
                  [
                    256,
                    256
                  ]
                ]
              },
              "Coronal": {}
            },
            "classifications": [],
            "key_frame_feature_map": {
              "cldnz5eto00053b6jqxb2rzm7": {
                "Axial": {
                  "6": true
                },
                "Coronal": {},
                "Sagittal": {}
              },
              "cldnz5k2z000b3b6j7rr1padw": {
                "Axial": {},
                "Coronal": {},
                "Sagittal": {
                  "256": true
                }
              }
            }
          }
        }
      ],
      "project_details": {
        "ontology_id": "cldnyxxwj06t007yyauy4d9v0",
        "batch_id": "74a832a0-a373-11ed-8589-0f62d40c5b84",
        "priority": 5,
        "consensus_expected_label_count": 1,
        "workflow_history": [
          {
            "action": "APPROVE",
            "created_at": "2023-02-09T20:52:24.428000+00:00",
            "created_by": "[email protected]",
            "previous_task_name": "Initial review task",
            "previous_task_id": "3670e63f-b170-42ff-89c1-d311bf042f4f"
          },
          {
            "action": "MOVE",
            "created_at": "2023-02-03T03:36:29.980000+00:00",
            "created_by": "[email protected]",
            "previous_task_name": "Initial labeling task",
            "previous_task_id": "912c16de-5f25-0b40-974d-70a507431241",
            "next_task_name": "Initial review task",
            "next_task_id": "3670e63f-b170-42ff-89c1-d311bf042f4f"
          },
          {
            "action": "MOVE",
            "created_at": "2023-02-03T03:36:29.947000+00:00",
            "created_by": "[email protected]",
            "next_task_name": "Initial labeling task",
            "next_task_id": "912c16de-5f25-0b40-974d-70a507431241"
          }
        ]
      }
    }
  }
}
[
  {
    "ID":"cl2y5gyv5pl2s07749ceb5mr2",
    "DataRow ID":"ckzohk4gy07d60ztx8orb8nbi",
    "Labeled Data":"https://storage.googleapis.com/bentz-test/dicom-assets/cat-scan1.dcm",
    "Label":{
      "objects":[

      ],
      "classifications":[

      ],
      "relationships":[

      ],
      "groups":[
        {
          "name":"axial", //should be 'axial', 'sagittal', or 'coronal'
          "objects":[

          ],
          "classifications":[

          ],
          "relationships":[

          ],
          "frames":"https://api.labelbox.com/v1/frames/cl2y5gyv5pl2s07749ceb5mr2?group=axial"
        }
      ]
    },
    "Created By":"[email protected]",
    "Project Name":"DICOM",
    "Created At":"2022-05-09T03:14:41.000Z",
    "Updated At":"2022-05-09T03:14:42.740Z",
    "Seconds to Label":1,
    "External ID":"2",
    "Agreement":-1,
    "Benchmark Agreement":-1,
    "Benchmark ID":null,
    "Dataset Name":"cat-scan.json",
    "Reviews": [],
    "View Label":"https://editor.labelbox.com?project=cl2sl1qnnbfrl0767bv649iud&label=cl2y5gyv5pl2s07749ceb5mr2",
    "Has Open Issues":0,
    "Skipped": false,
    "DataRow Workflow Info": {
      "taskName": "Done",
      "Workflow History": [
        {
          "actorId": "cl3lobugu14pw0796fau0dgad",
          "action": "APPROVE",
          "createdAt": "2022-09-29T15:46:23.269Z",
          "previousTaskId": "0ae49522-97f0-4a07-96c6-bd4d50963acd",
          "previousTaskName": "Initial review task"
        },
        {
          "actorId": "cl3lobugu14pw0796fau0dgad",
          "action": "REWORK",
          "createdAt": "2022-09-29T14:23:59.735Z",
          "previousTaskId": "4a0d7f40-0c3f-0cc8-adc4-fd818684facd",
          "previousTaskName": "Rework (all rejected)",
          "nextTaskId": "0ae49522-97f0-4a07-96c6-bd4d50963acd",
          "nextTaskName": "Initial review task"
        },
        {
          "actorId": "cl1qe5naj3g460z6e0owr6mwj",
          "action": "REJECT",
          "createdAt": "2022-09-29T13:39:01.077Z",
          "previousTaskId": "0ae49522-97f0-4a07-96c6-bd4d50963acd",
          "previousTaskName": "Initial review task",
          "nextTaskId": "4a0d7f40-0c3f-0cc8-adc4-fd818684facd",
          "nextTaskName": "Rework (all rejected)"
        },
        {
          "actorId": "cl3ucfsj22j8l073xaitnh1xe",
          "action": "MOVE",
          "createdAt": "2022-09-28T18:06:16.881Z",
          "previousTaskId": "ea78e526-e429-002e-8b80-b72c4b591152",
          "previousTaskName": "Initial labeling task",
          "nextTaskId": "0ae49522-97f0-4a07-96c6-bd4d50963acd",
          "nextTaskName": "Initial review task"
        },
        {
          "actorId": "cl3ucfsj22j8l073xaitnh1xe",
          "action": "MOVE",
          "createdAt": "2022-09-28T18:06:16.859Z",
          "nextTaskId": "ea78e526-e429-002e-8b80-b72c4b591152",
          "nextTaskName": "Initial labeling task"
        }
      ]
    }
  }

  // Access per-frame annotation for each axis via Label.frames URL (see above)
  {
  "frameNumber": 172,
  "classifications": [],
"objects": [
  {
    "featureId": "cl2y5hdq200053g6cklrdauj7",
    "schemaId": "ckzohkul206400z976bjrguy3",
    "title": "Tool 1",
    "value": "tool_1",
    "color": "#1CE6FF",
    "keyframe": true,
    "instanceURI": "https://api.labelbox.com/masks/feature/cl2y5hdq200053g6cklrdauj7/172",
    "classifications": []
  }
],
"relationships": []
}
{
  "frameNumber": 185,
  "classifications": [],
  "objects": [
    {
      "featureId": "cl2y5hjr200073g6cidkf0pqj",
      "schemaId": "ckzohkul206420z974x2q4a9h",
      "title": "Tool 2",
      "value": "tool_2",
      "color": "#FF34FF",
      "keyframe": true,
      "line": [
        {
          "x": 95.237,
          "y": 117.232
        },
        {
          "x": 223.735,
          "y": 196
        },
        {
          "x": 262.608,
          "y": 124.785
        }
      ],
      "classifications": []
    }
  ],
  "relationships": []
}

Sample model run export

Not supported yet.