Annotations

Get annotations into memory

To get image annotations into the memory:

annotations = sa.get_annotations(
    project = "Project Name", 
    items = ["item_name.png"])

This will return a Python dictionary with a annotation_json key with the value of the annotations in the SuperAnnotate format.

import json
print(json.dumps(annotations["annotation_json"], indent = 4, sort_keys = True))

This is the output:

{
    "instances": [
        {
            "attributes": [],
            "classId": 816825,
            "className": "apple",
            "createdAt": "2021-06-09T11:24:54.794Z",
            "createdBy": {
                "email": "[email protected]",
                "role": "Annotator"
            },
            "creationType": "Manual",
            "error": null,
            "groupId": 0,
            "locked": false,
            "pointLabels": {},
            "points": {
                "x1": 126.35,
                "x2": 384.42,
                "y1": 748.26,
                "y2": 921.96
            },
            "probability": 100,
            "trackingId": null,
            "type": "bbox",
            "updatedAt": "2021-07-27T14:21:52.904Z",
            "updatedBy": {
                "email": "[email protected]",
                "role": "QA"
            },
            "visible": true
        }
    ],
    "metadata": {
        "height": 1024,
        "width": 1024,
        "name": "fruit.png",  
        "lastAction": {
            "email": "[email protected]",
            "timestamp": 1627395705911
        }
    },
    "tags": [],
    "comments": []
}

Download annotations

To download image annotations:

sa.download_image_annotations(
    project = "Project Name",
    image_name = "image_name.png",
    local_dir_path = "./annotations")

🚧

Use the prepare_export functionality to download images or annotations in bulk. Learn more here.

To download annotations from a project's root:

sa.download_annotations(
   project="Project 1", 
   path="/Users/projectadmin/Desktop/Annotations"
)

To download all the annotations from a project:

sa.download_annotations(
   project="Project 1", 
   path="/Users/projectadmin/Desktop/Annotations", 
   recursive=True
)

To download specific items:

# step 1: query completed annotations and store item names

completed_item_names = [
    item['name'] for item in sa.query(
        project="Image Project",
        query="metadata(status = Completed)" 
    )
]

print(f'there are {len(completed_item_names)} completed items names are: {completed_item_names}')

# step 2: download annotations by providing the list of item names

sa.download_annotations(
   project="Image Project", 
   path="/Users/projectadmin/Desktop/Annotations", 
   items = completed_item_names,
   recursive=True
)

To download annotations using a specific JSON structure:

# step 1: define the converter function that accepts the SA annotation dict as an argument

def convert(sa_annotation): 
    filtered_boxes = [
        instance for instance in sa_annotation['instances'] if instance['type'] == 'bbox' 
    ]
    boxes = list(map(lambda box: 
            {
                'type': box['type'],
                'class': box['className'],
                'coordinates': box['points']
            }, filtered_boxes) 
    )
    return {'objects': boxes}

#step 2: pass the converter function to callback parameter

sa.download_annotations(
   project="Project 1", 
   path="/Users/projectadmin/Desktop/Annotations", 
   items=["Image 1.jpeg"],
   recursive=True,
   callback=convert
)