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 OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Bounding 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
In RotatableBoundingBoxCoordinates, top_left_x, top_left_y, width, and height describe the box before it is rotated, and theta is the rotation angle in degrees. The box is rotated around its center.Rotatable Bounding Box OntologyRotatable Bounding Box OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Rotatable 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 OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Polygons Ontology
This example passes a single list of points to PolygonCoordinates (the older values format), which only supports simple polygons. For new code, use PolygonCoordinates(polygons=...) as shown in the Polygons (Advanced) section.
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 OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Polyline 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 OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Keypoint 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 OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Bitmask 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 examples use an Object Primitive (skeleton) template named Triangle, with vertices named point_0, point_1, and point_2. SkeletonTemplate.create_instance matches each coordinate to the template vertex with the same name, so replace the vertex names in the code with the names in your template.Primitive OntologyThe same Ontology as text. The Basic examples use only the object. The Advanced examples also use the attributes and options:
Primitives Ontology

​
Classifications

The following example assumes the Ontology includes a text classification field named Mood. In this example, the text classification for the data unit DATA_UNIT is set to Melancholy on the first frame.
  • Replace SSH_PATH with the file path to your SSH private key.
  • Replace PROJECT_ID with the unique ID of your Project.
  • Replace DATA_UNIT with the name of the data unit (file) to label.
  • Replace the Classification names and answers to suit your needs.
Text Classification
Example 1:Adds a Text classification to a specific data unit. Replace DATA_UNIT 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. Replace DATA_UNIT with the name of the data unit you want to add the label to, and PROJECT_ID with the unique ID of the Project.
Example 1:Adds a Number input to a specific data unit. Replace DATA_UNIT 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. Replace DATA_UNIT with the name of the data unit you want to add the label 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 (160 to 165) 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 SSH_PATH with the file path to your SSH private key.
  • Replace PROJECT_ID with the unique ID of your Project.
  • Replace DATA_UNIT with the name of the data unit (file) that has the Whale object labels.
  • 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.
Dynamic Attributes

​
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:
  • SSH_PATH with the full path to your private key.
  • PROJECT_ID with the unique ID of your Project.
  • pass # Replace with your label row operations 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.