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

Returns

list of skipped image names

Return type

list of strs

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

Returns

list of skipped image names

Return type

list of strs

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

Neural Network

superannotate.delete_model(model)

This function deletes the provided model

Parameters

model (dict) – the model to be deleted

Returns

the metadata of the model that was deleted

Return type

dict

superannotate.download_model(model, output_dir)

Downloads the neural network and related files which are the <model_name>.pth/pkl. <model_name>.json, <model_name>.yaml, classes_mapper.json

Parameters

  • model (str) – the model that needs to be downloaded

  • output_dir (str) – the directiory in which the files will be saved

Returns

the metadata of the model

Return type

dict

superannotate.plot_model_metrics(metric_json_list)

plots the metrics generated by neural network using plotly

Parameters

metric_json_list (list of str) – list of <model_name>.json files

superannotate.run_prediction(project, images_list, model)

This function runs smart prediction on given list of images from a given project using the neural network of your choice

Parameters

  • project (str or dict) – the project in which the target images are uploaded.

  • images_list (list of str) – the list of image names on which smart prediction has to be run

  • model (str or dict) – the name of the model that should be used for running smart prediction

Returns

tupe of two lists, list of images on which the prediction has succeded and failed respectively

Return type

tuple

superannotate.run_segmentation(project, images_list, model)

Starts smart segmentation on a list of images using the specified model

Parameters

project (str or dict) – project name of metadata of the project

:param model : The model name or metadata of the model :type model : str or dict :return: tupe of two lists, list of images on which the prediction has succeded and failed respectively :rtype res: tuple

superannotate.run_training(project, base_model, model_name, model_description, task, hyperparameters, log=False)

Runs neural network training

Parameters

  • project (str, dict or list of dict) – project or list of projects that contain the training images

  • base_model (str or dict) – base model on which the new network will be trained

  • model_name (str) – name of the new model

  • model_description (str) – description of the new model

  • task (str) – The model training task

  • hyperparameters (dict) – hyperparameters that should be used in training

  • log (boolean) – If true will log training metrics in the stdout

Returns

the metadata of the newly created model

Return type

dict

superannotate.stop_model_training(model)

This function will stop training model provided by either name or metadata, and return the ID

Parameters

model (dict) – The name or the metadata of the model the training of which the user needs to terminate

Returns

the metadata of the now, stopped model

Return type

dict

superannotate.search_models(name=None, type_=None, project_id=None, task=None, include_global=True)

Search for ML models.

Parameters

  • name (str) – search string

  • type (str) – ml model type string

  • project_id (str) – project id

  • task (str) – training task

  • include_global (bool) – include global ml models

Returns

ml model metadata

Return type

list of dicts

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