How to import annotations

You can import annotations to all project types. The annotations you upload should follow the SuperAnnotate annotation format, whose structure is based on JSON.

🚧

Character Limitation

Please limit your item name to 120 characters. Uploading any items whose names exceed this limitation will result in their names cropped. This can be an issue if you have any pre-annotations or JSONs relying on the original filenames.

Annotation file format

Before you upload annotation files, make sure they have a valid file format. The annotation files should have the following naming conventions:

❗️

When you upload annotations, make sure that their corresponding items are available in the project. If they aren’t, then the annotations won’t be uploaded.

🚧

• The annotations you upload override the existing annotations.
• When you upload an annotation, the item's status will be changed to inProgress.

Annotation format

SuperAnnotate supports the SuperAnnotate annotation format and other common annotation formats (COCO, YOLO, and VOC).

To use the common annotation formats, you need to convert the annotations to the SuperAnnotate annotation format first.

The structure of the SuperAnnotate annotation format is based on JSON. Here are the formats of imported annotations:

• Image Project
• Image (Legacy) Project
• Video or Audio Project
• Text Project

Upload annotations from memory

To upload annotations from memory, create an annotation object and pass it to the function: upload_annotations()

my_annotations = [
    {
        "metadata": {
            "name": "image1.png"
        },
        "instances": [
            {
                "type": "tag",
                "className": "Dog"
            }
        ]
    }
]

sa.upload_annotations(
    project = "Project Name",
    annotations = my_annotations)

Upload annotations from local storage

To upload annotations from a local directory: upload_annotations_from_folder_to_project()

sa.upload_annotations_from_folder_to_project(
    project = "Car Project",
    folder_path = "./data/annotations")

To enable recursive subfolder upload (when annotations are stored within multiple subfolders) set recursive_subfolders to true:

sa.upload_annotations_from_folder_to_project(
    project = "Car Project",
    folder_path = "./data/annotations", 
    recursive_subfolders = True)

🚧

When you upload annotations, the status of an item will change to inProgress.

Upload annotations from a cloud storage

AWS S3 Bucket

To upload annotations from an AWS S3 bucket:

sa.upload_annotations_from_folder_to_project(
    project = "Car Project",
    folder_path = "./data/annotations",
    from_s3_bucket = "Car Bucket")

🚧

• Make sure that you have your AWS creditials for the from_s3_bucket argument.
• When you upload annotations, the status of an item will change to inProgress.

Identify invalid annotations

When you want to upload annotations from a folder, the function will identify the invalid annotations and show you a warning message that contains the number of invalid annotations.

The function will also put the paths of invalid annotations to the return tuple of (uploaded, could-not-upload, missing-images), in the could-not-upload list accordingly.

Use the function below to fetch the possible reason(s) for why an annotation is invalid.

superannotate.validate_annotations(
     project_type = “Video”, 
     annotations_json = “./<video_name.json>”)