COCO Labels/Annotations

Encord’s SDK supports importing labels/annotations for your data in the COCO format. You can also import your COCO labels/annotations as predictions on your Projects.

This guide assumes your files were already imported into Encord and a Project containing the data has been created.

Save import.py, replacing the following variables:
- SSH_PATH with the full path to your private key.
- PROJECT_ID with the unique ID of the Project containing the data units you want to import labels for.
- COCOimportfile.json with the full path of the COCO file containing the labels you want to import.
If necessary, modify the matching logic that maps COCO image IDs to Encord frame indices. This is particularly important in cases where filenames in the COCO file do not directly match those in the Encord Project or when multiple files have the same name.

The following import.py script is configured to import labels into single images with unique names and assumes that the category names in the COCO file match the names of your Ontology objects. It matches each COCO image’s file_name to the title of a data unit in the Project. COCO files exported from Encord also include image_title or video_title fields, and the script uses those when they are present. In practice, you must implement your own matching logic. An example where filenames in the COCO file do not directly match those in the Encord Project is provided below.

import json
from pathlib import Path
from encord.utilities.coco.datastructure import FrameIndex
from encord import EncordUserClient
from encord.exceptions import OntologyError
from encord.objects import Object

# 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 unique Project ID

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use domain="https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get the Project
project = user_client.get_project(PROJECT_ID)

# Load the COCO annotations JSON file
# Replace 'COCOimportfile.json' with the full path to your COCO file
coco_file = Path('COCOimportfile.json')
labels_dict = json.loads(coco_file.read_text())

# Build a mapping from COCO category IDs to the feature hashes in your Encord Ontology. 
category_id_to_feature_hash = {}
ont_struct = project.ontology_structure
for coco_category in labels_dict['categories']:
    try:
        ont_obj = ont_struct.get_child_by_title(title=coco_category['name'], type_=Object)
        category_id_to_feature_hash[coco_category['id']] = ont_obj.feature_node_hash
    except OntologyError:
        print(f'Could not match {coco_category["name"]} in the Ontology. Import will crash if these are present.')

# Build a mapping from COCO image IDs to Encord frame indices
# This is only applicable for images, image groups, image sequences, and DICOM series
image_id_to_frame_index = {}
data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2()}
for img in labels_dict['images']:
    if "video_title" in img:
        # COCO file exported from Encord: a video frame, saved as videos/<data_hash>/<frame>.jpg
        lr = data_title_to_label_row[img["video_title"]]
        frame_num = int(img["file_name"].split('/')[-1].split(".")[0])
    elif "image_title" in img:
        # COCO file exported from Encord: an image
        lr = data_title_to_label_row[img["image_title"]]
        frame_num = 0
    else:
        # Other COCO files: the file name must match the data unit title in Encord
        lr = data_title_to_label_row[img["file_name"]]
        frame_num = 0

    # Creates a mapping between the COCO image IDs and the corresponding frame indices in Encord
    # In this example, the target frame is 0 because the files in the sample project are single images
    image_id_to_frame_index[img['id']] = FrameIndex(lr.data_hash, frame=frame_num)

# Import the COCO labels into Encord
project.import_coco_labels(
    labels_dict,
    category_id_to_feature_hash,
    image_id_to_frame_index
)

{
  "info": {},
  "images": [
    {
      "id": 1,
      "file_name": "cutekitty.jpg",
      "height": 480,
      "width": 640
    },
    {
      "id": 2,
      "file_name": "cutepuppy.jpg",
      "height": 480,
      "width": 640
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [246, 251, 153, 159],
      "area": 1234.56,
      "iscrowd": false
    },
    {
      "id": 2,
      "image_id": 2,
      "category_id": 2,
      "bbox": [220, 236, 76, 64],
      "area": 5678.90,
      "iscrowd": true
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "Cat",
      "supercategory": "bounding_box"
    },
    {
      "id": 2,
      "name": "Dog",
      "supercategory": "bounding_box"
    }
  ]
}

{
  "info": {},
  "images": [
    {
      "id": 1,
      "file_name": "cutekitty.jpg",
      "height": 480,
      "width": 640
    },
    {
      "id": 2,
      "file_name": "cutepuppy.jpg",
      "height": 480,
      "width": 640
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "segmentation": [[508, 559, 512, 555, 517, 554, 520, 548, 527, 542, 531, 540, 538, 540, 553, 562]],
      "bbox": [508, 540, 45, 22],
      "area": 1234.56,
      "iscrowd": false
    },
    {
      "id": 2,
      "image_id": 2,
      "category_id": 2,
      "segmentation": [[508, 559, 512, 555, 517, 554, 520, 548, 527, 542, 531, 540, 538, 540, 553, 562]],
      "bbox": [508, 540, 45, 22],
      "area": 5678.90,
      "iscrowd": true
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "Cat",
      "supercategory": "polygon"
    },
    {
      "id": 2,
      "name": "Dog",
      "supercategory": "polygon"
    }
  ]
}

data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2()}
for img in labels_dict['images']:
    fname = img['file_name']
    stem = fname.split('/')[-1]  # The file name without its folder path. Adjust based on your filename structure
    assert stem in data_title_to_label_row, f'Problem matching {stem}'
    lr = data_title_to_label_row[stem]
    image_id_to_frame_index[img['id']] = FrameIndex(lr.data_hash, frame=0)

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

COCO Labels/Annotations