API Reference

Remote functions

Initialization and authentication

superannotate.init(path_to_config_json)

Initializes and authenticates to SuperAnnotate platform using the config file. If not initialized then $HOME/.superannotate/config.json will be used.

Parameters:path_to_config_json (str or Path) – Location to config JSON file

Projects

superannotate.search_projects(name=None, return_metadata=False, include_complete_image_count=False)

Project name based case-insensitive search for projects. If name is None, all the projects will be returned.

Parameters:
  • name (str) – search string
  • return_metadata (bool) – return metadata of projects instead of names
Returns:

project names or metadatas
Return type:

list of strs or dicts
superannotate.create_project(project_name, project_description, project_type)

Create a new project in the team.

Parameters:
  • project_name (str) – the new project’s name
  • project_description (str) – the new project’s description
  • project_type (str) – the new project type, Vector or Pixel.
Returns:

dict object metadata the new project
Return type:

dict
superannotate.create_project_from_metadata(project_metadata)

Create a new project in the team using project metadata object dict. Mandatory keys in project_metadata are “name”, “description” and “type” (Vector or Pixel) Non-mandatory keys: “workflow”, “contributors”, “settings” and “annotation_classes”.

Returns:dict object metadata the new project
Return type:dict
superannotate.clone_project(project_name, from_project, project_description=None, copy_annotation_classes=True, copy_settings=True, copy_workflow=True, copy_contributors=False)

Create a new project in the team using annotation classes and settings from from_project.

Parameters:
  • project_name (str) – new project’s name
  • from_project (str) – the name of the project being used for duplication
  • project_description (str) – the new project’s description. If None, from_project’s description will be used
  • copy_annotation_classes (bool) – enables copying annotation classes
  • copy_settings (bool) – enables copying project settings
  • copy_workflow (bool) – enables copying project workflow
  • copy_contributors (bool) – enables copying project contributors
Returns:

dict object metadata of the new project
Return type:

dict
superannotate.delete_project(project)

Deletes the project

Parameters:project (str) – project name or folder path (e.g., “project1/folder1”)
superannotate.rename_project(project, new_name)

Renames the project

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • new_name (str) – project’s new name
superannotate.get_project_metadata(project, include_annotation_classes=False, include_settings=False, include_workflow=False, include_contributors=False, include_complete_image_count=False)

Returns project metadata

Parameters:
  • project (str) – project name
  • include_annotation_classes (bool) – enables project annotation classes output under the key “annotation_classes”
  • include_settings (bool) – enables project settings output under the key “settings”
  • include_workflow (bool) – enables project workflow output under the key “workflow”
  • include_contributors (bool) – enables project contributors output under the key “contributors”
Returns:

metadata of project
Return type:

dict
superannotate.get_project_image_count(project, with_all_subfolders=False)

Returns number of images in the project.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • with_all_subfolders (bool) – enables recursive folder counting
Returns:

number of images in the project
Return type:

int
superannotate.get_project_and_folder_metadata(project)

Returns project and folder metadata tuple. If folder part is empty, than returned folder part is set to None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • folder_name (str) – folder’s name
Returns:

metadata of folder
Return type:

dict
superannotate.search_folders(project, folder_name=None, return_metadata=False)

Folder name based case-insensitive search for folders in project.

Parameters:
  • project (str) – project name
  • folder_name (str. If None, all the folders in the project will be returned.) – the new folder’s name
  • return_metadata (bool) – return metadata of folders instead of names
Returns:

folder names or metadatas
Return type:

list of strs or dicts
superannotate.get_folder_metadata(project, folder_name)

Returns folder metadata

Parameters:
  • project (str) – project name
  • folder_name (str) – folder’s name
Returns:

metadata of folder
Return type:

dict
superannotate.create_folder(project, folder_name)

Create a new folder in the project.

Parameters:
  • project (str) – project name
  • folder_name (str) – the new folder’s name
Returns:

dict object metadata the new folder
Return type:

dict
superannotate.delete_folders(project, folder_names)

Delete folder in project.

Parameters:
  • project (str) – project name
  • folder_names (list of strs) – to be deleted folders’ names
superannotate.rename_folder(project, new_folder_name)

Renames folder in project.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • new_folder_name (str) – folder’s new name
superannotate.upload_images_to_project(project, img_paths, annotation_status='NotStarted', from_s3_bucket=None, image_quality_in_editor=None)

Uploads all images given in list of path objects in img_paths to the project. Sets status of all the uploaded images to set_status if it is not None.

If an image with existing name already exists in the project it won’t be uploaded, and its path will be appended to the third member of return value of this function.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • img_paths (list) – list of Pathlike (str or Path) objects to upload
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded, could-not-upload, existing-images filepaths
Return type:

tuple (3 members) of list of strs
superannotate.attach_image_urls_to_project(project, attachments, annotation_status='NotStarted')

Link images on external storage to SuperAnnotate.

Parameters:
  • project (str or dict) – project name or project folder path
  • attachments (Pathlike (str or Path)) – path to csv file on attachments metadata
  • annotation_status (str) – value to set the annotation statuses of the linked images: NotStarted InProgress QualityCheck Returned Completed Skipped
Returns:

list of linked image names, list of failed image names, list of duplicate image names
Return type:

tuple
superannotate.upload_images_from_public_urls_to_project(project, img_urls, img_names=None, annotation_status='NotStarted', image_quality_in_editor=None)

Uploads all images given in the list of URL strings in img_urls to the project. Sets status of all the uploaded images to annotation_status if it is not None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • img_urls (list) – list of str objects to upload
  • img_names (list) – list of str names for each urls in img_url list
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type:

tuple of list of strs
superannotate.upload_images_from_google_cloud_to_project(project, google_project, bucket_name, folder_path, annotation_status='NotStarted', image_quality_in_editor=None)

Uploads all images present in folder_path at bucket_name in google_project to the project. Sets status of all the uploaded images to set_status if it is not None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • google_project (str) – the project name on google cloud, where the bucket resides
  • bucket_name (str) – the name of the bucket where the images are stored
  • folder_path (str) – path of the folder on the bucket where the images are stored
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type:

tuple of list of strs
superannotate.upload_images_from_azure_blob_to_project(project, container_name, folder_path, annotation_status='NotStarted', image_quality_in_editor=None)

Uploads all images present in folder_path at container_name Azure blob storage to the project. Sets status of all the uploaded images to set_status if it is not None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • container_name (str) – container name of the Azure blob storage
  • folder_path (str) – path of the folder on the bucket where the images are stored
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type:

tuple of list of strs
superannotate.upload_image_to_project(project, img, image_name=None, annotation_status='NotStarted', from_s3_bucket=None, image_quality_in_editor=None)

Uploads image (io.BytesIO() or filepath to image) to project. Sets status of the uploaded image to set_status if it is not None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • img (io.BytesIO() or Pathlike (str or Path)) – image to upload
  • image_name (str) – image name to set on platform. If None and img is filepath, image name will be set to filename of the path
  • annotation_status (str) – value to set the annotation statuses of the uploaded image NotStarted InProgress QualityCheck Returned Completed Skipped
  • from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
superannotate.upload_images_from_folder_to_project(project, folder_path, extensions=('jpg', 'jpeg', 'png', 'tif', 'tiff', 'webp', 'bmp'), annotation_status='NotStarted', from_s3_bucket=None, exclude_file_patterns=('___save.png', '___fuse.png'), recursive_subfolders=False, image_quality_in_editor=None)

Uploads all images with given extensions from folder_path to the project. Sets status of all the uploaded images to set_status if it is not None.

If an image with existing name already exists in the project it won’t be uploaded, and its path will be appended to the third member of return value of this function.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • folder_path (Pathlike (str or Path)) – from which folder to upload the images
  • extensions (tuple or list of strs) – tuple or list of filename extensions to include from folder
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
  • exclude_file_patterns (list or tuple of strs) – filename patterns to exclude from uploading, default value is to exclude SuperAnnotate export related [“___save.png”, “___fuse.png”]
  • recursive_subfolders (bool) – enable recursive subfolder parsing
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded, could-not-upload, existing-images filepaths
Return type:

tuple (3 members) of list of strs
superannotate.upload_video_to_project(project, video_path, target_fps=None, start_time=0.0, end_time=None, annotation_status='NotStarted', image_quality_in_editor=None)

Uploads image frames from video to platform. Uploaded images will have names “<video_name>_<frame_no>.jpg”.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • video_path (Pathlike (str or Path)) – video to upload
  • target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded
  • start_time (float) – Time (in seconds) from which to start extracting frames
  • end_time (float) – Time (in seconds) up to which to extract frames. If None up to end
  • annotation_status (str) – value to set the annotation statuses of the uploaded video frames NotStarted InProgress QualityCheck Returned Completed Skipped
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

filenames of uploaded images
Return type:

list of strs
superannotate.upload_videos_from_folder_to_project(project, folder_path, extensions=('mp4', 'avi', 'mov', 'webm', 'flv', 'mpg', 'ogg'), exclude_file_patterns=(), recursive_subfolders=False, target_fps=None, start_time=0.0, end_time=None, annotation_status='NotStarted', image_quality_in_editor=None)

Uploads image frames from all videos with given extensions from folder_path to the project. Sets status of all the uploaded images to set_status if it is not None.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • folder_path (Pathlike (str or Path)) – from which folder to upload the videos
  • extensions (tuple or list of strs) – tuple or list of filename extensions to include from folder
  • exclude_file_patterns (listlike of strs) – filename patterns to exclude from uploading
  • recursive_subfolders (bool) – enable recursive subfolder parsing
  • target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded
  • start_time (float) – Time (in seconds) from which to start extracting frames
  • end_time (float) – Time (in seconds) up to which to extract frames. If None up to end
  • annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
  • image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns:

uploaded and not-uploaded video frame images’ filenames
Return type:

tuple of list of strs
superannotate.upload_annotations_from_folder_to_project(project, folder_path, from_s3_bucket=None, recursive_subfolders=False)

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) – project name or folder path (e.g., “project1/folder1”)
  • 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
Returns:

paths to annotations uploaded, could-not-upload, missing-images
Return type:

tuple of list of strs
superannotate.upload_preannotations_from_folder_to_project(project, folder_path, from_s3_bucket=None, recursive_subfolders=False)

Finds and uploads all JSON files in the folder_path as pre-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 pre-annotations will be overwritten.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • folder_path (Pathlike (str or Path)) – from which folder to upload the pre-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
Returns:

paths to pre-annotations uploaded and could-not-upload
Return type:

tuple of list of strs
superannotate.share_project(project, user, user_role)

Share project with user.

Parameters:
  • project (str) – project name
  • user (str or dict) – user email or metadata of the user to share project with
  • user_role (str) – user role to apply, one of Admin , Annotator , QA , Customer , Viewer
superannotate.unshare_project(project, user)

Unshare (remove) user from project.

Parameters:
  • project (str) – project name
  • user (str or dict) – user email or metadata of the user to unshare project
superannotate.get_project_settings(project)

Gets project’s settings.

Return value example: [{ “attribute” : “Brightness”, “value” : 10, …},…]

Parameters:project (str or dict) – project name or metadata
Returns:project settings
Return type:list of dicts
superannotate.set_project_settings(project, new_settings)

Sets project’s settings.

New settings format example: [{ “attribute” : “Brightness”, “value” : 10, …},…]

Parameters:
  • project (str or dict) – project name or metadata
  • new_settings (list of dicts) – new settings list of dicts
Returns:

updated part of project’s settings
Return type:

list of dicts
superannotate.get_project_default_image_quality_in_editor(project)

Gets project’s default image quality in editor setting.

Parameters:project (str or dict) – project name or metadata
Returns:“original” or “compressed” setting value
Return type:str
superannotate.set_project_default_image_quality_in_editor(project, image_quality_in_editor)

Sets project’s default image quality in editor setting.

Parameters:
  • project (str or dict) – project name or metadata
  • image_quality_in_editor (str) – new setting value, should be “original” or “compressed”
superannotate.get_project_workflow(project)

Gets project’s workflow.

Return value example: [{ “step” : <step_num>, “className” : <annotation_class>, “tool” : <tool_num>, …},…]

Parameters:project (str or dict) – project name or metadata
Returns:project workflow
Return type:list of dicts
superannotate.set_project_workflow(project, new_workflow)

Sets project’s workflow.

new_workflow example: [{ “step” : <step_num>, “className” : <annotation_class>, “tool” : <tool_num>,
“attribute”:[{“attribute” : {“name” : <attribute_value>, “attribute_group” : {“name”: <attribute_group>}}}, …] },…]
Parameters:
  • project (list of dicts) – project name or metadata
  • project – new workflow list of dicts

Exports

superannotate.prepare_export(project, folder_names=None, annotation_statuses=None, include_fuse=False, only_pinned=False)

Prepare annotations and classes.json for export. Original and fused images for images with annotations can be included with include_fuse flag.

Parameters:
  • project (str) – project name
  • folder_names (list of str) – names of folders to include in the export. If None, whole project will be exported
  • annotation_statuses (list of strs) – images with which status to include, if None, [ “InProgress”, “QualityCheck”, “Returned”, “Completed”] will be chose list elements should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
  • include_fuse (bool) – enables fuse images in the export
  • only_pinned (bool) – enable only pinned output in export. This option disables all other types of output.
Returns:

metadata object of the prepared export
Return type:

dict
superannotate.download_export(project, export, folder_path, extract_zip_contents=True, to_s3_bucket=None)

Download prepared export.

WARNING: Starting from version 1.9.0 download_export additionally requires project as first argument.

Parameters:
  • project (str) – project name
  • export (str) – export name
  • folder_path (Pathlike (str or Path)) – where to download the export
  • extract_zip_contents (bool) – if False then a zip file will be downloaded, if True the zip file will be extracted at folder_path
  • to_s3_bucket – AWS S3 bucket to use for download. If None then folder_path is in local filesystem.
superannotate.get_exports(project, return_metadata=False)

Get all prepared exports of the project.

Parameters:
  • project (str) – project name
  • return_metadata (bool) – return metadata of images instead of names
Returns:

names or metadata objects of the all prepared exports of the project
Return type:

list of strs or dicts

Images

superannotate.search_images(project, image_name_prefix=None, annotation_status=None, return_metadata=False)

Search images by name_prefix (case-insensitive) and annotation status

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name_prefix (str) – image name prefix for search
  • annotation_status (str) – if not None, annotation statuses of images to filter, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
  • return_metadata (bool) – return metadata of images instead of names
Returns:

metadata of found images or image names
Return type:

list of dicts or strs
superannotate.search_images_all_folders(project, image_name_prefix=None, annotation_status=None, return_metadata=False)

Search images by name_prefix (case-insensitive) and annotation status in project and all of its folders

Parameters:
  • project (str) – project name
  • image_name_prefix (str) – image name prefix for search
  • annotation_status (str) – if not None, annotation statuses of images to filter, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
  • return_metadata (bool) – return metadata of images instead of names
Returns:

metadata of found images or image names
Return type:

list of dicts or strs
superannotate.get_image_metadata(project, image_names, return_dict_on_single_output=True)

Returns image metadata

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
Returns:

metadata of image
Return type:

dict
superannotate.get_image_bytes(project, image_name, variant='original')

Returns an io.BytesIO() object of the image. Suitable for creating PIL.Image out of it.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • variant (str) – which resolution to get, can be ‘original’ or ‘lores’ (low resolution)
Returns:

io.BytesIO() of the image
Return type:

io.BytesIO()
superannotate.download_image(project, image_name, local_dir_path='.', include_annotations=False, include_fuse=False, include_overlay=False, variant='original')

Downloads the image (and annotation if not None) to local_dir_path

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • local_dir_path (Pathlike (str or Path)) – where to download the image
  • include_annotations (bool) – enables annotation download with the image
  • include_fuse (bool) – enables fuse image download with the image
  • variant (str) – which resolution to download, can be ‘original’ or ‘lores’ (low resolution used in web editor)
Returns:

paths of downloaded image and annotations if included
Return type:

tuple
superannotate.set_image_annotation_status(project, image_name, annotation_status)

Sets the image annotation status

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name (str) – image name
  • annotation_status (str) – annotation status to set, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
Returns:

metadata of the updated image
Return type:

dict
superannotate.set_images_annotation_statuses(project, image_names, annotation_status)

Sets annotation statuses of images

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_names (list of str) – image names. If None, all the images in the project will be used
  • annotation_status (str) – annotation status to set, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
superannotate.get_image_annotations(project, image_name)

Get annotations of the image.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
Returns:

dict object with following keys: “annotation_json”: dict object of the annotation, “annotation_json_filename”: filename on server, “annotation_mask”: mask (for pixel), “annotation_mask_filename”: mask filename on server
Return type:

dict
superannotate.get_image_preannotations(project, image_name)

Get pre-annotations of the image. Only works for “vector” projects.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
Returns:

dict object with following keys: “preannotation_json”: dict object of the annotation, “preannotation_json_filename”: filename on server, “preannotation_mask”: mask (for pixel), “preannotation_mask_filename”: mask filename on server
Return type:

dict
superannotate.download_image_annotations(project, image_name, local_dir_path)

Downloads annotations of the image (JSON and mask if pixel type project) to local_dir_path.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • local_dir_path (Pathlike (str or Path)) – local directory path to download to
Returns:

paths of downloaded annotations
Return type:

tuple
superannotate.download_image_preannotations(project, image_name, local_dir_path)

Downloads pre-annotations of the image to local_dir_path. Only works for “vector” projects.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • local_dir_path (Pathlike (str or Path)) – local directory path to download to
Returns:

paths of downloaded pre-annotations
Return type:

tuple
superannotate.upload_image_annotations(project, image_name, annotation_json, mask=None, verbose=True)

Upload annotations from JSON (also mask for pixel annotations) to the image.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON dict or path to JSON file
  • mask (BytesIO or Pathlike (str or Path)) – BytesIO object or filepath to mask annotation for pixel projects in SuperAnnotate format
superannotate.copy_image(source_project, image_name, destination_project, include_annotations=False, copy_annotation_status=False, copy_pin=False)

Copy image to a project. The image’s project is the same as destination project then the name will be changed to <image_name>_(<num>).<image_ext>, where <num> is the next available number deducted from project image list.

Parameters:
  • source_project (str or dict) – project name plus optional subfolder in the project (e.g., “project1/folder1”) or metadata of the project of source project
  • image_name – image name
  • destination_project (str or dict) – project name or metadata of the project of destination project
  • include_annotations (bool) – enables annotations copy
  • copy_annotation_status (bool) – enables annotations status copy
  • copy_pin (bool) – enables image pin status copy
superannotate.copy_images(source_project, image_names, destination_project, include_annotations=True, copy_annotation_status=True, copy_pin=True)

Copy images in bulk between folders in a project

Parameters:
  • source_project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_names – image names. If None, all images from source project will be copied
  • destination_project (str) – project name or folder path (e.g., “project1/folder2”)
  • include_annotations (bool) – enables annotations copy
  • copy_annotation_status (bool) – enables annotations status copy
  • copy_pin (bool) – enables image pin status copy
superannotate.move_image(source_project, image_name, destination_project, include_annotations=True, copy_annotation_status=True, copy_pin=True)

Move image from source_project to destination_project. source_project and destination_project cannot be the same.

Parameters:
  • source_project (str or dict) – project name or metadata of the project of source project
  • image_name – image name
  • destination_project (str or dict) – project name or metadata of the project of destination project
  • include_annotations (bool) – enables annotations move
  • copy_annotation_status (bool) – enables annotations status copy
  • copy_pin (bool) – enables image pin status copy
superannotate.move_images(source_project, image_names, destination_project, include_annotations=True, copy_annotation_status=True, copy_pin=True)

Move images in bulk between folders in a project

Parameters:
  • source_project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_names – image names. If None, all images from source project will be moved
  • destination_project (str) – project name or folder path (e.g., “project1/folder2”)
  • include_annotations (bool) – enables annotations copy
  • copy_annotation_status (bool) – enables annotations status copy
  • copy_pin (bool) – enables image pin status copy
superannotate.pin_image(project, image_name, pin=True)

Pins (or unpins) image

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • pin (bool) – sets to pin if True, else unpins image
superannotate.assign_images(project, image_names, user)

Assigns images to a user. The assignment role, QA or Annotator, will be deduced from the user’s role in the project. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_names (list of str) – list of image names to assign
  • user (str) – user email
superannotate.delete_image(project, image_name)

Deletes image

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
superannotate.delete_images(project, image_names)

Delete images in project.

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_names (list of strs) – to be deleted images’ names. If None, all the images will be deleted
superannotate.add_annotation_bbox_to_image(project, image_name, bbox, annotation_class_name, annotation_class_attributes=None, error=None)

Add a bounding box annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>” }, “groupName” : “<attribute_group>”} ], … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • bbox (list of floats) – 4 element list of top-left x,y and bottom-right x, y coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_polygon_to_image(project, image_name, polygon, annotation_class_name, annotation_class_attributes=None, error=None)

Add a polygon annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • polygon (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_polyline_to_image(project, image_name, polyline, annotation_class_name, annotation_class_attributes=None, error=None)

Add a polyline annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • polyline (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_point_to_image(project, image_name, point, annotation_class_name, annotation_class_attributes=None, error=None)

Add a point annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • point (list of floats) – [x,y] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_ellipse_to_image(project, image_name, ellipse, annotation_class_name, annotation_class_attributes=None, error=None)

Add an ellipse annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • ellipse (list of floats) – [center_x, center_y, r_x, r_y, angle] list of coordinates and angle
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_template_to_image(project, image_name, template_points, template_connections, annotation_class_name, annotation_class_attributes=None, error=None)

Add a template annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • template_points (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • template_connections (list of ints) – [from_id_1,to_id_1,from_id_2,to_id_2,…] list of indexes from -> to. Indexes are based on template_points. E.g., to have x1,y1 to connect to x2,y2 and x1,y1 to connect to x4,y4, need: [1,2,1,4,…]
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_cuboid_to_image(project, image_name, cuboid, annotation_class_name, annotation_class_attributes=None, error=None)

Add a cuboid annotation to image annotations

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • cuboid (list of floats) – [x_front_tl,y_front_tl,x_front_br,y_front_br, x_back_tl,y_back_tl,x_back_br,y_back_br] list of coordinates of front rectangle and back rectangle, in top-left and bottom-right format
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_comment_to_image(project, image_name, comment_text, comment_coords, comment_author, resolved=False)

Add a comment to SuperAnnotate format annotation JSON

Parameters:
  • project (str) – project name or folder path (e.g., “project1/folder1”)
  • image_name – image name
  • comment_text (str) – comment text
  • comment_coords (list) – [x, y] coords
  • comment_author (str) – comment author email
  • resolved (bool) – comment resolve status
superannotate.create_fuse_image(image, classes_json, project_type, in_memory=False, output_overlay=False)

Creates fuse for locally located image and annotations

Parameters:
  • image (list or Pathlike) – path to image
  • image_name – annotation classes or path to their JSON
  • project_type (str) – project type, “Vector” or “Pixel”
  • in_memory (bool) – enables pillow Image return instead of saving the image
Returns:

path to created fuse image or pillow Image object if in_memory enabled
Return type:

str of PIL.Image

Annotation Classes

superannotate.create_annotation_class(project, name, color, attribute_groups=None)

Create annotation class in project

Parameters:
  • project (str) – project name
  • name (str) – name for the class
  • color (str) – RGB hex color value, e.g., “#FFFFAA”
  • attribute_groups (list of dicts) – example: [ { “name”: “tall”, “is_multiselect”: 0, “attributes”: [ { “name”: “yes” }, { “name”: “no” } ] }, { “name”: “age”, “is_multiselect”: 0, “attributes”: [ { “name”: “young” }, { “name”: “old” } ] } ]
Returns:

new class metadata
Return type:

dict
superannotate.create_annotation_classes_from_classes_json(project, classes_json, from_s3_bucket=None)

Creates annotation classes in project from a SuperAnnotate format annotation classes.json.

Parameters:
  • project (str) – project name
  • classes_json (list or Pathlike (str or Path)) – JSON itself or path to the JSON file
  • from_s3_bucket (str) – AWS S3 bucket to use. If None then classes_json is in local filesystem
Returns:

list of created annotation class metadatas
Return type:

list of dicts
superannotate.get_annotation_class_metadata(project, annotation_class_name)

Returns annotation class metadata

Parameters:
  • project (str) – project name
  • annotation_class_name (str) – annotation class name
Returns:

metadata of annotation class
Return type:

dict
superannotate.search_annotation_classes(project, name_prefix=None)

Searches annotation classes by name_prefix (case-insensitive)

Parameters:
  • project (str) – project name
  • name_prefix (str) – name prefix for search. If None all annotation classes will be returned
Returns:

annotation classes of the project
Return type:

list of dicts
superannotate.download_annotation_classes_json(project, folder)

Downloads project classes.json to folder

Parameters:
  • project (str) – project name
  • folder (Pathlike (str or Path)) – folder to download to
Returns:

path of the download file
Return type:

str
superannotate.delete_annotation_class(project, annotation_class)

Deletes annotation class from project

Parameters:
  • project (str or dict) – project name
  • project – annotation class name or metadata

Team contributors

superannotate.get_team_metadata()

Returns team metadata

Parameters:convert_users_role_to_string (bool) – convert integer team users’ roles to human comprehensible strings
Returns:team metadata
Return type:dict
superannotate.invite_contributor_to_team(email, admin=False)

Invites a contributor to team

Parameters:
  • email (str) – email of the contributor
  • admin (bool) – enables admin priviledges for the contributor
superannotate.delete_contributor_to_team_invitation(email)

Deletes team contributor invitation

Parameters:email (str) – invitation email

Remote metadata reference

Projects metadata

Project metadata example:

{
  "name": "Example Project test",
  "description": "test vector",
  "creator_id": "hovnatan@superannotate.com",
  "updatedAt": "2020-08-31T05:43:43.118Z",
  "createdAt": "2020-08-31T05:43:43.118Z"
  "type": "Vector",
  "attachment_name": None,
  "attachment_path": None,
  "entropy_status": 1,
  "status": 0,
  "...": "..."
}

Export metadata

Export metadata example:

{
  "name": "Aug 17 2020 15:44 Hovnatan.zip",
  "user_id": "hovnatan@gmail.com",
  "status": 2,
  "createdAt": "2020-08-17T11:44:26.000Z",
  "...": "..."
}

Image metadata

Image metadata example:

{
   "name": "000000000001.jpg",
   "annotation_status": "Completed",
   "prediction_status": 1,
   "segmentation_status": 1,
   "annotator_id": None,
   "annotator_name": None,
   "qa_id": None,
   "qa_name": None,
   "entropy_value": None,
   "approval_status": None,
   "createdAt": "2020-08-18T07:30:06.000Z",
   "updatedAt": "2020-08-18T07:30:06.000Z"
   "is_pinned": 0,
   "...": "...",
}

Annotation class metadata

Annotation class metadata example:

{
  "id": 4444,
  "name": "Human",
  "color": "#e4542b",
  "attribute_groups": [
     {
        "name": "tall",
        "attributes": [
           {
              "name": "yes"
           },
           {
              "name": "no"
           }
        ]
     },
     {
       "name": "age",
       "attributes": [
           {
             "name": "young"
           },
           {
             "name": "old"
           }
       ]
     }
  ],

  "...": "..."
}

Team contributor metadata

Team contributor metadata example:

{
  "id": "hovnatan@superannotate.com",
  "first_name": "Hovnatan",
  "last_name": "Karapetyan",
  "email": "hovnatan@superannotate.com",
  "user_role": 6
  "...": "...",
}

Annotation JSON helper functions

Converting annotation format to and from SuperAnnotate format

superannotate.import_annotation(input_dir, output_dir, dataset_format, dataset_name='', project_type='Vector', task='object_detection', images_root='', images_extensions=None)

Converts other annotation formats to SuperAnnotate annotation format. Currently available (project_type, task) combinations for converter presented below:

From COCO to SA
project_type task
Pixel panoptic_segmentation
Pixel instance_segmentation
Vector instance_segmentation
Vector object_detection
Vector keypoint_detection
From VOC to SA
project_type task
Pixel instance_segmentation
Vector instance_segmentation
Vector object_detection
From LabelBox to SA
project_type task
Vector object_detection
Vector instance_segmentation
Vector vector_annotation
Pixel instance_segmentation
From DataLoop to SA
project_type task
Vector object_detection
Vector instance_segmentation
Vector vector_annotation
From Supervisely to SA
project_type task
Vector object_detection
Vector keypoint_detection
Vector vector_annotation
Vector instance_segmentation
Pixel instance_segmentation
From VoTT to SA
project_type task
Vector instance_segmentation
Vector object_detection
Vector vector_annotation
From SageMaker to SA
project_type task
Pixel instance_segmentation
Vector objcet_detection
From VGG to SA
project_type task
Vector instance_segmentation
Vector object_detection
Vector vector_annotation
From GoogleCloud to SA
project_type task
Vector object_detection
From YOLO to SA
project_type task
Vector object_detection
Parameters:
  • input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
  • output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
  • dataset_format (str) – Annotation format to convert SuperAnnotate annotation format. Available candidates are: [“COCO”, “VOC”, “LabelBox”, “DataLoop”, “Supervisely”, ‘VGG’, ‘YOLO’, ‘SageMake’, ‘VoTT’, ‘GoogleCloud’]
  • dataset_name (str) – Name of the json file in the input_dir, which should be converted.
  • project_type (str) – SuperAnnotate project type is either ‘Vector’ or ‘Pixel’ (Default: ‘Vector’) ‘Vector’ project creates <image_name>___objects.json for each image. ‘Pixel’ project creates <image_name>___pixel.jsons and <image_name>___save.png annotation mask for each image.
  • task – Task can be one of the following: [‘panoptic_segmentation’, ‘instance_segmentation’, ‘keypoint_detection’, ‘object_detection’, ‘vector_annotation’]. (Default: “object_detection”). ‘keypoint_detection’ can be used to converts keypoints from/to available annotation format. ‘panoptic_segmentation’ will use panoptic mask for each image to generate bluemask for SuperAnnotate annotation format and use bluemask to generate panoptic mask for invert conversion. Panoptic masks should be in the input folder. ‘instance_segmentation’ ‘Pixel’ project_type converts instance masks and ‘Vector’ project_type generates bounding boxes and polygons from instance masks. Masks should be in the input folder if it is ‘Pixel’ project_type. ‘object_detection’ converts objects from/to available annotation format ‘vector_annotation’ can be used to convert all annotations (point, ellipse, circule, cuboid and etc) to SuperAnnotate vector project.
  • images_root (str) – Additonal path to images directory in input_dir
  • image_extensions (list) – List of image files xtensions in the images_root folder
superannotate.export_annotation(input_dir, output_dir, dataset_format, dataset_name, project_type='Vector', task='object_detection')

Converts SuperAnnotate annotation formate to the other annotation formats. Currently available (project_type, task) combinations for converter presented below:

From SA to COCO
project_type task
Pixel panoptic_segmentation
Pixel instance_segmentation
Vector instance_segmentation
Vector object_detection
Vector keypoint_detection
Parameters:
  • input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
  • output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
  • dataset_format (str) – One of the formats that are possible to convert. Available candidates are: [“COCO”]
  • dataset_name (str) – Will be used to create json file in the output_dir.
  • project_type (str) – SuperAnnotate project type is either ‘Vector’ or ‘Pixel’ (Default: ‘Vector’) ‘Vector’ project creates <image_name>___objects.json for each image. ‘Pixel’ project creates <image_name>___pixel.jsons and <image_name>___save.png annotation mask for each image.
  • task (str) – Task can be one of the following: [‘panoptic_segmentation’, ‘instance_segmentation’, ‘keypoint_detection’, ‘object_detection’]. (Default: “object_detection”). ‘keypoint_detection’ can be used to converts keypoints from/to available annotation format. ‘panoptic_segmentation’ will use panoptic mask for each image to generate bluemask for SuperAnnotate annotation format and use bluemask to generate panoptic mask for invert conversion. Panoptic masks should be in the input folder. ‘instance_segmentation’ ‘Pixel’ project_type converts instance masks and ‘Vector’ project_type generates bounding boxes and polygons from instance masks. Masks should be in the input folder if it is ‘Pixel’ project_type. ‘object_detection’ converts objects from/to available annotation format
superannotate.convert_project_type(input_dir, output_dir)

Converts SuperAnnotate ‘Vector’ project type to ‘Pixel’ or reverse.

Parameters:
  • input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
  • output_dir (Pathlike(str or Path)) – Path to the folder where you want to have converted files.
superannotate.coco_split_dataset(coco_json_path, image_dir, output_dir, dataset_list_name, ratio_list)

Splits COCO dataset to few datsets.

Parameters:
  • coco_json_path (str or Pathlike) – Path to main COCO JSON dataset, which should be splitted.
  • image_dir – Path to all images in the original dataset.
  • coco_json_path – Path to the folder where you want to output splitted COCO JSON files.
  • dataset_list_name (list) – List of dataset names.
  • ratio_list (list) – List of ratios for each splitted dataset.
superannotate.convert_json_version(input_dir, output_dir, version=2)

Converts SuperAnnotate JSON versions. Newest JSON version is 2.

Parameters:
  • input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
  • output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
  • version (int) – Output version number. Currently is either 1 or 2. Default value is 2. It will upgrade version 1 to version 2. Set 1 to degrade from version 2 to version 1.
Returns:

List of converted files
Return type:

list

Working with annotations

superannotate.add_annotation_bbox_to_json(annotation_json, bbox, annotation_class_name, annotation_class_attributes=None, error=None)

Add a bounding box annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • bbox (list of floats) – 4 element list of top-left x,y and bottom-right x, y coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_polygon_to_json(annotation_json, polygon, annotation_class_name, annotation_class_attributes=None, error=None)

Add a polygon annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • polygon (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_polyline_to_json(annotation_json, polyline, annotation_class_name, annotation_class_attributes=None, error=None)

Add a polyline annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • polyline (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_point_to_json(annotation_json, point, annotation_class_name, annotation_class_attributes=None, error=None)

Add a point annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • point (list of floats) – [x,y] list of coordinates
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_ellipse_to_json(annotation_json, ellipse, annotation_class_name, annotation_class_attributes=None, error=None)

Add an ellipse annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • ellipse (list of floats) – [center_x, center_y, r_x, r_y, angle] list of coordinates and rotation angle in degrees around y axis
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_template_to_json(annotation_json, template_points, template_connections, annotation_class_name, annotation_class_attributes=None, error=None)

Add a template annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • template_points (list of floats) – [x1,y1,x2,y2,…] list of coordinates
  • template_connections (list of ints) – [from_id_1,to_id_1,from_id_2,to_id_2,…] list of indexes from -> to. Indexes are based on template_points. E.g., to have x1,y1 to connect to x2,y2 and x1,y1 to connect to x4,y4, need: [1,2,1,4,…]
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_cuboid_to_json(annotation_json, cuboid, annotation_class_name, annotation_class_attributes=None, error=None)

Add a cuboid annotation to SuperAnnotate format annotation JSON

annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • cuboid (list of floats) – [x_front_tl,y_front_tl,x_front_br,y_front_br, x_rear_tl,y_rear_tl,x_rear_br,y_rear_br] list of coordinates of front rectangle and back rectangle, in top-left (tl) and bottom-right (br) format
  • annotation_class_name (str) – annotation class name
  • annotation_class_attributes – list of attributes
  • error (bool) – if not None, marks annotation as error (True) or no-error (False)
superannotate.add_annotation_comment_to_json(annotation_json, comment_text, comment_coords, comment_author, resolved=False)

Add a comment to SuperAnnotate format annotation JSON

Parameters:
  • annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
  • comment_text (str) – comment text
  • comment_coords (list) – [x, y] coords
  • comment_author (str) – comment author email
  • resolved (bool) – comment resolve status
superannotate.aggregate_annotations_as_df(project_root, include_classes_wo_annotations=False, include_comments=False, include_tags=False, verbose=True, folder_names=None)

Aggregate annotations as pandas dataframe from project root.

Parameters:
  • project_root (Pathlike (str or Path)) – export path of the project
  • include_classes_wo_annotations (bool) – enables inclusion of classes info that have no instances in annotations
  • include_comments (bool) – enables inclusion of comments info as commentResolved column
  • include_tags (bool) – enables inclusion of tags info as tag column
  • folder_names ((list of str)) – Aggregate the specified folders from project_root. If None aggregate all folders in the project_root.
Returns:

DataFrame on annotations with columns: “imageName”, “instanceId”, “className”, “attributeGroupName”, “attributeName”, “type”, “error”, “locked”, “visible”, “trackingId”, “probability”, “pointLabels”, “meta” (geometry information as string), “commentResolved”, “classColor”, “groupId”, “imageWidth”, “imageHeight”, “imageStatus”, “imagePinned”, “createdAt”, “creatorRole”, “creationType”, “creatorEmail”, “updatedAt”, “updatorRole”, “updatorEmail”, “tag”, “folderName”
Return type:

pandas DataFrame
superannotate.df_to_annotations(df, output_dir)

Converts and saves pandas DataFrame annotation info (see aggregate_annotations_as_df) in output_dir. The DataFrame should have columns: “imageName”, “className”, “attributeGroupName”, “attributeName”, “type”, “error”, “locked”, “visible”, trackingId”, “probability”, “pointLabels”, “meta”, “commentResolved”, “classColor”, “groupId”

Currently only works for Vector projects.

Parameters:
  • df (pandas.DataFrame) – pandas DataFrame of annotations possibly created by aggregate_annotations_as_df
  • output_dir (str or Pathlike) – output dir for annotations and classes.json
superannotate.filter_annotation_instances(annotations_df, include=None, exclude=None)

Filter annotation instances from project annotations pandas DataFrame.

include and exclude rules should be a list of rules of the following type: [{“className”: “<className>”, “type” : “<bbox, polygon,…>”, “error”: <True or False>, “attributes” : [{“name” : “<attribute_value>”, “groupName” : “<attribute_group_name>”},…]},…]

Parameters:
  • annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
  • include (list of dicts) – include rules
  • exclude (list of dicts) – exclude rules
Returns:

filtered DataFrame
Return type:

pandas.DataFrame
superannotate.filter_images_by_comments(annotations_df, include_unresolved_comments=True, include_resolved_comments=False, include_without_comments=False)

Filter images on comment resolve status and comment existence

Parameters:
  • annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
  • include_unresolved_comments (bool) – include images with unresolved state
  • include_resolved_comments (bool) – include images with resolved state
  • include_without_comments (bool) – include images without any comments
Returns:

filtered image names
Return type:

list of strs
superannotate.filter_images_by_tags(annotations_df, include=None, exclude=None)

Filter images on tags

Parameters:
  • annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
  • include (list of strs) – include images with given tags
  • exclude (list of strs) – exclude images with given tags
Returns:

filtered image names
Return type:

list of strs

Aggregating class/attribute distribution from annotations

superannotate.class_distribution(export_root, project_names, visualize=False)

Aggregate distribution of classes across multiple projects.

Parameters:
  • export_root (Pathlike (str or Path)) – root export path of the projects
  • project_names (list of str) – list of project names to aggregate through
  • visualize (bool) – enables class histogram plot
Returns:

DataFrame on class distribution with columns [“className”, “count”]
Return type:

pandas DataFrame
superannotate.attribute_distribution(export_root, project_names, visualize=False)

Aggregate distribution of attributes across multiple projects.

Parameters:
  • export_root (Pathlike (str or Path)) – root export path of the projects
  • project_names (list of str) – list of project names to aggregate through
  • visulaize – enables attribute histogram plot
Returns:

DataFrame on attribute distribution with columns [“className”, “attributeGroupName”, “attributeName”, “count”]
Return type:

pandas DataFrame

Utility functions

superannotate.dicom_to_rgb_sequence(input_dicom_file, output_dir, output_image_quality='original')

Converts DICOM file to RGB image sequence. Output file format is <input_dicom_file_name_woextension>_<frame_number>.jpg

Parameters:
  • input_dicom_file (str or Pathlike) – path to DICOM file
  • output_dir (str or Pathlike) – path to output directory
  • output_image_quality (str) – output quality “original” or “compressed”
Returns:

paths to output images
Return type:

list of strs
superannotate.consensus(project, folder_names, export_root=None, image_list=None, annot_type='bbox', show_plots=False)

Computes consensus score for each instance of given images that are present in at least 2 of the given projects:

Parameters:
  • project (str) – project name
  • folder_names (list of str) – list of folder names in the project for which the scores will be computed
  • export_root (Pathlike (str or Path)) – root export path of the projects
  • image_list (list) – List of image names from the projects list that must be used. If None, then all images from the projects list will be used. Default: None
  • annot_type (str) – Type of annotation instances to consider. Available candidates are: [“bbox”, “polygon”, “point”]
  • show_plots (bool) – If True, show plots based on results of consensus computation. Default: False
Returns:

Pandas DateFrame with columns (creatorEmail, QA, imageName, instanceId, className, area, attribute, folderName, score)
Return type:

pandas DataFrame
superannotate.benchmark(project, gt_folder, folder_names, export_root=None, image_list=None, annot_type='bbox', show_plots=False)

Computes benchmark score for each instance of given images that are present both gt_project_name project and projects in folder_names list:

Parameters:
  • project (str or dict) – project name or metadata of the project
  • gt_folder (str) – project folder name that contains the ground truth annotations
  • folder_names (list of str) – list of folder names in the project for which the scores will be computed
  • export_root (Pathlike (str or Path)) – root export path of the projects
  • image_list (list) – List of image names from the projects list that must be used. If None, then all images from the projects list will be used. Default: None
  • annot_type (str) – Type of annotation instances to consider. Available candidates are: [“bbox”, “polygon”, “point”]
  • show_plots (bool) – If True, show plots based on results of consensus computation. Default: False
Returns:

Pandas DateFrame with columns (creatorEmail, QA, imageName, instanceId, className, area, attribute, folderName, score)
Return type:

pandas DataFrame