Annotations#

SAClient.upload_annotations(project, annotations, keep_status=None, *, data_spec='default')#

Uploads a list of annotation dictionaries to the specified SuperAnnotate project or folder.

Parameters:

  • project (str) – The project name or folder path where annotations will be uploaded (e.g., “project1/folder1”).

  • annotations (list of dict) – A list of annotation dictionaries formatted according to the SuperAnnotate standards.

  • keep_status (bool, optional) – If False, the annotation status will be automatically updated to “InProgress.” If True, the current status will remain unchanged.

  • data_spec (str, optional) –

    Specifies the format for processing and transforming annotations before upload.

    Options are:

    • default: Retains the annotations in their original format.

    • multimodal: Converts annotations for multimodal projects, optimizing for

      compact and modality-specific data representation.

Returns:

A dictionary containing the results of the upload, categorized into successfully uploaded, failed, and skipped annotations.

Return type:

dict

Response Example:

{
   "succeeded": [],
   "failed": [],
   "skipped": []
}

Example Usage with JSONL Upload for Multimodal Projects:

import json
from pathlib import Path
from superannotate import SAClient

annotations_path = Path("annotations.jsonl")
annotations = []

# Reading the JSONL file and converting it into a list of dictionaries
with annotations_path.open("r", encoding="utf-8") as f:
    for line in f:
        annotations.append(json.loads(line))

# Initialize the SuperAnnotate client
sa = SAClient()

# Call the upload_annotations function
response = sa.upload_annotations(
    project="project1/folder1",
    annotations=annotations,
    keep_status=True,
    data_spec='multimodal'
)
SAClient.get_annotations(project, items=None, *, data_spec='default')#

Returns annotations for the given list of items.

Parameters:

  • project (str or int) – project id or project name or folder path (e.g., “project1/folder1”).

  • items (list of strs or list of ints) – item names. If None, all the items in the specified directory will be used.

  • data_spec (str, optional) –

    Specifies the format for processing and transforming annotations before upload.

    Options are:

    • default: Retains the annotations in their original format.

    • multimodal: Converts annotations for multimodal projects, optimizing for

      compact and multimodal-specific data representation.

Example Usage of Multimodal Projects:

from superannotate import SAClient


sa = SAClient()

# Call the get_annotations function
response = sa.get_annotations(
    project="project1/folder1",
    items=["item_1", "item_2"],
    data_spec='multimodal'
)
Returns:

list of annotations

Return type:

list of dict

Parameters:

  • project (ConstrainedStrValue | int) –

  • items (List[ConstrainedStrValue] | List[int] | None) –

  • data_spec (typing_extensions.Literal[default, multimodal]) –

SAClient.download_annotations(project, path=None, items=None, recursive=False, callback=None, data_spec='default')#

Downloads annotation JSON files of the selected items to the local directory.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”).

  • path (Path-like (str or Path)) – local directory path where the annotations will be downloaded. If none, the current directory is used.

  • items (list of str) – list of item names whose annotations will be downloaded (e.g., [“Image_1.jpeg”, “Image_2.jpeg”]). If the value is None, then all the annotations of the given directory will be downloaded.

  • recursive (bool) – download annotations from the project’s root and all of its folders with the preserved structure. If False download only from the project’s root or given directory.

  • callback (callable) – a function that allows you to modify each annotation’s dict before downloading. The function receives each annotation as an argument and the returned value will be applied to the download.

  • data_spec (str, optional) –

    Specifies the format for processing and transforming annotations before upload.

    Options are:

    • default: Retains the annotations in their original format.

    • multimodal: Converts annotations for multimodal projects, optimizing for

      compact and multimodal-specific data representation.

Example Usage of Multimodal Projects:

from superannotate import SAClient


sa = SAClient()

# Call the get_annotations function
response = sa.download_annotations(
    project="project1/folder1",
    path="path/to/download",
    items=["item_1", "item_2"],
    data_spec='multimodal'
)
Returns:

local path of the downloaded annotations folder.

Return type:

str

Parameters:

  • project (ConstrainedStrValue | dict) –

  • path (str | Path) –

  • items (List[ConstrainedStrValue] | None) –

  • recursive (bool) –

  • callback (Callable) –

  • data_spec (typing_extensions.Literal[default, multimodal]) –

SAClient.get_annotations_per_frame(project, video, fps=1)#

Returns per frame annotations for the given video.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”).

  • video (str) – video name

  • fps (str) – how many frames per second needs to be extracted from the video. Will extract 1 frame per second by default.

Returns:

list of annotation objects

Return type:

list of dicts

SAClient.set_annotation_statuses(project, annotation_status, items=None)#

Sets annotation statuses of items.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”).

  • annotation_status (str) – The desired status to set for the annotation. This status should match one of the predefined statuses available in the project workflow.

  • items (list of strs) – item names. If None, all the items in the specified directory will be used.

SAClient.delete_annotations(project, item_names=None)#

Delete item annotations from a given list of items.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”)

  • item_names (list of strs) – item names. If None, all the annotations in the specified directory will be deleted.

SAClient.upload_annotations_from_folder_to_project(project, folder_path, from_s3_bucket=None, recursive_subfolders=False, keep_status=None)#

Finds and uploads all JSON files in the folder_path as annotations to the project.

The JSON files should follow specific naming convention. For Vector projects they should be named “<image_filename>___objects.json” (e.g., if image is cats.jpg the annotation filename should be cats.jpg___objects.json), for Pixel projects JSON file should be named “<image_filename>___pixel.json” and also second mask image file should be present with the name “<image_name>___save.png”. In both cases image with <image_name> should be already present on the platform.

Existing annotations will be overwritten.

Parameters:

  • project (str or dict) – project name or folder path (e.g., “project1/folder1”)

  • folder_path (str or dict) – from which folder to upload annotations

  • from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem

  • recursive_subfolders (bool) – enable recursive subfolder parsing

  • keep_status (bool) – If False, the annotation status will be automatically updated to “InProgress,” otherwise the current status will be kept.

Returns:

paths to annotations uploaded, could-not-upload, missing-images

Return type:

tuple of list of strs