Exporting data and labels from Encord

Exporting data and labels from Annotation projects (Workflows)

Follow the steps below to seamlessly export your labels from Workflow projects.

  1. Navigate to Labels on the Project Dashboard and make sure you have the Data tab selected.
  2. Select the data units for which you want to export labels for.
  3. Click the Export and save button. The following pop-up will appear.
  1. Give this label version a name.
  2. Select whether you want your labels to be exported in JSON or COCO format.
  3. Toggle this if you want to include signed URLs in your export.
  4. Select which label status(es) to include in the export.
  5. Select what objects to include in the export.
  6. Click Export and save to export your labels.

Exporting labels from Manual QA projects

Learn how to export data Manual QA projects by watching this video. For more details, read on below!


The Export tab is where you export the labels and classifications created in a project.

A. Select the files you'd like to export data for by clicking the checkboxes next to the files you'd like to include in your export. Click the Export to export the selected data.

B. Select the format for your exported data; COCO or JSON.

C. Toggle this switch if you'd like to include signed URLs in your export.

D. Select the label status of the annotations you would like to be included in the data export.

E. Select the objects you would like to include in the data export.

F. Select which classifications to include in the data export.

ℹ️

Note

Download files are tagged with a unique id for the project they are exported from and the time at which the export is made.

After the Export button is pressed, progress can be monitored using the notification bell icon in the top-right of the page.

Once the process completes a notification will appear in the top-right corner of your screen telling you the export is complete. Click Click to download to download your labels.

👍

Tip

You can also download your labels in the notification menu (), and clicking the export icon next to the export you want to download.


Label editor coordinates

Label coordinates are normalized to be between 0 and 1. This means that the corners of the frame or image correspond to the coordinates (1,1), (1,0), (0,0), (0,1) regardless of frame dimensions.

To get the pixel values of any normalized coordinates, multiply them by the width or height of the label (given in pixels).

  • "x" and "h" coordinates of a label should be multiplied by the pixel height.
  • "y" and "w" coordinates of a label should be multiplied by the pixel width.

Export data format

All labels export to a single JSON or COCO file and both formats contain the exact same information. The information below uses the JSON format as an example. Refer to the COCO documentation for details on the COCO format.

👍

Tip

We recommend viewing the exported JSON using a web-browser or a JSON parser.

The tables below provide descriptions of all values contained in the exported files.

ℹ️

Note

Exports of label versions for which the data unit has been deleted will vary from the examples shown below - the data_type is deleted, while image groups and image sequences will only contain a single data_unit.

Single images

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.


[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "Cologne images",
    "data_title": "dom-hbf.jpg",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "image",
    "is_image_sequence": null,
    "video_link": null,
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "[email protected]"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
    "annotation_task_status": "COMPLETE"
  }
]

KeyDescriptionNotes
label_hashThe label's hashThe 'hash' represents a unique identifier
created_atTime and date the label was created
last_edited_atTime and date the label was last edited
dataset_hashThe dataset's hashThe 'hash' represents a unique identifier
data_typeThe data unit's file formatAlways "video" for videos
is_image_sequence"true" when the data unit is an image sequenceAlways "null" for images
video_linkContains a private cloud URL for videosAlways "null" for images
data_unitsList of all files the data unit is composed ofDetails of the export information for `data_units`` can be found below.
object_answersAll the attributes in this data unitThe object attributes are identified using their hash
classification_answersAll the classifications in a particular data unitThe classification labels are identified using their hash
object_actionsThe number of states a dynamic attribute can be in.A change in state occurs each time the attribute answer changes. The objectHash within the object_actions is the attribute answer's ID.
label_statusIndicates whether the data unit has been labeled.
export_historyContains a record of the export history for this data unitExporting labels to confirm export history generates an export history entry.
export_hashThe hash for this particular export instanceThe 'hash' represents a unique identifier
exported_atThe date and time when a particular export instance took place.
annotation_task_statusShows the task status of Manual QA Projects.annotation_task_status is only applicable for Manual QA Projects and will be deprecated in January 2024.

data_units

The data_units key contains all files that compose the data unit. For a given image there will only ever be one element in this list. This element will contain the following information.

🚧

Caution

data_units here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.


"data_units": {
      "9c588f63-ad87-4987-a074-06ba0d6980cd": {
        "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
        "data_title": "dom-hbf.jpg",
        "data_type": "image",
        "data_sequence": 0,
        "labels": { },
        "data_fps": "23.976023976023978" ,
        "data_duration": "29.0786",
        "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
        "width": 512,
        "height": 512
      }
}  
KeyDescriptionNotes
data_hashThe file's hashThe 'hash' represents a unique identifier
data_titleThe file's title
data_typeThe file type
data_sequenceThe sequence number of this file within the data unitAlways 0 for images, as single images are composed of a single file by definition
labelsA container for the image's label informationThis contains the label information for the image.
data_linkA link to the file stored in your private cloud
widthThe width of the image in pixel (px)
heightThe height of the image in pixel (px)


labels

labels contains all object labels, classification labels, and attributes present in the image.


"labels": {
      "0": {
        "objects": { },
        "classifications": [ ]
      }
}  
KeyDescriptionNotes
objectsA list of label objects in this frameContains geometric information for object labels
classificationsA list of classifications applying to image as a whole

objects

objects contains all object label information for the image. A key with the name of the object shape is always present - bounding_box in the example below. All shapes contain coordinates for each vertex.

👍

Tip

Navigate to the ontology shapes section to see how all ontology classes are represented in the exported file.

The example below shows a single object instance.

"objects": [
  {
        "name": "Apple",
        "color": "#D33115",
        "shape":"bounding_box",
        "value": "car",
        "boundingBox": {
          "0": {
            "h": 0.3235,
            "w": 0.1697,
            "x": 0.0153,
            "y": 0.254,   
          }
        },
        "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "objectHash": "P6gqJT/3",
        "featureHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe object's nameAs specified in the ontology
colorThe color used to draw the objectAs specified in the ontology
shapeThe ontology class used to create the objectAs specified in the ontology
valueThe name given to the object
createdAtDate and time the object was created
createdByThe email of the user that created this object
confidenceThe confidence score for this objectA confidence score of 1 is given for all labels created manually. More info can be found here
objectHashThe specific label's hashThe 'hash' represents a unique identifier
featureHashThe ontology object's hashCorresponds to the FeatureNodeHash in the ontology
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique
boundingBoxA list containing the coordinates for the bounding boxRefer to the ontology shapes section for more details

classifications

classifications contains all classification information for the image.

The example below shows a single object instance.

"classifications": [
  {
        "name": "Time of day",
        "value": "time_of_day",
        "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "featureHash": "wUS7p9B6",
        "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
        "classificationHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe classification's nameAs specified in the ontology
valueThe classification valueSame as the name
createdAtTime and day the classification was created
createdByThe email of the user that created this classification
confidenceThe confidence score for this classificationA confidence score of 1 is given for all labels created manually. More info can be found here
featureHashThe classification instance hashCorresponds to the FeatureNodeHash in the ontology
lastEditedAtTime and date of the last time this classification was edited
classificationHashThe classification instance hash hash
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

object_answers

object_answers is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding object_answers reveals the following:

"object_answers": {
  "Gqh06ypx"
      "objectHash": "Gqh06ypx",
      "classifications" [ 
        "name": "Size",
        "value": "size",
        "answers": "Medium",
        "featureHash": "GZnFumFq",
        "manualAnnotation": true
      ]
}  
KeyDescriptionNotes
objectHashThe hash of the object containing the attributesThe 'hash' represents a unique identifier
classificationsA list of attributes related to the object. Will include Dynamic attributes and Relation attributesNot to be confused with classifications as defined in our glossary, which apply to a frame
nameThe attribute name
valueThe attribute valueAlways the same as the name
answersThe value(s) the attribute(s) were set toIf the attribute was a radio button, the answer will be the option selected by the annotator
featureHashThe attribute's hashThe 'hash' represents a unique identifier
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

classification_answers

Contains a list of classifications that apply to entire frames or slices. classification_answer is represented by its hash. Expanding classification_answers reveals the following:

"classification_answers": {
  "OFX2jzwE": {
    "classificationHash": "OFX2jzwE", 
    "classifications": [{
      "name": "Time of day", 
      "value": "time_of_day", 
      "answers": [{
        "name": "Night", 
        "value": "night", 
        "featureHash": "j/7dpSmi"}],    
    "featureHash": "uZmB5YZC", 
    "manualAnnotation": true
    }]
  }
}
KeyDescriptionNotes
classificationHashThe classification's hashCorresponds to the featureNodeHash in the Ontology
classificationsA list of classification information
nameThe classification nameAs set in the ontology (Quality in the example above)
valueThe classification valueAlways the same as the classification name
answersA list of all classification answers"answers" refer to the values the classification were set to.
nameThe name of the classification answer"Night" in the example above
valueThe classification answer's valueAlways the same as the classifications answer's name
featureHashThe hash for the particular classification answerIncluded in answers
featureHashThe hash for the particular classification
manualAnnotation"true" for all manually created labels. "false" for all labels created with automated labeling techniques

export_history

The export_history contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

"export_history": {
  "0"
      "export_hash": "Gqh06ypx",
      "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
      "user_email": "[email protected]"
}  
KeyDescriptionNotes
export_hashThe export instance's hashThe 'hash' represents a unique identifier
exported_atDate and time of the export
user_emailThe email of the user that made this export

Image groups and image sequences

👍

Tip

Confused about the difference between image groups and image sequences? See our documentation here to learn about different data types in Encord.

The export contains a list of JSON objects, with each JSON object representing a single image group or image sequence, and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "cooking_image_sequences",
    "data_title": "image-group-67bdc95d",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "image_group",
    "is_image_sequence": null,
    "image_sequence_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "[email protected]"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "[email protected]"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
    "annotation_task_status": "COMPLETE"
  }
]
KeyDescriptionNotes
label_hashThe label's hashThe 'hash' represents a unique identifier
created_atTime and date the label was created
last_edited_atTime and date the label was last edited
dataset_hashThe dataset's hashThe 'hash' represents a unique identifier
data_typeThe data unit's file formatAlways "img_group" for image groups and image sequences
is_image_sequencetrue when the data unit is an image sequencefalse for all other types of data, including image groups. This is what distinguishes image groups and image sequences in your export
video_linkContains a link to file storage location if file is a videoAlways "null" for image groups and image sequences
data_unitsList of all files the data unit is composed ofDetails of the export information for data units can be found below.
object_answersAll the attributes in this data unitThe object attributes are identified using their hash
classification_answersAll the classifications in a particular data unitThe classification labels are identified using their hash
object_actionsThe number of states a dynamic attribute can be in.A change in state occurs each time the attribute answer changes. The objectHash within the object_actions is the attribute answer's ID.
label_statusIndicates whether the data unit has been labeled.
export_historyContains a record of the export history for this data unitExporting labels to confirm export history generates an export history entry.
export_hashThe hash for this particular export instanceThe 'hash' represents a unique identifier
exported_atThe date and time when a particular export instance took place.
annotation_task_statusShows the task status of Manual QA Projects.annotation_task_status is only applicable for Manual QA Projects and will be deprecated in January 2024.

data_units

The data_units key contains a list of all files that compose the image group or image sequence (sometimes referred to as frames). It contains the following information.

🚧

Caution

data_units here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.


"data_units": {
      "9c588f63-ad87-4987-a074-06ba0d6980cd": {
        "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
        "data_title": "rhein-hafen.jpg4",
        "data_type": "image/jpg",
        "data_sequence": 0,
        "labels": { },
        "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
        "width": 512,
        "height": 512
      }
}  
KeyDescriptionNotes
data_hashThe file's hashThe 'hash' represents a unique identifier
data_titleThe file's title
data_typeThe file type
data_sequenceThe sequence number of this file within the data unit0 represents the first file
labelsA list of all frames contained in image group or sequence, and any labels on each frameThis contains the label information for each frame.
widthThe width of the frame in pixel (px)
heightThe height of the frame in pixel (px)


labels

Each number within labels represents an individual frame within the image group or sequence. Each frame contains the following:


"labels": {
      "0": {
        "objects": { },
        "classifications": [ ],
        "metadata":{ }
      }
}  
KeyDescriptionNotes
objectsA list of label objects in this frameContains geometric information for object labels
classificationsA list of classifications applying to the entire frameWill be the same value for all instances of this classification.

objects

objects contains label information for all object instances in a frame. A key with the name of the object shape is always present - bounding_box in the example below. All shapes contain coordinates for each vertex.

👍

Tip

Navigate to the ontology shapes section to see how all ontology classes are represented in the exported file.

The example below shows a single object instance.

"objects": [
      {
        "name": "Apple",
        "color": "#D33115",
        "shape":"bounding_box",
        "value": "apple",
        "boundingBox": {
          "0": {
            "h": 0.3235,
            "w": 0.1697,
            "x": 0.0153,
            "y": 0.254,   
          }
        },
        "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "objectHash": "P6gqJT/3",
        "featureHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe object's nameAs specified in the ontology
colorThe color used to draw the objectAs specified in the ontology
shapeThe ontology class used to create the objectAs specified in the ontology
valueThe name given to the object
createdAtDate and time the object was created
createdByThe email of the user that created this object
confidenceThe confidence score for this objectA confidence score of 1 is given for all labels created manually. More info can be found here
objectHashThe specific label's hashThe 'hash' represents a unique identifier
featureHashThe ontology object's hashCorresponds to the FeatureNodeHash in the ontology
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique
boundingBoxA list containing the coordinates for the bounding boxRefer to the ontology shapes section for more details

classifications

classifications contains all frame level classification information for the image group or sequence.

The example below shows a single classification instance.

"classifications": [
      {
        "name": "Time of day",
        "value": "time_of_day",
        "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "featureHash": "wUS7p9B6",
        "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
        "classificationHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe classification's nameAs specified in the ontology
valueThe classification valueSame as the name
createdAtTime and day the classification was created
createdByThe email of the user that created this classification
confidenceThe confidence score for this classificationA confidence score of 1 is given for all labels created manually. More info can be found here
featureHashThe classification instance hashCorresponds to the FeatureNodeHash in the ontology
lastEditedAtTime and date of the last time this classification was edited
classificationHashThe classification instance hash hash
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

object_answers

object_answers is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding object_answers reveals the following:

"object_answers": {
  "Gqh06ypx"
      "objectHash": "Gqh06ypx",
      "classifications" [{ 
        "name": "Size",
        "value": "size",
        "answers": "Medium",
        "featureHash": "GZnFumFq",
        "manualAnnotation": true
  }]
}  
KeyDescriptionNotes
objectHashThe hash of the object containing the attributesThe 'hash' represents a unique identifier
classificationsA list of attributes related to the object. Will include Dynamic attributes and Relation attributesNot to be confused with classifications as defined in our glossary, which apply to a frame
nameThe attribute name
valueThe attribute valueAlways the same as the name
answersThe value(s) the attribute(s) were set toIf the attribute was a radio button, the answer will be the option selected by the annotator
featureHashThe attribute's hashThe 'hash' represents a unique identifier
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

classification_answers

Contains a list of classifications that apply to entire frames or slices. classification_answer is represented by its hash. Expanding classification_answers reveals the following:

"classification_answers": {
  "OFX2jzwE": {
    "classificationHash": "OFX2jzwE", 
    "classifications": [{
      "name": "Quality", 
      "value": "quality", 
      "answers": [{
        "name": "out of focus", 
        "value": "out_of_focus", 
        "featureHash": "j/7dpSmi"}],    
    "featureHash": "uZmB5YZC", 
    "manualAnnotation": true
    }]
  }
}
KeyDescriptionNotes
classificationHashThe classification's hashThe 'hash' represents a unique identifier
classificationsA list of classifications information
nameThe classification nameAs set in the ontology (Quality in the example above)
valueThe classification valueAlways the same as the classification name
answersA list of all classification answers"answers" refer to the values the classifications were set to.
nameThe name of the classification answer"out of focus" in the example above
valueThe classification answer's valueAlways the same as the classification answer's name
featureHashThe hash for the particular classification answerIncluded in answers
featureHashThe hash for the particular classification
manualAnnotation"true" for all manually created labels. "false" for all labels created with automated labeling techniques

export_history

The export_history contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

"export_history": {
  "0"
      "export_hash": "Gqh06ypx",
      "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
      "user_email": "[email protected]"
}  
KeyDescriptionNotes
export_hashThe export instance's hashThe 'hash' represents a unique identifier
exported_atDate and time of the export
user_emailThe email of the user that made this export

Videos

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.


[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "cooking_videos",
    "data_title": "how-to-make-apple-pie.mp4",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "video",
    "is_image_sequence": null,
    "video_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "[email protected]"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "[email protected]"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
    "annotation_task_status": "COMPLETE"
  }
]

KeyDescriptionNotes
label_hashThe label's hashThe 'hash' represents a unique identifier
created_atTime and date the label was created
last_edited_atTime and date the label was last edited
dataset_hashThe dataset's hashThe 'hash' represents a unique identifier
data_typeThe data unit's file formatAlways "video" for videos
is_image_sequence"true" when the data unit is an image sequenceAlways "null" for videos
video_linkLink to the video saved on your private cloudAlways "null" for all other file types
data_unitsList of all files the data unit is composed ofDetails of the export information for `data_units`` can be found below.
object_answersAll the attributes in this data unitThe object attributes are identified using their hash
classification_answersAll the classifications in a particular data unitThe classification labels are identified using their hash
object_actionsThe number of states a dynamic attribute can be in.A change in state occurs each time the attribute answer changes. The objectHash within the object_actions is the attribute answer's ID.
label_statusIndicates whether the data unit has been labeled.
export_historyContains a record of the export history for this data unitExporting labels to confirm export history generates an export history entry.
export_hashThe hash for this particular export instanceThe 'hash' represents a unique identifier
exported_atThe date and time when a particular export instance took place.
annotation_task_statusShows the task status of Manual QA Projects.annotation_task_status is only applicable for Manual QA Projects and will be deprecated in January 2024.

data_units

The data_units key contains all files that compose the data unit. For a given video there will only ever be one element in this list. This element will contain the following information.

🚧

Caution

data_units here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.


"data_units": {
      "9c588f63-ad87-4987-a074-06ba0d6980cd": {
        "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
        "data_title": "how-to-make-apple-pie.mp4",
        "data_type": "video/mp4",
        "data_sequence": 0,
        "labels": { },
        "data_fps": "23.976023976023978" ,
        "data_duration": "29.0786",
        "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
        "width": 512,
        "height": 512
      }
}  
KeyDescriptionNotes
data_hashThe file's hashThe 'hash' represents a unique identifier
data_titleThe file's title
data_typeThe file type
data_sequenceThe sequence number of this file within the data unit0 represents the first file
labelsA list of all frames contained in the video and any labels on each frameThis contains the label information for each frame.
data_fpsThe frames per second for this video
data_durationThe video lengthIn seconds
data_linkA link to the file stored in your private cloud
widthThe width of the frame in pixel (px)
heightThe height of the frame in pixel (px)


labels

Each number within labels represents an individual frame within the data unit. Each frame contains the following:


"labels": {
      "0": {
        "objects": { },
        "classifications": [ ],
        "metadata":{ }
      }
}  
KeyDescriptionNotes
objectsA list of label objects in this frameContains geometric information for object labels
classificationsA list of classifications applying to the entire frameWill be the same value for all instances of this classification.

objects

objects contains label information for all object instances in a frame. A key with the name of the object shape is always present - bounding_box in the example below. All shapes contain coordinates for each vertex.

👍

Tip

Navigate to the ontology shapes section to see how all ontology classes are represented in the exported file.

The example below shows a single object instance.

"objects": [
  {
        "name": "Apple",
        "color": "#D33115",
        "shape":"bounding_box",
        "value": "apple",
        "boundingBox": {
          "0": {
            "h": 0.3235,
            "w": 0.1697,
            "x": 0.0153,
            "y": 0.254,   
          }
        },
        "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "objectHash": "P6gqJT/3",
        "featureHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe object's nameAs specified in the ontology
colorThe color used to draw the objectAs specified in the ontology
shapeThe ontology class used to create the objectAs specified in the ontology
valueThe name given to the object
createdAtDate and time the object was created
createdByThe email of the user that created this object
confidenceThe confidence score for this objectA confidence score of 1 is given for all labels created manually. More info can be found here
objectHashThe specific label's hashThe 'hash' represents a unique identifier
featureHashThe ontology object's hashCorresponds to the FeatureNodeHash in the ontology
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique
boundingBoxA list containing the coordinates for the bounding boxRefer to the ontology shapes section for more details

classifications

classifications contains all frame level classification information for the video.

The example below shows a single classification instance.

"classifications": [
  {
        "name": "Time of day",
        "value": "time_of_day",
        "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "featureHash": "wUS7p9B6",
        "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
        "classificationHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe classification's nameAs specified in the ontology
valueThe classification valueSame as the name
createdAtTime and day the classification was created
createdByThe email of the user that created this classification
confidenceThe confidence score for this classificationA confidence score of 1 is given for all labels created manually. More info can be found here
featureHashThe classification instance hashCorresponds to the FeatureNodeHash in the ontology
lastEditedAtTime and date of the last time this classification was edited
classificationHashThe classification instance hash hash
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

object_answers

object_answers is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding object_answers reveals the following:

"object_answers": {
  "Gqh06ypx"
      "objectHash": "Gqh06ypx",
      "classifications" [ 
        "name": "Size",
        "value": "size",
        "answers": "Medium",
        "featureHash": "GZnFumFq",
        "manualAnnotation": true
      ]
}  
KeyDescriptionNotes
objectHashThe hash of the object containing the attributesThe 'hash' represents a unique identifier
classificationsA list of attributes related to the objectNot to be confused with classifications as defined in our glossary, which apply to a frame
nameThe attribute name
valueThe attribute valueAlways the same as the name
answersThe value(s) the attribute(s) were set toIf the attribute was a radio button, the answer will be the option selected by the annotator
featureHashThe attribute's hashThe 'hash' represents a unique identifier
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

classification_answers

Contains a list of classifications that apply to entire frames or slices. classification_answer is represented by its hash. Expanding classification_answers reveals the following:

"classification_answers": {
  "OFX2jzwE": {
    "classificationHash": "OFX2jzwE", 
    "classifications": [{
      "name": "Quality", 
      "value": "quality", 
      "answers": [{
        "name": "out of focus", 
        "value": "out_of_focus", 
        "featureHash": "j/7dpSmi"}],    
    "featureHash": "uZmB5YZC", 
    "manualAnnotation": true
    }]
  }
}
KeyDescriptionNotes
classificationHashThe classification's hashThe 'hash' represents a unique identifier
classificationsA list of classifications information
nameThe classification nameAs set in the ontology (Quality in the example above)
valueThe classification valueAlways the same as the classification name
answersA list of all classification answers"answers" refer to the values the classifications were set to.
nameThe name of the classification answer"out of focus" in the example above
valueThe classification answer's valueAlways the same as the classification answer's name
featureHashThe hash for the particular classification answerIncluded in answers
featureHashThe hash for the particular classification
manualAnnotation"true" for all manually created labels. "false" for all labels created with automated labeling techniques

export_history

The export_history contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

"export_history": {
  "0"
      "export_hash": "Gqh06ypx",
      "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
      "user_email": "[email protected]"
}  
KeyDescriptionNotes
export_hashThe export instance's hashThe 'hash' represents a unique identifier
exported_atDate and time of the export
user_emailThe email of the user that made this export

DICOM

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.


[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "BB: CT thin slices",
    "data_title": "9c58",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "dicom",
    "is_image_sequence": null,
    "video_link": null,
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "[email protected]"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "[email protected]"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
    "annotation_task_status": "RETURNED"
  }
]

KeyDescriptionNotes
label_hashThe label's hashThe 'hash' represents a unique identifier
created_atTime and date the label was created
last_edited_atTime and date the label was last edited
dataset_hashThe dataset's hashThe 'hash' represents a unique identifier
data_typeThe data unit's file formatAlways "dicom" in a DICOM series
is_image_sequence"true" when the data unit is an image sequenceAlways "null" for a DICOM series
video_linkLink to the video or image sequenceAlways "null" for a DICOM series
data_unitsList of all files the data unit is composed ofDetails of the export information for `data_units`` can be found below.
object_answersAll the object attributes in this data unitThe object attribute are identified using their hash
classification_answersAll the classifications in a particular data unitThe classification labels are identified using their hash
object_actionsThe number of states a dynamic attribute can be in.A change in state occurs each time the attribute answer changes. The objectHash within the object_actions is the attribute answer's ID.
label_statusIndicates whether the data unit has been labeled.
export_historyContains a record of the export history for the data unitExporting labels to confirm export history generates an export history entry.
export_hashThe hash for this particular export instanceThe 'hash' represents a unique identifier
exported_atThe date and time when a particular export instance took place.
annotation_task_statusShows the task status of Manual QA Projects.annotation_task_status is only applicable for Manual QA Projects and will be deprecated in January 2024.

data_units

The data_units key contains all files that compose the data unit. If a single DICOM series is one data unit, there will only be a single element in this list.

🚧

Caution

data_units here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.


"data_units": {
      "9c588f63-ad87-4987-a074-06ba0d6980cd": {
        "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
        "data_title": "9c58",
        "data_type": "application/dicom",
        "data_sequence": 0,
        "labels": { },
        "metadata": {  },
        "data_links": { },
        "width": 512,
        "height": 512
      }
}  
KeyDescriptionNotes
data_hashThe file's hashThe 'hash' represents a unique identifier
data_titleThe file's title
data_typeThe file type
data_sequenceThe sequence number of this file within the data unit0 represents the first file
labelsA list of all slices contained in the series and any labels on each sliceThis contains the label information for each slice.
metadataThe DICOM series metadata.Contains the ID for the patient, the study, and the series.
data_linksLinks to all slices within the series, ordered by their sequence number
widthThe width of the slice in pixel (px)
heightThe height of the slice in pixel (px)


labels

Each number within labels represents an individual slice or frame within the data unit. Each slice or frame contains the following:


"labels": {
      "0": {
        "objects": { },
        "classifications": [ ],
        "metadata":{ }
      }
}  
KeyDescriptionNotes
objectsA list of label objects on this sliceContains geometric information for object labels
classificationsA list of classifications applying to the entire slice or frameThis will be the same value for all instances of this classification.
metadataSlice specific metadata

objects

objects contains label information for all object instances in a frame. A key with the name of the object shape is always present - polygon in the example below. All shapes contain coordinates for each vertex.

👍

Tip

Navigate to the ontology shapes section to see how all ontology classes are represented in the exported file.

The example below shows a single object instance.

"objects": [
  {
        "name": "lungs",
        "color": "#D33115",
        "shape":"polygon",
        "value": "lungs",
        "polygon": {
          "0": {
            "x": 0.2423,
            "y": 0.5115,
          },
          "1": {
            "x": 0.4167,
            "y": 0.4218,   
          }
        },
        "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "objectHash": "mQ+yKcF5",
        "featureHash": "pRwpsg1H",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe object's nameAs specified in the ontology
colorThe color used to draw the objectAs specified in the ontology
shapeThe ontology class used to create the objectAs specified in the ontology
valueThe name given to the object
polygonA list containing the x and y coordinates of each vertex on the polygonRefer to the ontology shapes section for more details
createdAtDate and time the object was created
createdByThe email of the user that created this object
confidenceThe confidence score for this objectA confidence score of 1 is given for all labels created manually. More info can be found here
objectHashThe specific label's hashThe 'hash' represents a unique identifier
featureHashThe ontology object's hashCorresponds to the FeatureNodeHash in the ontology
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

classifications

classifications contains all frame level classification information for the slice.

The example below shows a single classification instance.

"classifications": [
  {
        "name": "State",
        "value": "state",
        "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
        "createdBy": "[email protected]",
        "confidence": "1",
        "featureHash": "wUS7p9B6",
        "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
        "classificationHash": "jiOiEq76",
        "manualAnnotation": true
      }
]  
KeyDescriptionNotes
nameThe classification's nameAs specified in the ontology
valueThe classification valueSame as the name
createdAtTime and day the classification was created
createdByThe email of the user that created this classification
confidenceThe confidence score for this classificationA confidence score of 1 is given for all labels created manually. More info can be found here
featureHashThe classification instance hashCorresponds to the FeatureNodeHash in the ontology
lastEditedAtTime and date of the last time this classification was edited
classificationHashThe classification instance hash hash
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

metadata
"metadata": {
      "dicom_instance_uid": "1.3.9.1.4.7.14219.5.2.8.1600.1202.0357967439694942",
      "multiframe_frame_number": "null",
      "file_uri":"cord-dicoms/H7sLTXjYbrou3GhfmHRiuE5m92/5adba3dd-09f6-5c95-b954-e76542fe0ed7",
      "width": "512",
      "height": "512",
}  
KeyDescriptionNotes
dicom_instance_uidThe DICOM instance UIDDICOM tag value (0008,0018). More information can be found here
multiframe_frame_numberA field indicating the frame number when the JSON contains only a single labelDisplays null when each slice has its only expandable labels instance
file_uriThis slice's URIIdentifies this slice
heightThe slice's height (in pixel)DICOM tag value (0028,0010). More information can be found here
widthThe slice's width (in pixel)DICOM tag value (0028,0011). More information can be found here

metadata

The slice metadata contains information on the DICOM study, the DICOM series, as well as the patient.

"metadata": {
      "patient_id": "ENC-ORD-LUV-031023",
      "study_uid": "null",
      "series_uid":"cord-dicoms/H7sLTXjYbrou3GhfmHRiuE5m92/5adba3dd-09f6-5c95-b954-e76542fe0ed7",
}  
KeyDescriptionNotes
patient_idThe patient IDDICOM tag value (0010,0020). More information can be found here
study_uidThe DICOM study's IDDICOM tag value (0020,000D). More information can be found here
series_uidThe DICOM series' IDDICOM tag value (0020,000E). More information can be found here

object_answers

object_answers is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding object_answers reveals the following:

"object_answers": {
  "Gqh06ypx"
      "objectHash": "Gqh06ypx",
      "classifications" [ 
        "name": "Size",
        "value": "size",
        "answers": "Medium",
        "featureHash": "GZnFumFq",
        "manualAnnotation": true
      ]
}  
KeyDescriptionNotes
objectHashThe hash of the object containing the attributesThe 'hash' represents a unique identifier
classificationsA list of attributes related to the object. Will include Dynamic attributes and Relation attributes.Not to be confused with classifications as defined in our glossary, which apply to a frame
nameThe attribute name
valueThe attribute valueAlways the same as the name
answersThe value(s) the attribute(s) were set toIf the attribute was a radio button, the answer will be the option selected by the annotator
featureHashThe attribute's hashThe 'hash' represents a unique identifier
manualAnnotationA field indicating whether the object was drawn manually or nottrue means it was drawn manually, while false means it was created using a model or an automated labeling technique

classification_answers

classification_answers a list of frame classifications in which each classification is represented by its hash. Expanding classification_answers reveals the following:

"classification_answers": {
  "OFX2jzwE": {
    "classificationHash": "OFX2jzwE", 
    "classifications": [{
      "name": "Quality", 
      "value": "quality", 
      "answers": [{
        "name": "out of focus", 
        "value": "out_of_focus", 
        "featureHash": "j/7dpSmi"}],    
    "featureHash": "uZmB5YZC", 
    "manualAnnotation": true
    }]
  }
}
KeyDescriptionNotes
classificationHashThe classification's hashThe 'hash' represents a unique identifier
classificationsA list of information about the classification
nameThe classification nameAs set in the ontology (Quality in the example above)
valueThe classification valueAlways the same as the classification name
answersA list of all classification answers"answers" refer to the values the classification were set to.
nameThe name of the classification answer"out of focus" in the example above
valueThe classification answer's valueAlways the same as the classification answer's name
featureHashThe hash for the particular classification answerIncluded in answers
featureHashThe hash for the particular classification
manualAnnotationtrue for all manually created labels. false for all labels created with automated labeling techniques

export_history

The export_history contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

"export_history": {
  "0"
      "export_hash": "Gqh06ypx",
      "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
      "user_email": "[email protected]"
}  
KeyDescriptionNotes
export_hashThe export instance's hashThe 'hash' represents a unique identifier
exported_atDate and time of the export
user_emailThe email of the user that made this export

Ontology shapes

All ontology shapes can be represented within an export.

Bounding Box

x and y represent coordinates of the top-left corner of the box. h and w respectively represent the height and width of the box.

 "boundingBox": {
    "h": 0.118,
    "w": 0.1643,
    "x": 0.6985,
    "y": 6204
 }
Polygon

Polygons contain the x and y coordinates for each vertex.

 "polygon": {
  "0": {
    "x": 0.2423,
    "y": 0.5115,
  },
  "1": {
    "x": 0.4167,
    "y": 0.4218,   
          },
  "2": {
    "x": 0.5821,
    "y": 0.4641,   
          },
  "3": {
    "x": 0.5808,
    "y": 0.5756,   
          },
  "4": {
    "x": 0.4564,
    "y": 0.6397,   
          }
  }

Polyline

Polylines contain the x and y coordinates for each vertex.

 "polyline": {
  "0": {
    "x": 0.2423,
    "y": 0.5115,
  },
  "1": {
    "x": 0.4167,
    "y": 0.4218,   
          },
  "2": {
    "x": 0.5821,
    "y": 0.4641,   
          },
  "3": {
    "x": 0.5808,
    "y": 0.5756,   
          },
  "4": {
    "x": 0.4564,
    "y": 0.6397,   
          }
  }

Keypoint

Keypoints are represented in the export using only x and y coordinates.

 "point": {
    "0": {
      "x": 0.3192,
      "y": 0.1547,
  }
 }
Rotatable Bounding Box

x and y represent the coordinates of the top-left corner of the unrotated box. h and w respectively represent the height and width of the box, while theta represents the angle of clockwise rotation of the bounding box about the centre of the box.

 "rotatableBoundingBox": {
    "h": 0.118,
    "w": 0.1643,
    "x": 0.6985,
    "y": 6204,
    "theta": 305.7762
 }
Bitmask

The rleString encodes the Bitmask label, and has to be decoded. See our SDK documentation to learn how to decode an rleString.

"objects": [
      {
        "bitmask": {
          "rleString": "02220N:0F20N",
          "top": 0,
          "left": 0,
          "width": 6,
          "height": 6
        }
      }
  ]  
Object primitive

Object primitives are referred to as skeletons in the export. Each point on the object primitive is represented in the export using x and y coordinates.

Below is an example of an object primitive with 3 points.


"skeleton": {
  "0": {
    "x": 0.5719,
    "y": 0.7615,
    "name": "point_0",
    "color": "#fcc400",
    "value": "point_0",
    "featureHash": "qPCTeIci"
    },
    "1": {
    "x": 0.5428,
    "y": 0.6734,
    "name": "point_1",
    "color": "#fcc400",
    "value": "point_1",
    "featureHash": "o1NKWqKP"
    },
    "2": {
    "x": 0.4865,
    "y": 0.6464,
    "name": "point_2",
    "color": "#fcc400",
    "value": "point_2",
    "featureHash": "9bgJBA85"
    }
}

KeyDescriptionNotes
nameName of this pointAs set in the ontology
colorThe hexadecimal color code used to represent this pointAs set in the ontology
featureHashThe hash for this particular pointthe 'hash' is a unique identifier

Exporting Bitmasks

Bitmask labels are exported as rleStrings. See our SDK documentation to learn how to decode an rleString.

👍

Tip

We strongly recommend exporting Bitmask labels using the Encord SDK. Bitmasks will be exported in the JSON format.

👍

Tip

Use the COCO API to decode Bitmasks when using the COCO export format.

Exporting data using the Python SDK

Go here to learn how to export JSON files from Encord's Python SDK. Reach out to us to if you need to export COCO labels.