Import Labels/Annotations

Once you have imported your local data or cloud data into Encord, you can import your labels/annotations for the data.

You MUST call the initialise_labels function (once per data unit) before trying to import your labels/annotations.

The process to import labels into Encord consists of the following:

Import the dependencies.
Authenticate your Encord client.
Specify the Annotate Project with the data you want to label.
Specify the label row you want to import your label to. This specifies the data unit (image, image group, image sequence, video, or DICOM series) you want to add your labels to.
Use the initialise_labels function ONCE to prepare the row for your labels.
Apply your labels to the label row.
Save the label row.

One label row is equivalent to one data unit. You only need to use the initialise_labels function and save the label row ONCE per data unit, regardless of how many labels are added to the data unit. However, any future changes to a data unit need to be initialized and saved.

READ THIS FIRST

All the examples demonstrating the use of each label and classification type utilize the following Project and Ontology:

Entity	Name
Project	Blueberries and Cherries PROJECT_HASH: 7d4ead9c-4087-4832-a301-eb2545e7d43b
Ontology	Blueberries and Cherries Ontology
Bounding box	Cherry
Rotatable bounding box	Other type of fruit
Polygon	Persimmon
Polyline	Branch
Keypoint	Pedicel
Bitmask	Blueberry
Object Primitive (Triangle)	Strawberry
Radio classification	Blueberry or cherry?
Checklist classification	Many types of fruit?

Object Labels

Example 1

Imports a single bounding box (Cherry) to a single image (cherry_001.png).

Example 2:

Imports three instances (tracking an object across three sequential frames: 103, 104, and 105) of a bounding box (Cherry) to a video (Cherries_video.mp4).

Example 3

Imports three bounding boxes (Cherry) to a single image (cherry_001.png).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 103, 104, 105, object 2 - frames 206, 207, 208, and object 3 - frames 313, 315, 317) of three bounding boxes (Cherry) to a video (Cherries_video.mp4).

# 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 = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating one bounding box - START
label_row = project.list_label_rows_v2(
    data_title_eq="<name-of-data-unit>"
)[0]

label_row.initialise_labels()

# Find a bounding box annotation object in the project ontology
box_ontology_object: Object = project.ontology_structure.get_child_by_title(
        title="<name-of-object-bounding-box>", type_=Object
    )

# Instantiate an object instance from the box ontology node
box_object_instance: ObjectInstance = box_ontology_object.create_instance()

box_object_instance.set_for_frames(
    coordinates=BoundingBoxCoordinates(
        height=<numerical-value>,
        width=<numerical-value>,
        top_left_x=<numerical-value>,
        top_left_y=<numerical-value>,
    ),
    # Add the bounding box to the frames specified
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
 )

# Link the object instance to the label row.
label_row.add_object_instance(box_object_instance)

# Upload the label to the server
label_row.save()

Example 1

Imports a single rotatable bounding box (Other type of fruit) to a single image (apple_001.png).

Example 2

Imports three instances (tracking an object across three sequential frames: 120, 121, and 122) of a bounding box (Other type of fruit) to a video (Cherries_video.mp4).

Example 3

Imports three rotatable bounding boxes (Other type of fruit) to a single image (apple_001.png).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 120, 121, 122, object 2 - frames 222, 224, 226, and object 3 - frames 321, 323, 325) of three rotatable bounding boxes (Other type of fruit) to a video (Cherries_video.mp4).

# Import dependencies
from pathlib import Path

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

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating one rotatable bounding box - START
label_row = project.list_label_rows_v2(
    data_title_eq="<data-unit-title>"
)[0]

label_row.initialise_labels()

# Find a rotatable bounding box annotation object in the project ontology
rbb_ontology_object: Object = project.ontology_structure.get_child_by_title((
        title="<rotatable-bounding-box-class-title>", type_=Object
    )

# Instantiate an object instance from the rotatable bounding box ontology node
rbb_object_instance: ObjectInstance = rbb_ontology_object.create_instance()

rbb_object_instance.set_for_frames(
    coordinates=RotatableBoundingBoxCoordinates(
        height=<height-value>
        width=<width-value>,
        top_left_x=<top-left-x-value>,
        top_left_y=<top-left-y-value>,
        theta=<angle-of-rotation>
    ),
    # Add the rotatable bounding box to frame number specified
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

# Link the object instance to the label row.
label_row.add_object_instance(rbb_object_instance)

# Upload the label to the server
label_row.save()

Polygons can have simple and complex shapes, including being enclosed in one another, and encompassing separate regions. In each case the polygon’s coordinates are arranged in a different way.

Specifying coordinates for polygons uses this format:

PolygonCoordinates(polygons=[[[PointCoordinate(x1, y1), PointCoordinate(x2, y2),...]]]

Simple Polygon

Import a simple polygon using the recommended method.

Donut

Import a complex polygon with a hole in it.

Multiple Polygons

Import a complex polygon that is in multiple parts.

Donut with Object Inside

Imports a complex polygon that has a hole in it with another polygon inside.

# Import dependencies
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import (
    Object,
    ObjectInstance,
)
from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_ID = "0bdc0bdf-638a-4256-ad97-750353ddbd0c"

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Define coordinates for each image (outer ring and inner ring for donut shape)
image_annotations = {
    "cherry-002-dup-001.jpg": [
        # Simple Polygon
        [
            [PointCoordinate(1.000, 0.500), PointCoordinate(0.750, 0.933), 
             PointCoordinate(0.250, 0.933), PointCoordinate(0.000, 0.500), 
             PointCoordinate(0.250, 0.067), PointCoordinate(0.750, 0.067)],
        ],
    ],
    
    "cherry-002-dup-002.jpg": [
        # Simple Polygon
        [
            [PointCoordinate(0.900, 0.400), PointCoordinate(0.700, 0.850), 
             PointCoordinate(0.300, 0.850), PointCoordinate(0.100, 0.400), 
             PointCoordinate(0.300, 0.100), PointCoordinate(0.700, 0.100)],
        ],
    ],

    # Add more images and their coordinates here
}

# Get project for which predictions are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Iterate over each image and apply predefined coordinates
for image_name, polygons in image_annotations.items():
    label_rows = project.list_label_rows_v2(data_title_eq=image_name)

    if not label_rows:
        print(f"Skipping {image_name}: No label row found.")
        continue

    label_row = label_rows[0]
    label_row.initialise_labels()

    # Find a polygon annotation object in the project ontology
    # Replace 'Complex Polygons' with name of your Polygon object in your Ontology
    polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
        title="Complex Polygons", type_=Object
    )

    # Instantiate an object instance from the polygon ontology node
    polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()

    # Set predefined coordinates
    polygon_object_instance.set_for_frames(
        coordinates=PolygonCoordinates(polygons=polygons),
        frames=0,
        manual_annotation=True,
        confidence=1.0,
    )

    # Link the object instance to the label row
    label_row.add_object_instance(polygon_object_instance)

    # Upload the label to the server
    label_row.save()
    print(f"Annotated {image_name}")

print("Annotation process completed.")

While this method works for simple polygons, we STRONGLY recommend using the new Polygon method for creating simple polygons.

Example 1

Imports a single polygon (Persimmon) to a single image (persimmon_001.jpg).

Example 2

Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a polygon (Persimmon) to a video (Cherries_video.mp4).

Example 3

Imports three polygons (Persimmon) to a single image (persimmon_001.jpg).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 153, 154, 155, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three polygons (Persimmon) to a video (Cherries_video.mp4).

# Import dependencies
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

# Configuration
SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"
DATA_UNIT_TITLE = "<name-of-data-unit>"  # The title of the data unit (image or video)
ONTOLOGY_OBJECT_TITLE = "<object-name>"  # The ontology object title for the polygon

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating one bounding box - START
label_row = project.list_label_rows_v2(
    data_title_eq=DATA_UNIT_TITLE
)[0]


# Initialize labels for each selected label row
label_row.initialise_labels()

# Find a polygon annotation object in the project ontology
polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
    title=ONTOLOGY_OBJECT_TITLE, type_=Object
)

# Instantiate an object instance from the polygon ontology node
polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()

# Define the polygon coordinates
polygon_coordinates = PolygonCoordinates([
    PointCoordinate(0.x1, 0.y1),
    PointCoordinate(0.x2, 0.y2),
    PointCoordinate(0.x3, 0.y3),
    PointCoordinate(0.x4, 0.y4)
])

# Set the polygon label for the specified frame
polygon_object_instance.set_for_frames(
    coordinates=polygon_coordinates,
    frames=0,  # Specify the frame number
    manual_annotation=False,  # Mark as a label
    confidence=1.0  # Optional confidence score
)

# Link the object instance to the label row
label_row.add_object_instance(polygon_object_instance)

# Save the label row 
label_row.save()

Example 1

Imports a single polyline (Branch) to a single image (persimmon_001.jpg).

Example 2

Imports three instances (tracking an object across three sequential frames: 146, 147, and 148) of a polygon (Branch) to a video (Cherries_video.mp4).

Example 3

Imports three polylines (Branch) to a single image (persimmon_001.jpg).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 246, 247, 248, object 2 - frames 346, 347, 348, and object 3 - frames 446, 447, 448) of three polylines (Branch) to a video (Cherries_video.mp4).

# Import dependencies
from pathlib import Path

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

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Specify the data unit to label
label_row = project.list_label_rows_v2(
    data_title_eq="<name-of-data-unit>"
)[0]

label_row.initialise_labels()

# Find a polyline annotation object in the project ontology
polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
        title="<object-name>", type_=Object
    )

# Instantiate an object instance from the polyline ontology node
polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

# The x,y coordinates of each polyline vertex are specified as follows
polyline_object_instance.set_for_frames(
    coordinates=PolylineCoordinates(
        [PointCoordinate(.x1,.y1), PointCoordinate(.x2,.y2), PointCoordinate(.x3,.y3), PointCoordinate(.13,.456)]
    ),
    # Add the polyline to the specified frame number
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

# Link the object instance to the label row.
label_row.add_object_instance(polyline_object_instance)

# Upload the label to the server
label_row.save()

Keypoint

Example 1

Imports a single keypoint (Pedicel) to a single image (blueberry_003.png).

Example 2

Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a keypoint (Pedicel) to a video (Blueberries_video.mp4).

Example 3

Imports three keypoints (Pedicel) to a single image (blueberry_003.png).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 143, 144, 145, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three keypoints (Pedicel) to a video (Blueberries_video.mp4).

# Import dependencies
from pathlib import Path

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

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Specify the data unit to label
label_row = project.list_label_rows_v2(
    data_title_eq="<name-of-data-unit>"
)[0]

label_row.initialise_labels()

# Creating one Keypoint - START
# Find a keypoint annotation object in the project ontology
keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
        title="<object-name>", type_=Object
    )

# Instantiate an object instance from the keypoint ontology node
keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

# The x,y coordinates of the keypoint are specified as follows
keypoint_object_instance.set_for_frames(
    coordinates=PointCoordinate(
        x=<value-for-x-axis>
        y=<value-for-y-axis>
    ),
    # Add the keypoint to the specified frame number
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

# Link the object instance to the label row.
label_row.add_object_instance(keypoint_object_instance)

# Upload the label to the server
label_row.save()

Example 1:

Imports a single bitmask (Blueberry) to a single image (blueberry_003.jpg). For simplicity, the bitmask covers the entire image (image dimensions: 1254x836).

Example 2:

Imports three instances (tracking an object across three sequential frames: 156, 157, and 159) of a bitmask (Blueberry) to a video (Blueberries_video.mp4). For simplicity, the bitmask covers the entire frame (video dimensions: 1920x1080).

Example 3:

Imports three bitmasks (Blueberry) to a single image (blueberry_003.jpg). For simplicity, the bitmasks cover the entire image (image dimensions: 1254x836).

Example 4:

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 156, 157, 158, object 2 - frames 256, 258, 259, and object 3 - frames 355, 357, 359) of three bitmasks (Blueberry) to a video (Blueberries_video.mp4). For simplicity, the bitmasks cover the entire frame (video dimensions: 1920x1080).

# Import dependencies
import numpy as np

from pathlib import Path

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

# Firstly, we need to prepare the mask itself.
# For simplicity, we can just mask the whole image
# Note, that the size of the mask must be identical to the size of the image
numpy_coordinates = np.ones((<y-axis-value>, <x-axis-value>))

# we also need to make sure that the image is in boolean format
numpy_coordinates = numpy_coordinates.astype(bool)


SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating one bitmask - START
label_row = project.list_label_rows_v2(
    data_title_eq="<data-unit-name>"
)[0]

label_row.initialise_labels()

# Find a bitmask annotation object in the project ontology
bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
    title="<bitmask-object-name>", type_=Object
)

# Instantiate an object instance from the bitmask ontology node
bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

# The coordinates the bitmask are specified as follows

bitmask_object_instance.set_for_frames(
    # Create coordinates from provided numpy bitmask
    coordinates=BitmaskCoordinates(numpy_coordinates),
    # Add the bitmask to the first frame
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

# And assign the object instance to the label row
label_row.add_object_instance(bitmask_object_instance)

label_row.save()

Before you can import Object Primitive labels into Encord, the Object Primitive Template MUST exist in Encord. Use the UI to create the Object Primitive Template so you can visually inspect the Object Primitive.

Import Object Primitive labels

Example 1

Imports a single object primitive (Ontology object = Strawberry Object Primitive name = Triangle) to a single image (strawberries_10.jpg).

Example 2

Imports three instances (tracking an object across three sequential frames: 163, 164, and 165) of a object primitive (Ontology object = Strawberry Object Primitive name = Triangle) to a video (Cherries_video.mp4).

Example 3

Imports three object primitives (Ontology object = Strawberry Object Primitive name = Triangle) to a single image (strawberries_10.jpg).

Example 4

Imports three instances (tracking 3 different objects across three frames: object 1 - frames 173, 174, 175, object 2 - frames 183, 184, 185, and object 3 - frames 193, 194, 195) of three object primitives (Ontology object = Strawberry Object Primitive name = Triangle) to a video (Cherries_video.mp4).

# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import (
    Object,
    ObjectInstance,
    OntologyStructure,
)
from encord.objects.coordinates import SkeletonCoordinate, SkeletonCoordinates
from encord.objects.skeleton_template import SkeletonTemplate

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Specify the data unit to label
label_row = project.list_label_rows_v2(
    data_title_eq="<name-of-data-unit>"
)[0]

label_row.initialise_labels()


# Creating one skeleton - START
# Find a skeleton annotation object in the project ontology
skeleton_ontology_object: Object = project.ontology_structure.get_child_by_title(
        title="<name-of-object-in-ontology>", type_=Object
    )
skeleton_template: SkeletonTemplate = project.ontology_structure.skeleton_templates['<name-of-object-primative>']

# Instantiate an object instance from the polygon ontology node
skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
    SkeletonCoordinate(
        x=x0, y=y0, 
        name='point_0', 
        color='#000000', 
        value="point_0", 
        feature_hash=skeleton_hashes[0]
        ), 
    SkeletonCoordinate(
        x=x1, y=y1, 
        name='point_1', 
        color='#000000', 
        value="point_1", 
        feature_hash=skeleton_hashes[1]
        ), 
    SkeletonCoordinate(
        x=x2, y=y2, 
        name='point_2', 
        color='#000000', 
        value="point_2", 
        feature_hash=skeleton_hashes[2]
        )
        ], 
    name="<name-of-object-primitive>")
print(skeleton_coordinates)
# The x,y coordinates of each polygon vertex are specified as follows
skeleton_object_instance.set_for_frames(
    coordinates=skeleton_coordinates,
    # Add the polygon to the image
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

# Link the object instance to the label row.
label_row.add_object_instance(skeleton_object_instance)

# Upload the label to the server
label_row.save()

Classifications

Example 1:

Imports a radio button classification (Blueberry or Cherry?) to a single image (blueberry_003.jpg).

Example 2:

Imports a radio button classification (Blueberry or Cherry?) across a range of sequential frames: 193 to 197) to a video (Blueberries_video.mp4).

#Import dependencies
from __future__ import annotations
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import (
    Classification,
)
from collections import defaultdict
from copy import deepcopy
from dataclasses import dataclass, field
from datetime import datetime
from typing import (
    TYPE_CHECKING,
    Any,
    Dict,
    Iterable,
    List,
    Optional,
    Sequence,
    Set,
    Tuple,
    Union,
)
from dateutil.parser import parse
from encord.constants.enums import DataType
from encord.exceptions import LabelRowError
from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
from encord.objects.answers import (
    Answer,
    _get_static_answer_map,
    get_default_answer_from_attribute,
)

from encord.objects.frames import (
    Frames,
    Ranges,
)
from encord.objects.internal_helpers import (
    _infer_attribute_from_answer,
    _search_child_attributes,
)
from encord.objects.ontology_object import Object
from encord.objects.options import Option
from encord.objects.utils import check_email, short_uuid_str

if TYPE_CHECKING:
    from encord.objects.ontology_labels_impl import LabelRowV2


SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating classification- START
# Specify the data unit to apply classification
label_row = project.list_label_rows_v2(
    data_title_eq="<data-unit-name>"
)[0]

label_row.initialise_labels()


# Assume that the following radio classification exists in the ontology.

radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
    title="<classification-name>",
    type_=Classification,
)

blueberry_option = radio_ontology_classification.get_child_by_title(
    title="<radio-button-option-title>", type_=Option
)

radio_classification_instance = (
   radio_ ontology_classification.create_instance()
)

radio_classification_instance.set_answer(
    answer=<radio-button-option>
)
radio_classification_instance.set_for_frames(
    # Add the classification to the image
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

label_row.add_classification_instance(radio_classification_instance)


label_row.save()

Example 1:

Imports a checklist classification (Many types of fruit?) to a single image (apple_003.jpg). The selected items from the list are apple and kiwi.

Example 2:

Imports a checklist classification (Many types of fruit?) across a range of sequential frames: 193 to 197) to a video (Blueberries_video.mp4). The selected items from the list are apple and kiwi.

#Import dependencies
from __future__ import annotations
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import (
    Classification,
)
from collections import defaultdict
from copy import deepcopy
from dataclasses import dataclass, field
from datetime import datetime
from typing import (
    TYPE_CHECKING,
    Any,
    Dict,
    Iterable,
    List,
    Optional,
    Sequence,
    Set,
    Tuple,
    Union,
)
from dateutil.parser import parse
from encord.constants.enums import DataType
from encord.exceptions import LabelRowError
from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
from encord.objects.answers import (
    Answer,
    _get_static_answer_map,
    get_default_answer_from_attribute,
)

from encord.objects.frames import (
    Frames,
    Ranges,
)
from encord.objects.internal_helpers import (
    _infer_attribute_from_answer,
    _search_child_attributes,
)
from encord.objects.ontology_object import Object
from encord.objects.options import Option
from encord.objects.utils import check_email, short_uuid_str

if TYPE_CHECKING:
    from encord.objects.ontology_labels_impl import LabelRowV2


SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added.
project: Project = user_client.get_project(PROJECT_ID)


# Creating one polyline- START
label_row = project.list_label_rows_v2(
    data_title_eq="Blueberries_video.mp4"
)[0]

label_row.initialise_labels()


# Assume that the following radio classification exists in the ontology.

checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
    title="Many types of fruit?",
    type_=Classification,
)

apple_option = checklist_ontology_classification.get_child_by_title(
    title="Apple", type_=Option
)

kiwi_option = checklist_ontology_classification.get_child_by_title(
    title="Kiwi", type_=Option
)
checklist_classification_instance = (
    checklist_ontology_classification.create_instance()
)

checklist_classification_instance.set_answer(
    [apple_option, kiwi_option]
)
checklist_classification_instance.set_for_frames(
    # Add the classification to the image
    frames=177,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

label_row.add_classification_instance(checklist_classification_instance)


label_row.save()

Import Labels in Bulk

When importing a large number of labels, here are some tips to improve your label import performance:

A data unit is one image, one image group, one image sequence, one video, or one DICOM series. One data unit is equivalent to one label row. You only need to call the initialise_labels function and save the label row ONCE per data unit. It does not matter how many labels are added to the data unit between the initialise_labels function and saving the label row.
Use the bundle function to significantly improve the import performance when you do any of the following:
- Import labels on a large number of individual images (NOT image groups, image sequences, videos, or DICOM sets).
- Import labels on a large number of data units at once.

In the following code, ensure you replace:

<private_key_path> with the full path to your private key.
<project-id> with the unique ID of your Project.
#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_HASH = "<project-unique-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_HASH)

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_save) 

Get Started

General

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

Import Labels/Annotations

READ THIS FIRST

Object Labels

Keypoint

Classifications

Import Labels in Bulk

Get Started

General

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

​READ THIS FIRST

​Object Labels

​Classifications

​Import Labels in Bulk

READ THIS FIRST

Object Labels

Classifications

Import Labels in Bulk