| 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. |
| 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 hash | The unique identifier for the attribute, as defined in the Ontology. |
| Attribute answer | The name of the attribute value, as defined in the Ontology. For example “Sitting” |
| Attribute answer hash | 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_all_label_branches=Truetolist_label_rows_v2()includes all labels from all branches in Consensus Projects.
Classification format (SDK v0.1.205 and later):
to_encord_dict() no longer lists classifications frame by frame. The classifications array on each frame in data_units is empty. Each classification is listed once in classification_answers, keyed by its classificationHash, and its range lists the frames it appears on as inclusive [start, end] pairs, for example [[0, 3]]. Read classifications from classification_answers, or use get_classification_instances() in the SDK.We recommend using
bundle in your scripts to improve performance. Keep bundle sizes under 1000 operations. Bundles of more than 1000 operations can degrade performance rather than improve performance.The optimal bundle size depends on your use case. For example, for videos with a large number of labels, start with 20 operations and adjust up or down based on performance.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 access 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()
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. Frame numbers start at 0. Single images only have a single frame (frame 0).ObjectInstance.get_answer(attribute) returns a different type depending on the attribute:
| Attribute | Answered | Unanswered |
|---|---|---|
| Static radio button | The selected Option (a NestableOption, which can have nested attributes) | None |
| Static checklist | A list of the selected Options | [] |
| Static text | A str | None |
| Static numeric | A number | None |
| Dynamic (any type) | A list of AnswerForFrames(answer, ranges): each answer, with the frame ranges it is on | [] |
Dynamic, with filter_frame=N | The same list, holding only the answer on frame N. Its ranges still list every frame that answer is on | [] |
filter_frame has no effect on static attributes. The scripts below use a small get_answer_on_frame() helper that handles both cases.
We recommend using the script for exporting all attributes if the Project uses
an Ontology with nested attributes.
# Import dependencies
import json
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, TextAttribute
from encord.objects.ontology_object_instance import AnswersForFrames
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-is" # Replace with the name of the file (data unit) to export labels for
OUTPUT_FILE_PATH = "/Users/chris-encord/text_attributes_output.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# Create user client using access 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# 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 = get_answer_on_frame(object_instance, attribute, frame_number)
return {
"frame": frame_number,
"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:
# A Data Group stores its labels on its spaces (one per file), not on the parent label row
object_instances = label_row.get_object_instances()
for space in label_row.get_spaces():
object_instances.extend(space.get_object_instances())
for object_instance in object_instances:
annotations = object_instance.get_annotations()
ontology_item = object_instance.ontology_item
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}")
# Import dependencies
import json
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, RadioAttribute
from encord.objects.ontology_object_instance import AnswersForFrames
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-010.jpg" # Replace with the name of the file (data unit) to export labels for
OUTPUT_FILE_PATH = "/Users/chris-encord/radio_attribute_output.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# Create user client using access 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",
)
# Get project and label rows
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"
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 label rows using bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Prepare data structure to collect all results
output_data = []
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Function to extract info from RadioAttribute (recursively if nested)
def extract_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
frame_data = []
if isinstance(attribute, RadioAttribute):
attribute_answers = get_answer_on_frame(object_instance, attribute, frame_number)
if not isinstance(attribute_answers, list):
attribute_answers = [attribute_answers]
for answer in attribute_answers:
if answer is None:
continue # Skip empty answers
answer_data = {
"frame": frame_number,
"attribute_name": attribute.title,
"attribute_hash": attribute.feature_node_hash,
"answer_title": answer.title,
"answer_hash": answer.feature_node_hash,
"nested_attributes": [],
}
if hasattr(answer, "attributes") and answer.attributes:
for nested_attribute in answer.attributes:
nested_data = extract_attributes(nested_attribute, object_instance, frame_number)
if nested_data:
answer_data["nested_attributes"].extend(nested_data)
frame_data.append(answer_data)
return frame_data
# Loop through label rows and extract attribute data
for label_row in label_rows:
# A Data Group stores its labels on its spaces (one per file), not on the parent label row
object_instances = label_row.get_object_instances()
for space in label_row.get_spaces():
object_instances.extend(space.get_object_instances())
for object_instance in object_instances:
annotations = object_instance.get_annotations()
ontology_item = object_instance.ontology_item
for annotation in annotations:
for attribute in ontology_item.attributes:
attr_data = extract_attributes(attribute, object_instance, annotation.frame)
if attr_data:
output_data.extend(attr_data)
# 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(output_data, f, indent=4)
print(f"Radio attribute data saved to {OUTPUT_FILE_PATH}")
# Import dependencies
import json
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, ChecklistAttribute
from encord.objects.ontology_object_instance import AnswersForFrames
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-010.jpg" # Replace with the name of the file (data unit) to export labels for
OUTPUT_FILE_PATH = "/Users/chris-encord/checklist_attributes_output.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# Create user client using access 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 and filter label rows
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"
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 label rows using bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Function to extract checklist attributes in structured format
def extract_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
if isinstance(attribute, ChecklistAttribute):
attribute_answers = get_answer_on_frame(object_instance, attribute, frame_number)
if not isinstance(attribute_answers, list):
attribute_answers = [attribute_answers]
return {
"frame": frame_number,
"attribute_name": attribute.title,
"attribute_hash": attribute.feature_node_hash,
"answers": [
{
"title": answer.title,
"hash": answer.feature_node_hash,
}
for answer in attribute_answers
if answer
],
}
return None
# Collect data for saving
results = []
# Iterate through label rows and extract checklist attribute data
for label_row in label_rows:
# A Data Group stores its labels on its spaces (one per file), not on the parent label row
object_instances = label_row.get_object_instances()
for space in label_row.get_spaces():
object_instances.extend(space.get_object_instances())
for object_instance in object_instances:
annotations = object_instance.get_annotations()
ontology_item = object_instance.ontology_item
for annotation in annotations:
for attribute in ontology_item.attributes:
attr_data = extract_attributes(attribute, object_instance, annotation.frame)
if attr_data:
results.append(attr_data)
print(f"Frame {attr_data['frame']}:")
print(f"Checklist Attribute name: {attr_data['attribute_name']}")
for answer in attr_data["answers"]:
print(f"Checklist answer: {answer['title']}")
print(f"Checklist answer hash: {answer['hash']}")
# Save 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"\nChecklist attribute data saved to: {OUTPUT_FILE_PATH}")
# Import dependencies
import json
from typing import cast
from collections.abc import Iterable
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, ChecklistAttribute, RadioAttribute, TextAttribute
from encord.objects.ontology_object_instance import AnswersForFrames
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-010.jpg" # Replace with the name of the file (data unit) to export labels for
OUTPUT_FILE_PATH = "/Users/chris-encord/all_attributes_output.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# Create user client using access 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 project and label rows
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"
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 label rows using bundle
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Container for structured results
results = []
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Function to collect and print attributes
def extract_and_print_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
attr_data = {
"frame": frame_number,
"attribute_name": attribute.title,
"attribute_hash": attribute.feature_node_hash,
"attribute_type": None,
"answers": [],
}
if isinstance(attribute, TextAttribute):
attr_data["attribute_type"] = "TextAttribute"
text_answer = get_answer_on_frame(object_instance, attribute, frame_number)
attr_data["answers"].append({"text": text_answer or "No attribute answer"})
elif isinstance(attribute, RadioAttribute):
attr_data["attribute_type"] = "RadioAttribute"
answer = get_answer_on_frame(object_instance, attribute, frame_number)
if answer:
answer_data = {"title": answer.title, "hash": answer.feature_node_hash, "nested_attributes": []}
if hasattr(answer, "attributes") and answer.attributes:
for nested_attribute in answer.attributes:
nested_result = extract_and_print_attributes(nested_attribute, object_instance, frame_number)
if nested_result:
answer_data["nested_attributes"].append(nested_result)
attr_data["answers"].append(answer_data)
else:
attr_data["answers"].append({"note": "No attribute answer"})
elif isinstance(attribute, ChecklistAttribute):
attr_data["attribute_type"] = "ChecklistAttribute"
answers = get_answer_on_frame(object_instance, attribute, frame_number)
if answers:
if not isinstance(answers, Iterable):
answers = [answers]
for answer in answers:
attr_data["answers"].append({"title": answer.title, "hash": answer.feature_node_hash})
else:
attr_data["answers"].append({"note": "No attribute answer"})
# Print the same info (optional)
print(f"Frame {attr_data['frame']}: {attr_data['attribute_type']} name: {attr_data['attribute_name']}")
for answer in attr_data["answers"]:
if "title" in answer:
print(f"Answer: {answer['title']}")
print(f"Answer hash: {answer['hash']}")
elif "text" in answer:
print(f"Answer: {answer['text']}")
elif "note" in answer:
print(f"Note: {answer['note']}")
if "nested_attributes" in answer:
for nested in answer["nested_attributes"]:
print(f"Nested attribute: {nested['attribute_name']} ({nested['attribute_hash']})")
return attr_data
# Process all label rows
for label_row in label_rows:
# A Data Group stores its labels on its spaces (one per file), not on the parent label row
object_instances = label_row.get_object_instances()
for space in label_row.get_spaces():
object_instances.extend(space.get_object_instances())
for object_instance in object_instances:
annotations = object_instance.get_annotations()
for annotation in annotations:
for attribute in object_instance.ontology_item.attributes:
extracted = extract_and_print_attributes(attribute, object_instance, annotation.frame)
if extracted:
results.append(extracted)
# 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"\nAll attribute data saved to: {OUTPUT_FILE_PATH}")
Export Objects and Classifications
The following scripts print the top-level answer of each classification (radio
button, checklist, or text). Answers to nested classification questions are not
printed.
# User input.
# Import dependencies
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import NestableOption, Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your 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)
# Get a readable value and hash for any answer: an Option for radio buttons, a list of
# Options for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.title, answer.feature_node_hash
if isinstance(answer, list):
return [option.title for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# Print one attribute answer. ranges lists the frames for a dynamic attribute, and is None for a static one
def print_answer(answer, ranges, object_instance: ObjectInstance):
value, answer_hash = describe_answer(answer)
if ranges is None:
print(f"Attribute answer: {value}")
else:
print(f"Attribute answer \"{value}\" is present on frames {ranges}")
print(f"Attribute answer hash: {answer_hash}")
# A radio button answer can have nested attributes
if isinstance(answer, NestableOption):
for nested_attribute in answer.attributes:
print(f"Attribute answer \"{value}\" has nested attribute \"{nested_attribute.title}\"")
print_attributes(nested_attribute, object_instance)
# A function to extract and print essential information for all attributes, including nested attributes
def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
if attribute.dynamic:
# A dynamic attribute can change between frames: get_answer() returns each answer with its frames
for answer_for_frames in cast(AnswersForFrames, object_instance.get_answer(attribute)):
print_answer(answer_for_frames.answer, answer_for_frames.ranges, object_instance)
else:
# A static attribute has one answer for the whole object
print_answer(object_instance.get_answer(attribute), None, 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 ("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)
answer, answer_hash = describe_answer(classification_instance.get_answer())
print (f"Classification answer: {answer}")
print (f"Classification answer hash: {answer_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))
# Import dependencies
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import NestableOption, Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your 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)
# Get a readable value and hash for any answer: an Option for radio buttons, a list of
# Options for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.title, answer.feature_node_hash
if isinstance(answer, list):
return [option.title for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# Print one attribute answer. ranges lists the frames for a dynamic attribute, and is None for a static one
def print_answer(answer, ranges, object_instance: ObjectInstance):
value, answer_hash = describe_answer(answer)
if ranges is None:
print(f"Attribute answer: {value}")
else:
print(f"Attribute answer \"{value}\" is present on frames {ranges}")
print(f"Attribute answer hash: {answer_hash}")
# A radio button answer can have nested attributes
if isinstance(answer, NestableOption):
for nested_attribute in answer.attributes:
print(f"Attribute answer \"{value}\" has nested attribute \"{nested_attribute.title}\"")
print_attributes(nested_attribute, object_instance)
# A function to extract and print essential information for all attributes, including nested attributes
def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
if attribute.dynamic:
# A dynamic attribute can change between frames: get_answer() returns each answer with its frames
for answer_for_frames in cast(AnswersForFrames, object_instance.get_answer(attribute)):
print_answer(answer_for_frames.answer, answer_for_frames.ranges, object_instance)
else:
# A static attribute has one answer for the whole object
print_answer(object_instance.get_answer(attribute), None, 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 ("Object color: " + object_instance.ontology_item.color)
print ("Ontology shape: " + object_instance.ontology_item.shape)
for annotation in object_instance.get_annotations():
print(f"Frame {annotation.frame} -> {annotation.coordinates}")
for attribute in object_instance.ontology_item.attributes:
print_attributes(attribute, object_instance)
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)
answer, answer_hash = describe_answer(classification_instance.get_answer())
print (f"Classification answer: {answer}")
print (f"Classification answer hash: {answer_hash}")
for annotation in classification_instance.get_annotations():
print("Classification appears on frame " + str(annotation.frame))
objectHash: HI5408US
Object name: Chicken
featureHash: p6T5NeQ4
Object color: #D33115
Ontology shape: bounding_box
Frame 101 -> BoundingBoxCoordinates(height=0.526, width=0.2514, top_left_x=0.5826, top_left_y=0.2431)
Frame 102 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.578, top_left_y=0.2413)
Frame 103 -> BoundingBoxCoordinates(height=0.5469, width=0.2615, top_left_x=0.5752, top_left_y=0.2378)
Frame 104 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5798, top_left_y=0.2396)
Frame 105 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5661, top_left_y=0.2396)
Frame 106 -> BoundingBoxCoordinates(height=0.5469, width=0.2615, top_left_x=0.5633, top_left_y=0.2361)
Frame 107 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5532, top_left_y=0.2361)
Frame 108 -> BoundingBoxCoordinates(height=0.526, width=0.2514, top_left_x=0.556, top_left_y=0.2413)
Attribute name: Walking or Sitting?
Attribute hash: pHXXPbuc
Attribute answer "Walking" is present on frames [(101:104)]
Attribute answer hash: 6qeufh3l
Attribute answer "Sitting" is present on frames [(105:108)]
Attribute answer hash: hkInN4Sd
classificationHash: gffOkg9l
Classification name: Day or Night?
featureHash: FA6pAde3
Classification answer: Day
Classification answer hash: gasjasd
Classification appears on frame 352
Export Objects, Classifications, and Attributes by Frame
Videos with variable frame
rates
can result in misplaced labels.
The scripts in this section read labels with
get_frame_view(), which only covers labels stored on the label row itself. A Data Group stores its labels on its spaces, so these scripts return no labels for a Data Group. To export Data Group labels, see Export all Data Group 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, set
START_FRAME_NUMBER and END_FRAME_NUMBER to the same value. Frame numbers start at 0, so to export labels on the 13th frame set START_FRAME_NUMBER = 12 and END_FRAME_NUMBER = 12.
# Import dependencies
import json
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-is" # Replace with the name of the file (data unit) to export labels for
OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json" # Replace with the path of the output JSON file
START_FRAME_NUMBER = 0 # Replace with the first frame to export. Frame numbers start at 0
END_FRAME_NUMBER = 35 # Replace with the last frame to export (inclusive)
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Get the value and hash of an answer: an Option for radio buttons, a list of Options
# for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.value, answer.feature_node_hash
if isinstance(answer, list):
return [option.value for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# 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": [],
}
# get_frame_view() returns only the labels on one frame.
# Frames after the last frame of the file return no labels.
for frame_number in range(START_FRAME_NUMBER, END_FRAME_NUMBER + 1):
frame_view = label_row.get_frame_view(frame_number)
# Objects on this frame
for object_instance in frame_view.get_object_instances():
annotation = object_instance.get_annotation(frame_number)
ontology_item = object_instance.ontology_item
obj_info = {
"frame": frame_number,
"object_hash": object_instance.object_hash,
"object_name": object_instance.object_name,
"feature_hash": object_instance.feature_hash,
"color": ontology_item.color,
"shape": ontology_item.shape.value,
"label_location": annotation.coordinates.to_dict(),
"attributes": [],
}
print("Frame:", frame_number)
print("objectHash:", object_instance.object_hash)
print("Object name:", object_instance.object_name)
print("featureHash:", object_instance.feature_hash)
print("Object color:", ontology_item.color)
print("Ontology shape:", ontology_item.shape.value)
print(f"Label location: {annotation.coordinates}")
for attribute in ontology_item.attributes:
answer_value, answer_hash = describe_answer(get_answer_on_frame(object_instance, attribute, frame_number))
obj_info["attributes"].append(
{
"attribute_name": attribute.title,
"attribute_hash": attribute.feature_node_hash,
"attribute_answer": answer_value,
"attribute_answer_hash": answer_hash,
}
)
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
print(f"Attribute answer: {answer_value}")
print(f"Attribute answer hash: {answer_hash}")
row_data["objects"].append(obj_info)
# Classifications on this frame
for classification_instance in frame_view.get_classification_instances():
answer_value, answer_hash = describe_answer(classification_instance.get_answer())
classification_info = {
"frame": frame_number,
"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("Frame:", frame_number)
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}")
# Import dependencies
import json
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json" # Replace with the path of the output JSON file
START_FRAME_NUMBER = 0 # Replace with the first frame to export. Frame numbers start at 0
END_FRAME_NUMBER = 35 # Replace with the last frame to export (inclusive)
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# 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"
# Retrieve all label rows
label_rows = project.list_label_rows_v2()
assert label_rows, "No label rows returned from the project"
# 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Get the value and hash of an answer: an Option for radio buttons, a list of Options
# for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.value, answer.feature_node_hash
if isinstance(answer, list):
return [option.value for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# 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": [],
}
# get_frame_view() returns only the labels on one frame.
# Frames after the last frame of the file return no labels.
for frame_number in range(START_FRAME_NUMBER, END_FRAME_NUMBER + 1):
frame_view = label_row.get_frame_view(frame_number)
# Objects on this frame
for object_instance in frame_view.get_object_instances():
annotation = object_instance.get_annotation(frame_number)
ontology_item = object_instance.ontology_item
obj_info = {
"frame": frame_number,
"object_hash": object_instance.object_hash,
"object_name": object_instance.object_name,
"feature_hash": object_instance.feature_hash,
"color": ontology_item.color,
"shape": ontology_item.shape.value,
"label_location": annotation.coordinates.to_dict(),
"attributes": [],
}
print("Frame:", frame_number)
print("objectHash:", object_instance.object_hash)
print("Object name:", object_instance.object_name)
print("featureHash:", object_instance.feature_hash)
print("Object color:", ontology_item.color)
print("Ontology shape:", ontology_item.shape.value)
print(f"Label location: {annotation.coordinates}")
for attribute in ontology_item.attributes:
answer_value, answer_hash = describe_answer(get_answer_on_frame(object_instance, attribute, frame_number))
obj_info["attributes"].append(
{
"attribute_name": attribute.title,
"attribute_hash": attribute.feature_node_hash,
"attribute_answer": answer_value,
"attribute_answer_hash": answer_hash,
}
)
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
print(f"Attribute answer: {answer_value}")
print(f"Attribute answer hash: {answer_hash}")
row_data["objects"].append(obj_info)
# Classifications on this frame
for classification_instance in frame_view.get_classification_instances():
answer_value, answer_hash = describe_answer(classification_instance.get_answer())
classification_info = {
"frame": frame_number,
"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("Frame:", frame_number)
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}")
Frame: 0
objectHash: U88+HXj4
Object name: Person
featureHash: AaaPMAgE
Object color: #15d3bc
Ontology shape: bounding_box
Label location: BoundingBoxCoordinates(height=0.519561557605036, width=0.15380023056653513, top_left_x=0.43242033102766797, top_left_y=0.0028114478114478862)
Attribute name: Man or woman
Attribute hash: X0Xhz9ip
Attribute answer: Man
Attribute answer hash: MN57hMep
Frame: 35
objectHash: nZWuD66O
Object name: Person
featureHash: AaaPMAgE
Object color: #15d3bc
Ontology shape: bounding_box
Label location: BoundingBoxCoordinates(height=0.46671424388815697, width=0.1688282279314888, top_left_x=0.37747550230566534, top_left_y=0.07887095593617346)
Attribute name: Man or woman
Attribute hash: X0Xhz9ip
Attribute answer: None
Attribute answer hash: None
Frame: 35
Classification hash: biZZZov4
Classification name: Day or Night?
Feature hash: T+P+wwjw
Classification value: Day
Classification answer hash: t+QtqkFp
Data saved to: /Users/chris-encord/frame_range_output.json
List of non-consecutive frames
The following scripts download and print the labels for specific frames in videos. Before you run a script, replace the values under# User input. Frame numbers start at 0.
# Import dependencies
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-vid-001.mp4" # Replace with the name of the file (data unit) to export labels for
SPECIFIC_FRAMES = [10, 20, 30, 40] # Replace with the frames to export. Frame numbers start at 0
# 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Get a readable value and hash for any answer: an Option for radio buttons, a list of
# Options for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.title, answer.feature_node_hash
if isinstance(answer, list):
return [option.title for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# Print an attribute and its answer on one frame
def print_attribute(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
value, answer_hash = describe_answer(get_answer_on_frame(object_instance, attribute, frame_number))
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
print(f"Attribute answer: {value}")
print(f"Attribute answer hash: {answer_hash}")
# Initialize label rows using bundles
label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
with project.create_bundle() as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
for label_row in label_rows:
for frame_number in SPECIFIC_FRAMES:
# get_frame_view() returns only the labels on one frame.
# Frames after the last frame of the file return no labels.
frame_view = label_row.get_frame_view(frame_number)
object_instances = frame_view.get_object_instances()
# Print essential label information for all objects on this frame
for object_instance in object_instances:
annotation = object_instance.get_annotation(frame_number)
print(f"Frame: {frame_number}")
print(f"objectHash: {object_instance.object_hash}")
print(f"Object name: {object_instance.object_name}")
print(f"featureHash: {object_instance.feature_hash}")
print(f"Object color: {object_instance.ontology_item.color}")
print(f"Ontology shape: {object_instance.ontology_item.shape.value}")
print(f"Label location: {annotation.coordinates}")
# Print all attributes
for attribute in object_instance.ontology_item.attributes:
print_attribute(attribute, object_instance, frame_number)
# Print essential classification information on this frame
for classification_instance in frame_view.get_classification_instances():
value, answer_hash = describe_answer(classification_instance.get_answer())
print(f"Frame: {frame_number}")
print(f"Classification hash: {classification_instance.classification_hash}")
print(f"Classification name: {classification_instance.classification_name}")
print(f"Feature hash: {classification_instance.feature_hash}")
print(f"Classification value: {value}")
print(f"Classification answer hash: {answer_hash}")
# Import dependencies
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
SPECIFIC_FRAMES = [10, 20, 30, 40] # Replace with the frames to export. Frame numbers start at 0
# 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Get a readable value and hash for any answer: an Option for radio buttons, a list of
# Options for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.title, answer.feature_node_hash
if isinstance(answer, list):
return [option.title for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# Print an attribute and its answer on one frame
def print_attribute(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
value, answer_hash = describe_answer(get_answer_on_frame(object_instance, attribute, frame_number))
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
print(f"Attribute answer: {value}")
print(f"Attribute answer hash: {answer_hash}")
# 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:
for frame_number in SPECIFIC_FRAMES:
# get_frame_view() returns only the labels on one frame.
# Frames after the last frame of the file return no labels.
frame_view = label_row.get_frame_view(frame_number)
object_instances = frame_view.get_object_instances()
# Print essential label information for all objects on this frame
for object_instance in object_instances:
annotation = object_instance.get_annotation(frame_number)
print(f"Frame: {frame_number}")
print(f"objectHash: {object_instance.object_hash}")
print(f"Object name: {object_instance.object_name}")
print(f"featureHash: {object_instance.feature_hash}")
print(f"Object color: {object_instance.ontology_item.color}")
print(f"Ontology shape: {object_instance.ontology_item.shape.value}")
print(f"Label location: {annotation.coordinates}")
# Print all attributes
for attribute in object_instance.ontology_item.attributes:
print_attribute(attribute, object_instance, frame_number)
# Print essential classification information on this frame
for classification_instance in frame_view.get_classification_instances():
value, answer_hash = describe_answer(classification_instance.get_answer())
print(f"Frame: {frame_number}")
print(f"Classification hash: {classification_instance.classification_hash}")
print(f"Classification name: {classification_instance.classification_name}")
print(f"Feature hash: {classification_instance.feature_hash}")
print(f"Classification value: {value}")
print(f"Classification answer hash: {answer_hash}")
Frame: 10
objectHash: U88+HXj4
Object name: Person
featureHash: AaaPMAgE
Object color: #15d3bc
Ontology shape: bounding_box
Label location: BoundingBoxCoordinates(height=0.519561557605036, width=0.15380023056653513, top_left_x=0.43242033102766797, top_left_y=0.0028114478114478862)
Attribute name: Man or woman
Attribute hash: X0Xhz9ip
Attribute answer: Man
Attribute answer hash: MN57hMep
Frame: 20
objectHash: nZWuD66O
Object name: Person
featureHash: AaaPMAgE
Object color: #15d3bc
Ontology shape: bounding_box
Label location: BoundingBoxCoordinates(height=0.46671424388815697, width=0.1688282279314888, top_left_x=0.37747550230566534, top_left_y=0.07887095593617346)
Attribute name: Man or woman
Attribute hash: X0Xhz9ip
Attribute answer: None
Attribute answer hash: None
Frame: 20
Classification hash: biZZZov4
Classification name: Day or Night?
Feature hash: T+P+wwjw
Classification value: Day
Classification answer hash: t+QtqkFp
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.# User input. VIDEO_FILE_PATH is a local copy of the video named in DATA_UNIT. Frame numbers start at 0, as they do in ffmpeg.
# Import dependencies
import os
import subprocess
from typing import cast
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute
from encord.objects.ontology_object_instance import AnswersForFrames
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
DATA_UNIT = "cherries-vid-001.mp4" # Replace with the name of the file (data unit) to export labels for
VIDEO_FILE_PATH = "/Users/chris-encord/cherries-vid-001.mp4" # Replace with the path to a local copy of the video
OUTPUT_FOLDER = "/Users/chris-encord/labeled-frames" # Replace with the folder to save the frame images in
SPECIFIC_FRAMES = [10, 20, 30, 40] # Replace with the frames to export. Frame numbers start at 0
# Create the output folder if it doesn't exist
os.makedirs(OUTPUT_FOLDER, exist_ok=True)
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', '-y', '-i', video_file, '-vf', rf'select=eq(n\,{frame_number})',
'-vframes', '1', output_file
]
subprocess.run(ffmpeg_command, check=True)
# 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)
# Get an attribute's answer on one frame. A static attribute has one answer for the whole object.
# A dynamic attribute can change between frames, so get_answer() returns a list of answers,
# each with the frames it applies to.
def get_answer_on_frame(object_instance: ObjectInstance, attribute: Attribute, frame_number: int):
if attribute.dynamic:
answers_for_frames = cast(AnswersForFrames, object_instance.get_answer(attribute, filter_frame=frame_number))
return answers_for_frames[0].answer if answers_for_frames else None
return object_instance.get_answer(attribute)
# Get a readable value and hash for any answer: an Option for radio buttons, a list of
# Options for checklists, a string for text, a number, or None when there is no answer
def describe_answer(answer):
if isinstance(answer, Option):
return answer.title, answer.feature_node_hash
if isinstance(answer, list):
return [option.title for option in answer], [option.feature_node_hash for option in answer]
return answer, None
# Print an attribute and its answer on one frame
def print_attribute(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
value, answer_hash = describe_answer(get_answer_on_frame(object_instance, attribute, frame_number))
print(f"Attribute name: {attribute.title}")
print(f"Attribute hash: {attribute.feature_node_hash}")
print(f"Attribute answer: {value}")
print(f"Attribute answer hash: {answer_hash}")
# Initialize label rows using bundles
label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
with project.create_bundle() as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
for label_row in label_rows:
for frame_number in SPECIFIC_FRAMES:
# get_frame_view() returns only the labels on one frame.
# Frames after the last frame of the file return no labels.
frame_view = label_row.get_frame_view(frame_number)
object_instances = frame_view.get_object_instances()
# Print essential label information for all objects on this frame
for object_instance in object_instances:
annotation = object_instance.get_annotation(frame_number)
print(f"Frame: {frame_number}")
print(f"objectHash: {object_instance.object_hash}")
print(f"Object name: {object_instance.object_name}")
print(f"featureHash: {object_instance.feature_hash}")
print(f"Object color: {object_instance.ontology_item.color}")
print(f"Ontology shape: {object_instance.ontology_item.shape.value}")
print(f"Label location: {annotation.coordinates}")
# Print all attributes
for attribute in object_instance.ontology_item.attributes:
print_attribute(attribute, object_instance, frame_number)
# Print essential classification information on this frame
for classification_instance in frame_view.get_classification_instances():
value, answer_hash = describe_answer(classification_instance.get_answer())
print(f"Frame: {frame_number}")
print(f"Classification hash: {classification_instance.classification_hash}")
print(f"Classification name: {classification_instance.classification_name}")
print(f"Feature hash: {classification_instance.feature_hash}")
print(f"Classification value: {value}")
print(f"Classification answer hash: {answer_hash}")
# Save the frame as an image if it has at least one object
if object_instances:
output_image_path = os.path.join(OUTPUT_FOLDER, f"frame_{frame_number}.png")
extract_frame_to_image(VIDEO_FILE_PATH, frame_number, output_image_path)
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 image or frame (in pixels).
- The
xcoordinate and the width (w) of a label are multiplied by the pixel width of the image or frame. - The
ycoordinate and the height (h) of a label are multiplied by the pixel height of the image or frame.
Export Labels from Specific Workflow Stages
from encord import EncordUserClient
# User input
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 the unique Project ID
WORKFLOW_STAGE = "Annotation" # Replace with the name of the Workflow stage
# Authenticate
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 project
project = user_client.get_project(PROJECT_ID)
# Fetch label rows in the stage named WORKFLOW_STAGE
label_rows = project.list_label_rows_v2(
workflow_graph_node_title_eq=WORKFLOW_STAGE
)
# Initialise labels
with project.create_bundle() as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Export rows
for label_row in label_rows:
print(label_row.data_title)
print(label_row.to_encord_dict())
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 the unique Project ID
WORKFLOW_STAGE = "Review%" # Replace with a stage name pattern. % matches any characters
# Authenticate
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 project
project = user_client.get_project(PROJECT_ID)
# Fetch rows whose stage name matches WORKFLOW_STAGE (for example Review 1, Review 2)
label_rows = project.list_label_rows_v2(
workflow_graph_node_title_like=WORKFLOW_STAGE
)
# Initialise labels
with project.create_bundle() as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Export rows
for label_row in label_rows:
stage = label_row.workflow_graph_node.title
print(f"{label_row.data_title} is in stage: {stage}")
print(label_row.to_encord_dict())
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 the unique Project ID
# Authenticate
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 project
project = user_client.get_project(PROJECT_ID)
# Fetch all label rows
label_rows = project.list_label_rows_v2()
# Initialise labels
with project.create_bundle() as bundle:
for label_row in label_rows:
label_row.initialise_labels(bundle=bundle)
# Process depending on stage
for label_row in label_rows:
stage = label_row.workflow_graph_node.title if label_row.workflow_graph_node else None
print(f"{label_row.data_title} is in stage: {stage}")
if stage == "Annotation":
print("Processing annotation row")
print(label_row.to_encord_dict())
elif stage == "Review":
print("Processing review row")
print(label_row.to_encord_dict())
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, useinclude_all_label_branches=True.
Make sure you:
- Replace the values under
# User input. - If you only want to export the MAIN branch, remove
include_all_label_branches=True.
All labels all branches
import json
from encord import EncordUserClient
from encord.objects.options import Option
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
OUTPUT_FILE_PATH = "/Users/chris-encord/consensus_labels_output.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# Create user client using access 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)
# Downloads a local copy of all the labels
# Without the include_all_label_branches flag only the MAIN branch labels export.
# For a Data Group, list the parent row: its child labels are on the parent's spaces,
# so include_children is not needed (it is deprecated since SDK v0.1.195).
label_rows = project.list_label_rows_v2(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 and classification instances. A Data Group stores its labels on its
# spaces (one per file), not on the parent label row
object_instances = label_row.get_object_instances()
classification_instances = label_row.get_classification_instances()
for space in label_row.get_spaces():
object_instances.extend(space.get_object_instances())
classification_instances.extend(space.get_classification_instances())
for object_instance in object_instances:
object_data = {
"object_hash": object_instance.object_hash,
"object_name": object_instance.object_name,
"feature_hash": object_instance.feature_hash,
"ontology_item": {
"color": object_instance.ontology_item.color,
"shape": object_instance.ontology_item.shape,
"attributes": [
{"name": attribute.name, "feature_node_hash": attribute.feature_node_hash}
for attribute in object_instance.ontology_item.attributes
],
},
"annotations": [
{"frame": annotation.frame, "coordinates": annotation.coordinates.to_dict()}
for annotation in object_instance.get_annotations()
],
}
label_row_data["objects"].append(object_data)
for classification_instance in classification_instances:
answer = classification_instance.get_answer()
if isinstance(answer, Option): # Radio button
answer_data = {"value": answer.value, "hash": answer.feature_node_hash}
elif answer is None or isinstance(answer, str): # Text (or unanswered)
answer_data = {"value": answer, "hash": None}
else: # Checklist: list of selected options
answer_data = [{"value": option.value, "hash": option.feature_node_hash} for option in answer]
classification_data = {
"classification_hash": classification_instance.classification_hash,
"classification_name": classification_instance.classification_name,
"feature_hash": classification_instance.feature_hash,
"classification_answer": answer_data,
"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
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
For Data Groups, all child labels are exported through the Data Group parent. Calllist_label_rows_v2() (without include_children) and export the parent rows. Each child’s labels are in the spaces key of the parent’s exported dictionary. The Export Labels as JSON script does this:
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 access 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()
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}.")
LabelRowV2.get_spaces() and call get_object_instances() and get_classification_instances() on each space, as the attribute and Consensus scripts do.
- Adding
include_all_label_branches=Truetolist_label_rows_v2()includes all labels from all branches in Consensus Projects.
Deprecated (SDK v0.1.195): For Data Groups, passing
include_children=True to list_label_rows_v2() to fetch child labels is deprecated. Work on the Data Group parent instead and access each child through its Label Space with LabelRowV2.get_spaces().Deprecated: export Data Group labels with include_children=True
Deprecated: export Data Group labels with include_children=True
This script is kept for reference only. Use the script above instead.
DEPRECATED: 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 access 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
# DEPRECATED (SDK v0.1.195): include_children=True is deprecated. Prefer the
# parent-based export (list_label_rows_v2() without include_children), which
# returns each Data Group child's labels on the parent row.
label_rows = project.list_label_rows_v2(include_children=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 Bitmasks
The following code example illustrates how to download / export and save Bitmask labels:import cv2
import numpy as np
from encord import EncordUserClient
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your 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)
# Obtain labels for the media of interest
label_row = project.list_label_rows_v2()[0]
label_row.initialise_labels()
# Find annotation
# In this example, it is just a first object on a first frame
object_with_bitmask_annotation = label_row.get_frame_views()[
0
].get_object_instances()[0]
# Get a bitmask annotation
# In this example, it is a first annotation on the object
bitmask_annotation = object_with_bitmask_annotation.get_annotations()[0]
# Convert bitmask to a numpy array
# Obtained array is a binary mask, so to work with it as an image,
# it is necessary to convert it to a different datatype and scale
bitmask = bitmask_annotation.coordinates.to_numpy_array().astype(np.uint8)
bitmask[bitmask == 1] = 255
# And now we can save the mask as a grayscale image
cv2.imwrite("./mask_as_an_image.png", bitmask)
Decode Bitmask Labels
Bitmask labels exported from Encord as JSON or COCO are encoded as anrleString. This rleString can be converted to an image or a binary array.
Use the COCO API to decode Bitmasks when using the COCO export format.
Create Bitmask Image
Create Bitmask Image
# Import dependencies
import json
from pathlib import Path
import numpy as np
from encord.objects.coordinates import BitmaskCoordinates
from PIL import Image
# Read the JSON file.
# Replace labels.json with the path to the JSON file containing your Bitmask
labels = json.loads(Path("labels.json").read_text())
output_folder = Path("output")
output_folder.mkdir(parents=True, exist_ok=True)
# Finds the rleString and saves it to a .png image
for label_row in labels:
for du in label_row["data_units"].values():
frame_labels = du["labels"]
# Videos, image sequences, and DICOM are keyed by frame or slice number.
# A single image stores its objects directly, so treat it as frame 0.
if "objects" in frame_labels:
frame_labels = {"0": frame_labels}
for slice_num, slice_labels in frame_labels.items():
for obj in slice_labels["objects"]:
# Skip objects that are not Bitmasks, such as bounding boxes or polygons
if obj.get("shape") != "bitmask":
continue
bmc = BitmaskCoordinates.from_dict(obj)
nparr = np.array(bmc)
img = Image.fromarray(nparr)
# img.show()
# Object hashes can contain "/", which is not allowed in file names
safe_hash = obj["objectHash"].replace("/", "_")
img.save(output_folder / f"mask_{int(slice_num):05d}_{safe_hash}.png")
print("Decoding complete.")
from pycocotools.coco import COCO
import numpy as np
from pycocotools import mask as maskUtils
from PIL import Image
import json
# Read the COCO file. Replace 'labels.json' with the path to your COCO format annotations file
coco_annotations_path = 'labels.json'
coco = COCO(coco_annotations_path)
# Get all annotation IDs (you might want to filter or select specific ones)
annIds = coco.getAnnIds()
anns = coco.loadAnns(annIds)
# Decode each rleString and save as a .png image
for ann in anns:
if 'segmentation' in ann and isinstance(ann['segmentation'], dict):
rle = ann['segmentation']
mask = maskUtils.decode(rle)
img = Image.fromarray(mask * 255).convert('L') # Convert to grayscale
# Save one file per annotation, named after the annotation ID
img.save(f"mask_{ann['id']}.png")
print("Decoding complete.")
Create Binary Array
Create Binary Array
The
rleStringcan be converted into an array of 1’s and 0’s using the script below.import json
from pathlib import Path
from encord.objects.coordinates import BitmaskCoordinates
# Read the JSON file. Replace labels.json with the path to the JSON file containing your Bitmask
labels = json.loads(Path("labels.json").read_text())
for label_row in labels:
for du in label_row["data_units"].values():
frame_labels = du["labels"]
# A single image stores its objects directly, so treat it as frame 0
if "objects" in frame_labels:
frame_labels = {"0": frame_labels}
for frame_data in frame_labels.values():
for obj in frame_data["objects"]:
if obj.get("shape") != "bitmask":
continue
# Create a numpy array
np_mask = BitmaskCoordinates.from_dict(obj).to_numpy_array()
print(np_mask.astype(int))
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.
to_encord_dict(). Replace the values under # User input.
# Import dependencies
import json
from encord import EncordUserClient
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
OUTPUT_FILE_PATH = "/Users/chris-encord/bulk-export.json" # Replace with the path of the output JSON file
BUNDLE_SIZE = 100 # Optional: number of operations per bundle (keep it under 1000)
# 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",
)
# Gets Project to export labels
project = user_client.get_project(PROJECT_ID)
label_rows = project.list_label_rows_v2()
# 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)
# Export every label row. Exporting only reads labels, so there is nothing to save.
exported_labels = [label_row.to_encord_dict() for label_row in label_rows]
with open(OUTPUT_FILE_PATH, "w") as file:
json.dump(exported_labels, file, indent=4)
print(f"Exported {len(exported_labels)} label rows to {OUTPUT_FILE_PATH}")
Export Classifications Only
When you only need the classification answers for a Project,get_label_classifications() provides a fast bulk path that fetches classification answers directly, without initializing each full label row. Object annotations, frames, and coordinates are not returned.
This script DOES NOT use the bundle function shown above. Requests are batched server-side using the
batch_size argument (max 1000 labels per request), so the batching benefit is already built into the method.Export classifications (bulk) to JSON
# Import dependencies
import json
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
BRANCH_NAME = "main" # Replace with the label branch to read from
BATCH_SIZE = 500 # Number of labels per server request (max 1000). Customize as needed
OUTPUT_JSON = "/Users/chris-encord/export-classifications.json" # Replace with file path to save JSON output file
# Create user client using access 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()
assert label_rows, f"No label rows found in project {PROJECT_ID}"
# Collect the label row UUIDs (label_hash) to fetch classifications for
label_uuids = [row.label_hash for row in label_rows if row.label_hash is not None]
assert label_uuids, f"No created label rows found in project {PROJECT_ID}"
# Fast bulk fetch of classification answers only.
# Requests are batched automatically, so no bundle is required here.
all_classifications = [
entry.to_dict()
for entry in project.get_label_classifications(
label_uuids,
branch_name=BRANCH_NAME,
batch_size=BATCH_SIZE,
)
]
assert all_classifications, "No classification data collected for export"
# Save the collected classifications 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_classifications, file, indent=4)
print(f"Classifications for {len(all_classifications)} label rows have been saved to {output_file}.")
COCO Format Export
Use the following script to bulk export labels in the COCO format.export_coco_labels() needs the SDK’s coco extra. Install it with pip install "encord[coco]".# User input. export_coco_labels() takes these optional arguments:
label_hashes: the label rows to export. Leave out to export every label row.branch_name: the label branch to export. Defaults to themainbranch.include_object_feature_hashesandinclude_classification_feature_hashes: only export the objects or classifications with these feature hashes.
COCO Export
import json
from encord import EncordUserClient
# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of your Project
BRANCH_NAME = "main" # Replace with the label branch to export
OUTPUT_FILE_PATH = "/Users/chris-encord/coco_labels.json" # Replace with the path of the output JSON 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",
)
project = user_client.get_project(PROJECT_ID)
# Optional: export only some label rows. This example exports every row with labels.
label_hashes = [label_row.label_hash for label_row in project.list_label_rows_v2() if label_row.label_hash is not None]
coco_labels = project.export_coco_labels(label_hashes=label_hashes, branch_name=BRANCH_NAME)
# Save the coco_labels dictionary to a .json file
with open(OUTPUT_FILE_PATH, "w") as json_file:
json.dump(coco_labels, json_file)