Skip to main content
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 you can import your labels/annotations.
The process to import labels into Encord consists of the following:
  1. Import the dependencies.
  2. Authenticate your Encord client.
  3. Specify the Annotate Project with the data you want to label.
  4. 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.
  5. Use the initialise_labels function ONCE to prepare the row for your labels.
  6. Apply your labels to the label row.
  7. 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.

​
Object Labels

BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Bounding Box OntologyBounding Box Ontology
BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Rotatable Bounding Box OntologyRotatable Bounding Box Ontology
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.BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Polygon CoordinatesSpecifying coordinates for polygons uses this format:
Simple PolygonImport a simple polygon using the recommended method.
DonutImport a complex polygon with a hole in it.
Multiple PolygonsImport a complex polygon that is in multiple parts.
Donut with Object InsideImports a complex polygon that has a hole in it with another polygon inside.
Polygons OntologyThis ontology applies for all polygon shapes (simple, donut, multiple polygons, donut with object inside).Polygons Ontology
While this method works for simple polygons, we STRONGLY recommend using the new Polygon method for creating simple polygons.This example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Polyline OntologyPolyline Ontology
BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Keypoint OntologyKeypoint Ontology
Use CircleCoordinates(center_x=0.XX, center_y=0.YY, radius=0.XX) to specify the location and size of the Circle object label you want to import.
BasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Bitmask OntologyBitmask Ontology
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 labelsBasicThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
AdvancedThis example includes the following:
  • Single image labeling
  • Image Group labeling
  • Image Sequence labeling
  • Video labeling
  • Radio button options
  • Checklist options
  • Text input
  • Number input
Primitives OntologyThe title for the primitive object is Triangle.Primitive Ontology

​
Classifications

The following example assumes the Ontology includes a text classification field named Mood. In this example, the text classification for the first label row (data unit) in the Project is set to Melancholy on the first frame.
  • Replace <private_key_path> with the key to your private key for authentication.
  • Replace <project_hash> with the hash of your Project.
  • Replace the Classification names and answers to suit your needs.
Example 1:Adds a Text classification to a specific data unit. Ensure you replace <data-unit-name> with the name of the data unit you want to add the classification to.Example 2:Adds a Text attribute to an arbitrary bounding box on a specific data unit. Ensure you replace <data-unit-name> with the name of the data unit you want to add the classification to, and <project_id> with the unique ID of the Project.
Example 1:Adds a Number input to a specific data unit. Ensure you replace <data-unit-name> with the name of the data unit you want to add the classification to.Example 2:Adds a Number attribute to an arbitrary bounding box on a specific data unit. Ensure you replace <data-unit-name> with the name of the data unit you want to add the classification to, and <project_id> with the unique ID of the Project.
Example 1:Imports a Radio button options (Blueberry or Cherry?) to a single image (blueberry_003.jpg).Example 2:Imports a Radio button options (Blueberry or Cherry?) across a range of sequential frames (193 to 197) to a video (Blueberries_video.mp4).
Example 1:Imports a Checklist options (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 options (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.

​
Attributes

The following scripts assume that an object label called Whale has already been created. Each script retrieves the object instance and searches for the corresponding attribute within the Project’s Ontology. For radio buttons and checklists, the scripts also identify the relevant attribute options.
  • Replace <private_key_path> with the key to your private key for authentication.
  • Replace <project_hash> with the hash of your Project.
  • Replace Whale with the name of your object.
  • Replace the attributes and attribute answers to suit your needs.

​
Nested Attributes

Radio button attributes can be nested. The following script assumes that an object label called Whale has already been created.
Nested Radio Attributes

​
Relation Attributes

Relation attributes use text attributes as pointers to show a relationship between labels. When an attribute is marked as Relation the string #relation is appended to the attribute name. You can specify relationships between any object labels in a data unit, if a Relation attribute is added to one object label type with Relation.
Learn more about relation attributes in Encord here.
The following example uses bounding box and polygon object labels with a Text-Relation attribute and a Text attribute. The Text attribute can be used to provide more context for the relationship between object labels.
Relation Attributes

​
Dynamic Attributes

Dynamic attributes are attributes for object instances where the answer can change in each frame. You can read more about them here. The following example adds bounding boxes for the label Person to three frames. It then sets the dynamic attribute Position to Walking and Standing. Wherever you can set frames, you can either set a single integer, a Range, or a list of Ranges.

​
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.