Export Labels

The Encord SDK is designed to offer a versatile and targeted approach to accessing label information. This approach allows for a more customized handling of label information, catering to various needs and scenarios in data processing. The following table describes all values exported by the scripts on this page.

Key	Description
objectHash	The unique ID of the object instance. Two instances of the same object have different object hashes
Object name	The name of the object as defined in the Ontology. For example “Chicken”.
featureHash	The unique ID of the Ontology element. For example, the object “Chicken” in the Ontology. All instances have the same featureHash.
uid	The unique identifier for the object instance. Two instances of the same object have different uids.
Object color	The color used to label the object, as defined in the Ontology and seen in the Encord platform.
Ontology shape	The shape used to label the object, as defined in the Ontology. For example, polygon.
Classification name	The name of the Classification, as defined in the Ontology. For example “Day or night?”
Classification answer	The value of the Classification, as defined in the Ontology. For example “Day”
classificationHash	The unique identifier for the Classification instance.
Classification answer hash	The unique identifier for the Classification value
Attribute name	The name of the attribute, as defined in the Ontology. For example “Standing or sitting?”
Attribute answer	The name of the attribute value, as defined in the Ontology. For example “Sitting”
Attribute answer featureHash	The unique identifier for the attribute value.

Export Labels as JSON

The following script prints a JSON file containing all the labels in your Project.

Adding include_children=True to list_label_rows_v2() includes all labels from Data Groups.
Adding include_all_label_branches=True to list_label_rows_v2() includes all labels from all branches in Consensus Projects.

Export labels to JSON


# Import dependencies
import json
import os

from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
BUNDLE_SIZE = 100  # Customize as needed
OUTPUT_JSON = "/Users/chris-encord/export-label-rows.json" # Replace with file path to save JSON output file

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

# Get label rows for your Project
label_rows = project.list_label_rows_v2(include_children=True, include_all_label_branches=True)
assert label_rows, f"No label rows found in project {PROJECT_ID}"

# Initialize label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Collect all label row data
all_label_rows = [label_row.to_encord_dict() for label_row in label_rows]
assert all_label_rows, "No label row data collected for export"

# Save the collected label rows data to a JSON file
output_file = OUTPUT_JSON
assert output_file.endswith(".json"), "Output file must be a .json file"

with open(output_file, "w") as file:
    json.dump(all_label_rows, file, indent=4)

print(f"Label rows have been saved to {output_file}.")

Export Attributes

The following scripts get the attributes for all labels in a Project, as well as the frames that the attributes appear on. Single images only have a single frame.

We recommend using the script for exporting all attributes if the Project uses an Ontology with nested attributes.


# Import dependencies
import json

from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, TextAttribute

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
DATA_UNIT = "cherries-is"
OUTPUT_FILE_PATH = "/Users/chris-encord/text_attributes_output.json"
BUNDLE_SIZE = 100

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

# Filter label rows for a specific data title
label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
assert label_rows, f"No label rows found for data title '{DATA_UNIT}'"

# Initialize labels using bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)


# Function to extract text attributes and store in structured format
def extract_text_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
    if isinstance(attribute, TextAttribute):
        text_answer = object_instance.get_answer(attribute)
        return {
            "frame": frame_number + 1,
            "attribute_name": attribute.title,
            "attribute_hash": attribute.feature_node_hash,
            "text_answer": text_answer,
        }
    return None


# Collect results for saving
results = []

# Iterate through all object instances and collect text attribute data
for label_row in label_rows:
    object_instances = label_row.get_object_instances()
    assert object_instances, f"No object instances found in label row {label_row.uid}"

    for object_instance in object_instances:
        annotations = object_instance.get_annotations()
        assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

        ontology_item = object_instance.ontology_item
        assert ontology_item and ontology_item.attributes, (
            f"Missing ontology item or attributes for object {object_instance.object_hash}"
        )

        for annotation in annotations:
            for attribute in ontology_item.attributes:
                attr_data = extract_text_attributes(attribute, object_instance, annotation.frame)
                if attr_data:
                    results.append(attr_data)
                    # Optional: also print to console
                    print(f"Frame {attr_data['frame']}:")
                    print(f"Text Attribute name: {attr_data['attribute_name']}")
                    print(f"Text Attribute hash: {attr_data['attribute_hash']}")
                    print(f"Text Attribute Answer: {attr_data['text_answer']}")

# Save results to JSON
assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must end with .json"

with open(OUTPUT_FILE_PATH, "w") as f:
    json.dump(results, f, indent=4)

print(f"\nText attribute data saved to: {OUTPUT_FILE_PATH}")

Export Objects and Classifications

The following scripts do not support Ontologies with text classifications, or nested classifications. The scripts serve as a template for exporting object labels only.

The following script shows how to access and print essential label information for all object and classification instances, and all attributes in a Project. The example for videos, image groups, image sequences and DICOM outputs the frame numbers of each object, classification and attribute. Make sure you substitute:

The <private_key_path> with the full path to your private key.
The <project_id> with the ID of your Project.

# Import dependencies
from encord import EncordUserClient
from encord.objects.ontology_element import OntologyElement
from encord.objects.attributes import Attribute
from encord.objects import ObjectInstance

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Replace <project_id> with the hash of your Project
project = user_client.get_project("<project_id>")

# A function to extract and print essential information for all attributes
def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
    print(f"Attribute name: {attribute.title}")
    print(f"Attribute hash: {attribute.feature_node_hash}")
    for answer_for_frames in object_instance.get_answer(attribute):
        print(f"Attribute answer \"{answer_for_frames.answer.title}\" is present on frames {answer_for_frames.ranges}")
        print ("Attribute answer hash " + answer_for_frames.answer.feature_node_hash)
        for attribute in answer_for_frames.answer.attributes:
            print(f"Attribute answer \"{answer_for_frames.answer.title}\" has nested attribute \"{attribute.title}\"")
            print_attributes(attribute, object_instance)

# Initialize label rows using bundles
label_rows = project.list_label_rows_v2()
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    # Print essential label information for all objects
    for object_instance in label_row.get_object_instances():
        print ("objectHash: " + object_instance.object_hash)
        print ("Object name: " + object_instance.object_name)
        print ("featureHash: " + object_instance.feature_hash)
        print ("uid: " + str(object_instance.ontology_item.uid))
        print ("Object color: " + object_instance.ontology_item.color)
        print ("Ontology shape: " + object_instance.ontology_item.shape)

        # Print the frame number and the location of the object on the frame
        for annotation in object_instance.get_annotations():
            print(f"Frame {annotation.frame} -> {annotation.coordinates}")

        # Print all attributes
        for attribute in object_instance.ontology_item.attributes:
            print_attributes(attribute, object_instance)

    # Print all essential classification information
    for classification_instance in label_row.get_classification_instances():
        print ("classificationHash: " + classification_instance.classification_hash)
        print ("Classification name: " + classification_instance.classification_name)
        print ("featureHash: " + classification_instance.feature_hash)
        print ("Classification answer: " + classification_instance.get_answer().value)
        print ("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)

        # Print the frame number(s) that a classification appears on
        for annotation in classification_instance.get_annotations():
            print("Classification appears on frame " + str(annotation.frame))

Export Objects, Classifications, and Attributes by Frame

Videos with variable frame rates can result in misplaced labels.

Range of Consecutive Frames

The following scripts download and print the labels for a specified range of frames in videos.

To export labels for a single frame, make the <start_frame_number> the same as the <end_frame_number>. For example, to export labels on the 13th frame set <start_frame_number> = 13, and <end_frame_number> = 13.


# Import dependencies
import json

from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
DATA_UNIT = "cherries-is"
OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json"
START_FRAME_NUMBER = 0
END_FRAME_NUMBER = 35
BUNDLE_SIZE = 100

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Load the project
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

# Get filtered label rows
label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
assert label_rows, f"No label rows found for data unit: {DATA_UNIT}"

# Initialize labels using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)


# Function to extract attributes in a structured format
def extract_attributes(attribute: Attribute, object_instance: ObjectInstance):
    try:
        answer = object_instance.get_answer(attribute)
    except Exception:
        answer = None
    return {
        "attribute_name": attribute.title,
        "attribute_hash": attribute.feature_node_hash,
        "attribute_answer": str(answer),
    }


# Result collection
results = []

# Loop over label rows
for label_row in label_rows:
    row_data = {
        "label_row_hash": label_row.label_hash,
        "data_title": label_row.data_title,
        "objects": [],
        "classifications": [],
    }

    # Process object annotations
    object_instances = label_row.get_object_instances()
    assert object_instances, f"No object instances found in label row {label_row.uid}"

    for object_instance in object_instances:
        annotations = object_instance.get_annotations()
        assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

        assert object_instance.ontology_item and object_instance.ontology_item.attributes, (
            f"No attributes found for object {object_instance.object_hash}"
        )

        for annotation in annotations:
            if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                obj_info = {
                    "frame": annotation.frame,
                    "object_hash": object_instance.object_hash,
                    "object_name": object_instance.object_name,
                    "feature_hash": object_instance.feature_hash,
                    "uid": str(object_instance.ontology_item.uid),
                    "color": object_instance.ontology_item.color,
                    "shape": object_instance.ontology_item.shape,
                    "label_location": str(annotation.coordinates),
                    "attributes": [],
                }

                print("Frame:", annotation.frame)
                print("objectHash:", object_instance.object_hash)
                print("Object name:", object_instance.object_name)
                print("featureHash:", object_instance.feature_hash)
                print("uid:", obj_info["uid"])
                print("Object color:", object_instance.ontology_item.color)
                print("Ontology shape:", object_instance.ontology_item.shape)
                print(f"Label location: {annotation.coordinates}")

                for attribute in object_instance.ontology_item.attributes:
                    attr_data = extract_attributes(attribute, object_instance)
                    obj_info["attributes"].append(attr_data)

                    print(f"Attribute name: {attr_data['attribute_name']}")
                    print(f"Attribute hash: {attr_data['attribute_hash']}")
                    print(f"Attribute answer: {attr_data['attribute_answer']}")

                row_data["objects"].append(obj_info)

    # Process classification annotations
    classification_instances = label_row.get_classification_instances()
    assert classification_instances is not None, f"No classification instances found in label row {label_row.uid}"

    for classification_instance in classification_instances:
        annotations = classification_instance.get_annotations()
        assert annotations, (
            f"No annotations found for classification instance {classification_instance.classification_hash}"
        )

        for annotation in annotations:
            if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                try:
                    answer = classification_instance.get_answer()
                    answer_value = answer.value
                    answer_hash = answer.feature_node_hash
                except Exception:
                    answer_value = None
                    answer_hash = None

                classification_info = {
                    "frame": annotation.frame,
                    "classification_hash": classification_instance.classification_hash,
                    "classification_name": classification_instance.classification_name,
                    "feature_hash": classification_instance.feature_hash,
                    "value": answer_value,
                    "answer_hash": answer_hash,
                }

                print("Classification hash:", classification_info["classification_hash"])
                print("Classification name:", classification_info["classification_name"])
                print("Feature hash:", classification_info["feature_hash"])
                print("Classification value:", classification_info["value"])
                print("Classification answer hash:", classification_info["answer_hash"])

                row_data["classifications"].append(classification_info)

    results.append(row_data)

# Save to JSON
assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must be a JSON file"

with open(OUTPUT_FILE_PATH, "w") as f:
    json.dump(results, f, indent=4)

print(f"\nData saved to: {OUTPUT_FILE_PATH}")

List of non-consecutive frames

The following scripts download and print the labels for specific frames in videos. Make sure you substitute:

The <private_key_path> with the full path to your private key.
The <project_hash> with the hash of your Project.
The <task_name> with the name of the file (in Encord) you want to export labels for (if using the task-specific script).
Replace the numbers in the list [10, 20, 30, 40] with the frames you want to export labels for.

# Import dependencies
from encord import EncordUserClient
from encord.objects.ontology_element import OntologyElement
from encord.objects.attributes import Attribute, Option
from encord.objects import ObjectInstance
from collections.abc import Iterable

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Replace with the hash of your Project
project = user_client.get_project("<project_hash>")

# Function to extract and print essential information for all attributes
def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
    print(f"Attribute name: {attribute.title}")
    print(f"Attribute hash: {attribute.feature_node_hash}")
    print(f"Attribute answer: {object_instance.get_answer(attribute)}")

# List of specific frames to be exported
specific_frames = [10, 20, 30, 40]  # Replace with your specific frame numbers

# Initialize label rows using bundles
label_rows = project.list_label_rows_v2()
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    # Print essential label information for all objects
    for object_instance in label_row.get_object_instances():
        for annotation in object_instance.get_annotations():
            if annotation.frame in specific_frames:
                print("Frame: " + str(annotation.frame))
                print("objectHash: " + object_instance.object_hash)
                print("Object name: " + object_instance.object_name)
                print("featureHash: " + object_instance.feature_hash)
                print("uid: " + str(object_instance.ontology_item.uid))
                print("Object color: " + object_instance.ontology_item.color)
                print("Ontology shape: " + object_instance.ontology_item.shape)
                print(f"Label location: {annotation.coordinates}")

                # Print all attributes
                for attribute in object_instance.ontology_item.attributes:
                    print_attributes(attribute, object_instance)

    # Print essential classification information on specified frames
    for classification_instance in label_row.get_classification_instances():
        for annotation in classification_instance.get_annotations():
            if annotation.frame in specific_frames:
                print("Classification hash: " + classification_instance.classification_hash)
                print("Classification name: " + classification_instance.classification_name)
                print("Feature hash: " + classification_instance.feature_hash)
                print("Classification value: " + classification_instance.get_answer().value)
                print("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)

Saving Frames with Labels

ffmpeg can be used to save all frames with labels as an image, to be used in machine learning applications. The script below shows how this is done when exporting a list of non-consecutive frames from a specific video.

ffmpeg must be installed for this script to work.

Make sure you substitute:

The <output_folder_path> with the full path to the output folder you want the output image files to be saved.
The <private_key_path> with the full path to your private key.
The <project_id> with the ID of your Project.
The <task_name> with the name of the file in Encord you want to export labels for.
The <path_to_your_video_file> with the full path to the video file you are exporting labels for.
The def get_video_path function to return your actual video path corresponding to the label row.
Replace the numbers in the list [10, 20, 30, 40] with the frames you want to export labels for.

# Import dependencies
from encord import EncordUserClient
from encord.objects.ontology_element import OntologyElement
from encord.objects.attributes import Attribute, Option
from encord.objects import ObjectInstance
from collections.abc import Iterable
import subprocess
import os

# Specify the output folder path. Replace with your desired folder path
output_folder = "<output_folder_path>"

# Create the output folder if it doesn't exist
if not os.path.exists(output_folder):
    os.makedirs(output_folder)

def extract_frame_to_image(video_file, frame_number, output_file):
    """
    Uses FFmpeg to extract a specific frame from a video and saves it as an image.
    """
    ffmpeg_command = [
        'ffmpeg', '-i', video_file, '-vf', f'select=eq(n\,{frame_number})',
        '-vframes', '1', output_file
    ]
    subprocess.run(ffmpeg_command, check=True)

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Replace with the ID of your Project
project = user_client.get_project("<project_id>")

# Function to extract and print essential information for all attributes
def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
    print(f"Attribute name: {attribute.title}")
    print(f"Attribute hash: {attribute.feature_node_hash}")
    print(f"Attribute answer: {object_instance.get_answer(attribute)}")

# List of specific frames to be exported. Replace with your specific frame numbers
specific_frames = [10, 20, 30, 40]

# Path to the video file you are exporting labels for
def get_video_path(label_row)
    return "<path_to_your_video_file>"

# Initialize label rows using bundles
label_rows = project.list_label_rows_v2()
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    # Print essential label information for all objects
    video_path = get_video_path(label_row)
    for object_instance in label_row.get_object_instances():
        for annotation in object_instance.get_annotations():
            if annotation.frame in specific_frames:
                print("Frame: " + str(annotation.frame))
                print("objectHash: " + object_instance.object_hash)
                print("Object name: " + object_instance.object_name)
                print("featureHash: " + object_instance.feature_hash)
                print("uid: " + str(object_instance.ontology_item.uid))
                print("Object color: " + object_instance.ontology_item.color)
                print("Ontology shape: " + object_instance.ontology_item.shape)
                print(f"Label location: {annotation.coordinates}")

                # Define the output path for the image
                output_image_path = os.path.join(output_folder, f"frame_{annotation.frame}.png")

                # Extract and save the specific frame as an image
                extract_frame_to_image(video_path, annotation.frame, output_image_path)

                # Print all attributes
                for attribute in object_instance.ontology_item.attributes:
                    print_attributes(attribute, object_instance)

    # Print essential classification information on specified frames
    for classification_instance in label_row.get_classification_instances():
        for annotation in classification_instance.get_annotations():
            if annotation.frame in specific_frames:
                print("Classification hash: " + classification_instance.classification_hash)
                print("Classification name: " + classification_instance.classification_name)
                print("Feature hash: " + classification_instance.feature_hash)
                print("Classification value: " + classification_instance.get_answer().value)
                print("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)

Label Editor Coordinates

All label locations are exported as normalized coordinates ranging from 0 to 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 width.
“y” and “w” coordinates of a label should be multiplied by the pixel height.

Export all Consensus labels

Consensus Projects introduce the concept of BRANCHES within the task workflow. A Consensus annotation task consists of a MAIN branch and one sub-branch for each Annotator. Each time an annotator saves or submits a task, the annotator creates their own branch on a task. The MAIN branch remains empty of labels until a reviewer specifies that a task is in consensus. When consensus is reached, the labels that are the best representative set move to the MAIN branch. To export all labels (labels generated for every branch on every data unit) from your Consensus Project, use include_all_branches=True. Make sure you:

Substitute the <private_key_path> with the full path to your private key.
Substitute the <project_id> with the ID of your Project.
If you only want to export the MAIN branch, remove include_all_label_branches=True.

Adding include_children=True to list_label_rows_v2() includes all labels from Data Groups.
Adding include_all_label_branches=True to list_label_rows_v2() includes all labels from all branches in Consensus Projects.


import json

from encord import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json"
BUNDLE_SIZE = 100

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project. Replace <project_id> with the ID of the Project you want to export labels for.
project = user_client.get_project(PROJECT_ID)

# Downloads a local copy of all the labels
# Without the include_all_label_branches flag only the MAIN branch labels export
label_rows = project.list_label_rows_v2(include_children=True, include_all_label_branches=True)

output_data = []  # This will hold the output data to be saved as JSON

# Initialize label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Collecting data for JSON output
for label_row in label_rows:
    label_row_data = {
        "title": label_row.data_title,
        "branch": label_row.branch_name,
        "objects": [],
        "classifications": [],
    }

    # Collect object instances
    for object_instance in label_row.get_object_instances():
        object_data = {
            "object_hash": object_instance.object_hash,
            "object_name": object_instance.object_name,
            "feature_hash": object_instance.feature_hash,
            "ontology_item": {
                "uid": object_instance.ontology_item.uid,
                "color": object_instance.ontology_item.color,
                "shape": object_instance.ontology_item.shape,
                "attributes": [
                    {"name": attribute.name, "value": attribute.value}
                    for attribute in object_instance.ontology_item.attributes
                ],
            },
            "annotations": [
                {"frame": annotation.frame, "coordinates": annotation.coordinates}
                for annotation in object_instance.get_annotations()
            ],
        }
        label_row_data["objects"].append(object_data)

    # Collect classification instances
    for classification_instance in label_row.get_classification_instances():
        classification_data = {
            "classification_hash": classification_instance.classification_hash,
            "classification_name": classification_instance.classification_name,
            "feature_hash": classification_instance.feature_hash,
            "classification_answer": {
                "value": classification_instance.get_answer().value,
                "hash": classification_instance.get_answer().feature_node_hash,
            },
            "annotations": [{"frame": annotation.frame} for annotation in classification_instance.get_annotations()],
        }
        label_row_data["classifications"].append(classification_data)

    # Add label row data to the output list
    output_data.append(label_row_data)

# Saving to JSON file
output_file_path = OUTPUT_FILE_PATH  # Replace with the desired file path
with open(output_file_path, "w") as json_file:
    json.dump(output_data, json_file, indent=4)

print(f"Output saved to {output_file_path}")

Export all Data Group labels

Adding include_children=True to list_label_rows_v2() includes all labels from Data Groups.
Adding include_all_label_branches=True to list_label_rows_v2() includes all labels from all branches in Consensus Projects.


# Import dependencies
import json
import os

from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
BUNDLE_SIZE = 100  # Customize as needed
OUTPUT_JSON = "/Users/chris-encord/export-label-rows.json" # Replace with file path to save JSON output file

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

# Get label rows for your Project
label_rows = project.list_label_rows_v2(include_children=True, include_all_label_branches=True)
assert label_rows, f"No label rows found in project {PROJECT_ID}"

# Initialize label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Collect all label row data
all_label_rows = [label_row.to_encord_dict() for label_row in label_rows]
assert all_label_rows, "No label row data collected for export"

# Save the collected label rows data to a JSON file
output_file = OUTPUT_JSON
assert output_file.endswith(".json"), "Output file must be a .json file"

with open(output_file, "w") as file:
    json.dump(all_label_rows, file, indent=4)

print(f"Label rows have been saved to {output_file}.")

Bulk Export Labels

Use the bundle function to significantly improve export performance.

We strongly recommend NOT bundling more than 1000 operations at once, because bundling more than 1000 operations can reduce performance instead of improving performance.

In the following code, ensure you replace:

<private_key_path> with the full path to your private key.
<project-id> with the ID of the Project you want to export labels for.
#Perform label row operation before in this loop with the label row operations you want to perform.
Optionally, change the value of BUNDLE_SIZE to suit your needs. We strongly recommend NOT bundling more than 1000 operations at once, because bundling more than 1000 operations can reduce performance instead of improving performance.


# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import (
    Object,
    ObjectInstance,
    OntologyStructure,
)
from encord.objects.coordinates import BoundingBoxCoordinates

SSH_PATH = "<private-key-path>"
PROJECT_ID = "<project-id>"

# Authenticate
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path=SSH_PATH)

# Gets Project to export labels
project: Project = user_client.get_project(PROJECT_ID)

label_rows = project.list_label_rows_v2()
BUNDLE_SIZE = 100

# Initialize label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:

    # Write any label row operation here. For example import, or export label rows.


# Saving changes to label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.save(bundle=bundle)

COCO Format Export

Use the following script to bulk export labels in the COCO format. Ensure that you replace:

<private-key-path> with the full path to your private key for authentication.
<project-id> with the ID of the Project for which you want to export labels.

COCO Export

from encord import EncordUserClient
import json


SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the SSH key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the unique ID for the Project

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

project = user_client.get_project(PROJECT_ID)
coco_labels = project.export_coco_labels()

# Save the coco_labels dictionary to a .json file
with open("coco_labels.json", "w") as json_file:
    json.dump(coco_labels, json_file)

Get Started

General

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

Export Labels as JSON

Export Attributes

Export Objects and Classifications

Export Objects, Classifications, and Attributes by Frame

Range of Consecutive Frames

List of non-consecutive frames

Saving Frames with Labels

Label Editor Coordinates

Export all Consensus labels

Export all Data Group labels

Bulk Export Labels

COCO Format Export

Get Started

General

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

​Export Labels as JSON

​Export Attributes

​Export Objects and Classifications

​Export Objects, Classifications, and Attributes by Frame

​Range of Consecutive Frames

​List of non-consecutive frames

​Saving Frames with Labels

​Label Editor Coordinates

​Export all Consensus labels

​Export all Data Group labels

​Bulk Export Labels

​COCO Format Export

Export Labels as JSON

Export Attributes

Export Objects and Classifications

Export Objects, Classifications, and Attributes by Frame

Range of Consecutive Frames

List of non-consecutive frames

Saving Frames with Labels

Label Editor Coordinates

Export all Consensus labels

Export all Data Group labels

Bulk Export Labels

COCO Format Export