Annotations#

SAClient.upload_annotations(project, annotations, keep_status=None)#

Uploads a list of annotation dicts as annotations to the SuperAnnotate directory.

Parameters:

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

  • annotations (list of dicts) – list of annotation dictionaries corresponding to SuperAnnotate format

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

Returns:

a dictionary containing lists of successfully uploaded, failed and skipped name

Return type:

dict

Response Example:

{
   "succeeded": [],
   "failed":[],
   "skipped": []
}
SAClient.get_annotations(project, items=None)#

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.

Returns:

list of annotations

Return type:

list of dict

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

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.

Returns:

local path of the downloaded annotations folder.

Return type:

str

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