User Guide#

Welcome to the SuperAnnotate Python Software Development Kit (SDK), which enables Python programmers to create software that incorporates services of the platform and effortlessly integrates SuperAnnotate into their AI process.

Contents#

Quickstart#

This introduction provides a quick overview of how to get SuperAnnotate Python SDK up and running on your local machine.

Installation#

SDK is available on PyPI:

pip install superannotate

The package officially supports Python 3.7+ and was tested under Linux and Windows (Anaconda) platforms.

For certain video related functions to work, ffmpeg package needs to be installed. It can be installed on Ubuntu with:

sudo apt-get install ffmpeg

Initialization and authorization#

To use the SDK, you need to create a config file with a team-specific authentication token. The token is available to team admins on the team settings page at https://app.superannotate.com/team.

SAClient can be used with or without arguments#

Without arguments

from superannotate import SAClient

sa_client = SAClient()

Method 1: SA_TOKEN is defined as an environment variable.

Method 2: Generate a default location (~/.superannotate/config.ini) config file. CLI init should be used:

superannotatecli init --token <token>
                      [--logging_level <NOTSET/INFO/DEBUG/WARNING/ERROR/CRITICAL (Default=INFO)>]
                      [--logging_path <Default=/Users/username/.superannotate/logs>]

Arguments provided

Method 1: Use the token as an argument:

from superannotate import SAClient

SAClient(token="<token>")

Method 2: Create a custom config file:

from superannotate import SAClient

sa_client = SAClient(config_path="~/.superannotate/dev-config.ini")

Custom config.ini example:

[DEFAULT]
SA_TOKEN = <token>
LOGGING_LEVEL = DEBUG
LOGGING_PATH = /Users/username/data/superannotate_logs

Creating a project#

To create a new “Vector” project with name “Example Project 1” and description “test”:

project = "Example Project 1"

sa.create_project(project, "test", "Vector")

Uploading images to project#

To upload all images with extensions “jpg” or “png” from the "<local_folder_path>" to the project “Example Project 1”:

sa.upload_images_from_folder_to_project(project, "<local_folder_path>")

See the full argument options for upload_images_from_folder_to_project() here.

For full list of available functions on projects, see.

Note

Python SDK functions that accept project argument will accept both project name or project metadata (returned either by get_project_metadata or search_projects with argument return_metadata=True). If project name is used it should be unique in team’s project list. Using project metadata will give performance improvement.

Working with images#

To download the image one can use:

image = "example_image1.jpg"

sa.download_image(project, image, "<path_to_local_dir>")

To download image annotations:

sa.download_image_annotations(project, image, "<path_to_local_dir>")

Upload back to the platform with:

sa.upload_image_annotations(project, image, "<path_to_json>")

Working with team contributors#

A team contributor can be invited to the team with:

sa.invite_contributors_to_team(emails=["admin@superannotate.com"], admin=False)

Setup Project#

Creating a project#

To create a new “Vector” project with name “Example Project 1” and description “test”:

project = "Example Project 1"

sa.create_project(project, "test", "Vector")

Uploading images to project#

To upload all images with extensions “jpg” or “png” from the "<local_folder_path>" to the project “Example Project 1”:

sa.upload_images_from_folder_to_project(project, "<local_folder_path>")

See the full argument options for upload_images_from_folder_to_project() here.

Note

Creating a folder in a project#

To create a new folder “folder1” in the project “Example Project 1”:

sa.create_folder(project, "folder1")

After that point almost all SDK functions that use project name as argument can point to that folder with slash after the project name, e.g., “Example Project 1/folder1”, in this case.

Note

To upload images to the “folder1” instead of the root of the project:

sa.upload_images_from_folder_to_project(project + "/folder1", "<local_folder_path>")

Working with annotation classes#

An annotation class for a project can be created with SDK’s:

sa.create_annotation_class(project, "Large car", color="#FFFFAA")

To create annotation classes in bulk with SuperAnnotate export format classes.json (documentation at: https://app.superannotate.com/documentation Management Tools -> Project Workflow part):

sa.create_annotation_classes_from_classes_json(project, "<path_to_classes_json>")

All of the annotation classes of a project are downloaded (as classes/classes.json) with download_export along with annotations, but they can also be downloaded separately with:

sa.download_annotation_classes_json(project, "<path_to_local_folder>")

The classes.json file will be downloaded to "<path_to_local_folder>" folder.

Working with annotations#

The SuperAnnotate format annotation JSONs have the general form:

{
    "metadata":{
        "name":"example_image_1.jpg",
        "width":1024,
        "height":683,
        "status":"Completed",
    },
    "instances":[
        {
            "type":"bbox",
            "classId":72274,
            "probability":100,
            "points":{
                "x1":437.16,
                "x2":465.23,
                "y1":341.5,
                "y2":357.09
            },
            "className":"Jake"
        },
        {
            "type":"polygon",
            "classId":72274,
            "probability":100,
            "points":[
                281.98,
                383.75,
                282.55,
            ],
            "className":"Finn"
        }
    ],
}

the “className” fields here will identify the annotation class of an annotation object (polygon, points, etc.). The project you are uploading to should contain annotation class with that name.

To upload annotations to platform:

sa.upload_annotations_from_folder_to_project(project, "<path_to_local_dir>")

This will try uploading to the project all the JSON files in the folder that have "<image_name>.json" postfix. For pixel projects JSON files should be named "<image_name>___pixel.json" and also for each JSON a mask image file should be present with the name "<image_name>___save.png". Image with <image_name> should already be present in the project for the upload to work.

Exporting projects#

To export the project annotations we need to prepare the export first:

export = sa.prepare_export(project, include_fuse=True)

We can download the prepared export with:

sa.download_export(project, export, "<local_folder_path>", extract_zip_contents=True)

download_export will wait until the export is finished preparing and download it to the specified folder.

Utilities#

Converting annotation format#

After exporting project annotations (in SuperAnnotate format), it is possible to convert them to other annotation formats:

sa.export_annotation("<input_folder>", "<output_folder>", "<dataset_format>", "<dataset_name>",
"<project_type>", "<task>")

Note

Right now we support only SuperAnnotate annotation format to COCO annotation format conversion, but you can convert from “COCO”, “Pascal VOC”, “DataLoop”, “LabelBox”, “SageMaker”, “Supervisely”, “VGG”, “VoTT” or “YOLO” annotation formats to SuperAnnotate annotation format.

You can find more information annotation format conversion here. We provide some examples in our GitHub repository. In the root folder of our github repository, you can run following commands to do conversions.

from superannotate import export_annotation
from superannotate import import_annotation

 # From SA format to COCO panoptic format
 export_annotation(
    "tests/converter_test/COCO/input/fromSuperAnnotate/cats_dogs_panoptic_segm",
    "tests/converter_test/COCO/output/panoptic",
    "COCO", "panoptic_test", "Pixel","panoptic_segmentation"
 )

 # From COCO keypoints detection format to SA annotation format
 import_annotation(
    "tests/converter_test/COCO/input/toSuperAnnotate/keypoint_detection",
    "tests/converter_test/COCO/output/keypoints",
    "COCO", "person_keypoints_test", "Vector", "keypoint_detection"
 )

 # Pascal VOC annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/VOC/input/fromPascalVOCToSuperAnnotate/VOC2012",
    "tests/converter_test/VOC/output/instances",
    "VOC", "instances_test", "Pixel", "instance_segmentation"
 )

 # YOLO annotation format to SA annotation format
 import_annotation(
   'tests/converter_test/YOLO/input/toSuperAnnotate',
   'tests/converter_test/YOLO/output',
   'YOLO', '', 'Vector', 'object_detection'
   )

 # LabelBox annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/LabelBox/input/toSuperAnnotate/",
    "tests/converter_test/LabelBox/output/objects/",
    "LabelBox", "labelbox_example", "Vector", "object_detection"
 )

 # Supervisely annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/Supervisely/input/toSuperAnnotate",
    "tests/converter_test/Supervisely/output",
    "Supervisely", "", "Vector", "vector_annotation"
 )

 # DataLoop annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/DataLoop/input/toSuperAnnotate",
    "tests/converter_test/DataLoop/output",
    "DataLoop", "", "Vector", "vector_annotation"
 )

 # VGG annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/VGG/input/toSuperAnnotate",
    "tests/converter_test/VGG/output",
    "VGG", "vgg_test", "Vector", "instance_segmentation"
 )

 # VoTT annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/VoTT/input/toSuperAnnotate",
    "tests/converter_test/VoTT/output",
    "VoTT", "", "Vector", "vector_annotation"
 )

 # GoogleCloud annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/GoogleCloud/input/toSuperAnnotate",
    "tests/converter_test/GoogleCloud/output",
    "GoogleCloud", "image_object_detection", "Vector", "object_detection"
 )

 # GoogleCloud annotation format to SA annotation format
 import_annotation(
    "tests/converter_test/SageMaker/input/toSuperAnnotate",
    "tests/converter_test/SageMaker/output",
    "SageMaker", "test-obj-detect", "Vector", "object_detection"
 )

pandas DataFrame out of project annotations and annotation instance filtering#

To create a pandas DataFrame from project SuperAnnotate format annotations:

df = sa.aggregate_annotations_as_df("<path_to_project_folder>")

The created DataFrame will have columns specified at aggregate_annotations_as_df.

Example of created DataFrame:

Each row represents annotation information. One full annotation with multiple attribute groups can be grouped under instanceId field.

API Reference#

Contents#

SAClient interface#

Contents#

Projects#

SAClient.create_project(project_name, project_description, project_type, settings=None, classes=None, workflows=None, instructions_link=None)#

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, Pixel, Video, Document, Tiled, PointCloud, GenAI.
settings (list of dicts) – list of settings objects
classes (list of dicts) – list of class objects
workflows (list of dicts) – list of information for each step
instructions_link (str) – str of instructions URL

Returns:

dict object metadata the new project

Return type:

dict

SAClient.search_projects(name=None, return_metadata=False, include_complete_item_count=False, status=None)#

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
include_complete_item_count (bool) – return projects that have completed items and include the number of completed items in response.
status (str) – search projects via project status

Returns:

project names or metadatas

Return type:

list of strs or dicts

SAClient.clone_project(project_name, from_project, project_description=None, copy_annotation_classes=True, copy_settings=True, copy_workflow=False, 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

SAClient.rename_project(project, new_name)#

Renames the project

Parameters:

project (str) – project name
new_name (str) – project’s new name

SAClient.delete_project(project)#

Deletes the project

Parameters:: project (str) – project name

SAClient.get_project_by_id(project_id)#

Returns the project metadata

Parameters:: project_id (int) – the id of the project
Returns:: project metadata
Return type:: dict

SAClient.set_project_status(project, status)#

Set project status

Parameters:

project (str) – project name

status (str) –

status to set.

Available statuses are:

* NotStarted
* InProgress
* Returned
* Completed
* OnHold

SAClient.get_project_metadata(project, include_annotation_classes=False, include_settings=False, include_workflow=False, include_contributors=False, include_complete_item_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”
include_complete_item_count (bool) – enables project complete item count output under the key “completed_items_count”

Returns:

metadata of project

Return type:

dict

SAClient.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 Path-like (str or Path) objects to upload
annotation_status (str) –
value to set the annotation statuses of the uploaded images Available statuses are:
```
* 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

SAClient.attach_items_from_integrated_storage(project, integration, folder_path=None)#

Link images from integrated external storage to SuperAnnotate.

Parameters:

project (str) – project name or folder path where items should be attached (e.g., “project1/folder1”).
integration (str or dict) – existing integration name or metadata dict to pull items from. Mandatory keys in integration metadata’s dict is “name”.
folder_path (str) – Points to an exact folder/directory within given storage. If None, items are fetched from the root directory.

SAClient.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 Path-like (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.

SAClient.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 or dict) – project name or folder path (e.g., “project1/folder1”)
folder_path (Path-like (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

SAClient.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 (Path-like (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

SAClient.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 (Path-like (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

SAClient.add_contributors_to_project(project, emails, role)#

Add contributors to project.

Parameters:

project (str) – project name
emails (list) – users email
role (str) – user role to apply, one of Admin , Annotator , QA

Returns:

lists of added, skipped contributors of the project

Return type:

tuple (2 members) of lists of strs

SAClient.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

SAClient.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”

SAClient.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 (str or dict) – project name or metadata
new_workflow (list of dicts) – new workflow list of dicts

SAClient.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

Folders#

SAClient.search_folders(project, folder_name=None, status=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
status (str or list of str) –
search folders via status. If None, all folders will be returned.

Available statuses are:
```
* NotStarted
* InProgress
* Completed
* OnHold
```
return_metadata (bool) – return metadata of folders instead of names

Returns:

folder names or metadatas

Return type:

list of strs or dicts

SAClient.set_folder_status(project, folder, status)#

Set folder status

Parameters:

project (str) – project name
folder (str) – folder name

status (str) –

status to set.

Available statuses are:

* NotStarted
* InProgress
* Completed
* OnHold

SAClient.assign_folder(project_name, folder_name, users)#

Assigns folder to users. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

project_name (str or dict) – project name or metadata of the project
folder_name (str) – folder name to assign
users (list of str) – list of user emails

SAClient.unassign_folder(project_name, folder_name)#

Removes assignment of given folder for all assignees. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

project_name (str) – project name
folder_name (str) – folder name to remove assignees

SAClient.get_folder_by_id(project_id, folder_id)#

Returns the folder metadata

Parameters:

project_id (int) – the id of the project
folder_id (int) – the id of the folder

Returns:

folder metadata

Return type:

dict

SAClient.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

SAClient.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

SAClient.delete_folders(project, folder_names)#

Delete folder in project.

Parameters:

project (str) – project name
folder_names (list of strs) – to be deleted folders’ names

Items#

SAClient.query(project, query=None, subset=None)#

Return items that satisfy the given query. Query syntax should be in SuperAnnotate query language(https://doc.superannotate.com/docs/explore-overview).

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
query (str) – SAQuL query string.
subset (str) – subset name. Allows you to query items in a specific subset. To return all the items in the specified subset, set the value of query param to None.

Returns:

queried items’ metadata list

Return type:

list of dicts

SAClient.get_item_by_id(project_id, item_id)#

Returns the item metadata

Parameters:

project_id (int) – the id of the project
item_id (int) – the id of the item

Returns:

item metadata

Return type:

dict

SAClient.search_items(project, name_contains=None, annotation_status=None, annotator_email=None, qa_email=None, recursive=False, include_custom_metadata=False)#

Search items by filtering criteria.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”). If recursive=False=True, then only the project name is required.
name_contains (str) – Returns those items, where the given string is found anywhere within an item’s name. If None, all items returned, in accordance with the recursive=False parameter.
annotation_status (str) –
if not None, filters items by annotation status.

Available statuses are:
```
* NotStarted
* InProgress
* QualityCheck
* Returned
* Completed
* Skipped
```
annotator_email (str) – returns those items’ names that are assigned to the specified annotator. If None, all items are returned. Strict equal.
qa_email (str) – returns those items’ names that are assigned to the specified QA. If None, all items are returned. Strict equal.
recursive (bool) – search in the project’s root and all of its folders. If False search only in the project’s root or given directory.
include_custom_metadata (bool) – include custom metadata that has been attached to an asset.

Returns:

metadata of item

Return type:

list of dicts

Request Example:

client.search_items(
   project="Medical Annotations",
   name_contains="image_1",
   include_custom_metadata=True
)

Response Example:

[
   {
       "name": "image_1.jpeg",
       "path": "Medical Annotations/Study",
       "url": "https://sa-public-files.s3.../image_1.png",
       "annotation_status": "NotStarted",
       "annotator_email": None,
       "qa_email": None,
       "entropy_value": None,
       "createdAt": "2022-02-15T20:46:44.000Z",
       "updatedAt": "2022-02-15T20:46:44.000Z",
       "custom_metadata": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com",
       }
   }
]

SAClient.attach_items(project, attachments, annotation_status='NotStarted')#

Link items from external storage to SuperAnnotate using URLs.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
attachments (path-like (str or Path) or list of dicts) – path to CSV file or list of dicts containing attachments URLs.
annotation_status (str) –
value to set the annotation statuses of the linked items.

Available statuses are:
```
* NotStarted
* InProgress
* QualityCheck
* Returned
* Completed
* Skipped
```

Returns:

uploaded, failed and duplicated item names

Return type:

tuple of list of strs

Example:

client = SAClient()
client.attach_items(
    project="Medical Annotations",
    attachments=[{"name": "item", "url": "https://..."}]
 )

Example of attaching items from custom integration:

client = SAClient()
client.attach_items(
    project="Medical Annotations",
    attachments=[
        {
            "name": "item",
            "url": "https://bucket-name.s3…/example.png"
            "integration": "custom-integration-name"
            }
        ]
)

SAClient.copy_items(source, destination, items=None, include_annotations=True)#

Copy images in bulk between folders in a project

Parameters:

source (str) – project name or folder path to select items from (e.g., “project1/folder1”).
destination (str) – project name (root) or folder path to place copied items.
items (list of str) – names of items to copy. If None, all items from the source directory will be copied.
include_annotations (bool) – enables annotations copy

Returns:

list of skipped item names

Return type:

list of strs

SAClient.move_items(source, destination, items=None)#

Move images in bulk between folders in a project

Parameters:

source (str) – project name or folder path to pick items from (e.g., “project1/folder1”).
destination (str) – project name (root) or folder path to move items to.
items (list of str) – names of items to move. If None, all items from the source directory will be moved.

Returns:

list of skipped item names

Return type:

list of strs

SAClient.delete_items(project, items=None)#

Delete items in a given project.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of str) – to be deleted items’ names. If None, all the items will be deleted

SAClient.assign_items(project, items, user)#

Assigns items to a user. The assignment role, QA or Annotator, will be deduced from the user’s role in the project. The type of the objects` image, video or text will be deduced from the project type. 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”)
items (list of str) – list of items to assign
user (str) – user email

SAClient.unassign_items(project, items)#

Removes assignment of given items for all assignees. 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”)
items (list of str) – list of items to unassign

SAClient.get_item_metadata(project, item_name, include_custom_metadata=False)#

Returns item metadata

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
item_name (str) – item name.
include_custom_metadata (bool) – include custom metadata that has been attached to an asset.

Returns:

metadata of item

Return type:

dict

Request Example:

client.get_item_metadata(
   project="Medical Annotations",
   item_name = "image_1.png",
   include_custom_metadata=True
)

Response Example:

{
   "name": "image_1.jpeg",
   "path": "Medical Annotations/Study",
   "url": "https://sa-public-files.s3.../image_1.png",
   "annotation_status": "NotStarted",
   "annotator_email": None,
   "qa_email": None,
   "entropy_value": None,
   "createdAt": "2022-02-15T20:46:44.000Z",
   "updatedAt": "2022-02-15T20:46:44.000Z",
   "custom_metadata": {
       "study_date": "2021-12-31",
       "patient_id": "62078f8a756ddb2ca9fc9660",
       "patient_sex": "female",
       "medical_specialist": "robertboxer@ms.com",
   }
}

SAClient.set_approval_statuses(project, approval_status, items=None)#

Sets annotation statuses of items

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”).
approval_status (str) –
approval status to set.

Available statuses are:
```
* None
* Approved
* Disapproved
```
items (list of strs) – item names to set the mentioned status for. If None, all the items in the project will be used.

Annotations#

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

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

Parameters:

project (str or dict) – project name or folder path (e.g., “project1/folder1”)
annotations (list of dicts) – list of annotation dictionaries corresponding to SuperAnnotate format
keep_status (bool) – If False, the annotation status will be automatically updated to “InProgress,” otherwise the current status will be kept.

Returns:

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

Return type:

dict

Response Example:

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

SAClient.get_annotations(project, items=None)#

Returns annotations for the given list of items.

Parameters:

project (str or int) – project id or project name or folder path (e.g., “project1/folder1”).
items (list of strs or list of ints) – item names. If None, all the items in the specified directory will be used.

Returns:

list of annotations

Return type:

list of dict

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

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

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”).
path (Path-like (str or Path)) – local directory path where the annotations will be downloaded. If none, the current directory is used.
items (list of str) – list of item names whose annotations will be downloaded (e.g., [“Image_1.jpeg”, “Image_2.jpeg”]). If the value is None, then all the annotations of the given directory will be downloaded.
recursive (bool) – download annotations from the project’s root and all of its folders with the preserved structure. If False download only from the project’s root or given directory.
callback (callable) – a function that allows you to modify each annotation’s dict before downloading. The function receives each annotation as an argument and the returned value will be applied to the download.

Returns:

local path of the downloaded annotations folder.

Return type:

str

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

Returns per frame annotations for the given video.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”).
video (str) – video name
fps (str) – how many frames per second needs to be extracted from the video. Will extract 1 frame per second by default.

Returns:

list of annotation objects

Return type:

list of dicts

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

Sets annotation statuses of items

Parameters:

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

annotation_status (str) –

annotation status to set.

Available statuses are:

* NotStarted
* InProgress
* QualityCheck
* Returned
* Completed
* Skipped

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

SAClient.delete_annotations(project, item_names=None)#

Delete item annotations from a given list of items.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
item_names (list of strs) – item names. If None, all the annotations in the specified directory will be deleted.

SAClient.upload_annotations_from_folder_to_project(project, folder_path, from_s3_bucket=None, recursive_subfolders=False, keep_status=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 or dict) – project name or folder path (e.g., “project1/folder1”)
folder_path (str or dict) – from which folder to upload annotations
from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
recursive_subfolders (bool) – enable recursive subfolder parsing
keep_status (bool) – If False, the annotation status will be automatically updated to “InProgress,” otherwise the current status will be kept.

Returns:

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

Return type:

tuple of list of strs

Annotation Classes#

SAClient.create_annotation_class(project, name, color, attribute_groups=None, class_type='object')#

Create annotation class in project

Parameters:

project (str) – project name
name (str) – name for the class
color (str) – RGB hex color value, e.g., “#F9E0FA”
attribute_groups (list of dicts) –
list of attribute group dicts. The values for the “group_type” key are
```
* radio
* checklist
* checklist
* text
* numeric
* ocr
```
ocr and group_type keys are only available for Vector projects. Mandatory keys for each attribute group are:
```
- "name"
```
class_type (str) – class type. Should be either “object” or “tag”. Document project type can also have “relationship” type of classes.

Returns:

new class metadata

Return type:

dict

Request Example:

attributes_list = [
    {
        "group_type": "radio",
        "name": "Vehicle",
        "attributes": [
           {
               "name": "Car"
           },
           {
               "name": "Track"
           },
           {
               "name": "Bus"
           }
       ],
       "default_value": "Car"
   },
   {
       "group_type": "checklist",
       "name": "Color",
       "attributes": [
           {
               "name": "Yellow"
           },
           {
               "name": "Black"
           },
           {
               "name": "White"
           }
       ],
       "default_value": ["Yellow", "White"]
   },
   {
       "group_type": "text",
       "name": "Timestamp"
   },
   {
       "group_type": "numeric",
       "name": "Description"
   }
]
client.create_annotation_class(
   project="Image Project",
   name="Example Class",
   color="#F9E0FA",
   attribute_groups=attributes_list
)

SAClient.create_annotation_classes_from_classes_json(project, classes_json, from_s3_bucket=False)#

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

Parameters:

project (str) – project name
classes_json (list or Path-like (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

SAClient.search_annotation_classes(project, name_contains=None)#

Searches annotation classes by name_prefix (case-insensitive)

Parameters:

project (str) – project name
name_contains (str) – search string. Returns those classes, where the given string is found anywhere within its name. If None, all annotation classes will be returned.

Returns:

annotation classes of the project

Return type:

list of dicts

SAClient.download_annotation_classes_json(project, folder)#

Downloads project classes.json to folder

Parameters:

project (str) – project name
folder (Path-like (str or Path)) – folder to download to

Returns:

path of the download file

Return type:

str

SAClient.delete_annotation_class(project, annotation_class)#

Deletes annotation class from project

Parameters:

project (str) – project name
annotation_class (str or dict) – annotation class name or metadata

Exports#

SAClient.prepare_export(project, folder_names=None, annotation_statuses=None, include_fuse=False, only_pinned=False, **kwargs)#

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, [“NotStarted”, “InProgress”, “QualityCheck”, “Returned”, “Completed”, “Skipped”] will be chosen 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.
kwargs – Arbitrary kwarg integration_name can be provided which will be used as a storage to store export file

Returns:

metadata object of the prepared export

Return type:

dict

SAClient.download_export(project, export, folder_path, extract_zip_contents=True, to_s3_bucket=None)#

Download prepared export.

Parameters:

project (str) – project name
export (str or dict) – export name
folder_path (Path-like (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 (Bucket object) – AWS S3 bucket to use for download. If None then folder_path is in local filesystem.

SAClient.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

Custom Metadata#

SAClient.create_custom_fields(project, fields)#

Create custom fields for items in a project in addition to built-in metadata. Using this function again with a different schema won’t override the existing fields, but add new ones. Use the upload_custom_values() function to fill them with values for each item.

Parameters:

project (str) – project name (e.g., “project1”)
fields (dict) – dictionary describing the fields and their specifications added to the project. You can see the schema structure <here>.

Returns:

custom fields actual schema of the project

Return type:

dict

Supported Types:

number
field spec	spec value
minimum	any number (int or float)
maximum	any number (int or float)
enum	list of numbers (int or float)

string
field spec	spec value
format	“email” (user@example.com) or “date” (YYYY-MM-DD)
enum	list of strings

custom_fields = {
   "study_date": {
       "type": "string",
       "format": "date"
   },
   "patient_id": {
       "type": "string"
   },
   "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
   },
   "patient_age": {
       "type": "number"
   },
   "medical_specialist": {
       "type": "string",
       "format": "email"
   },
   "duration": {
       "type": "number",
       "minimum": 10
   }
}

client = SAClient()
client.create_custom_fields(
   project="Medical Annotations",
   fields=custom_fields
)

SAClient.get_custom_fields(project)#

Get the schema of the custom fields defined for the project

Parameters:: project (str) – project name (e.g., “project1”)
Returns:: custom fields actual schema of the project
Return type:: dict

Response Example:

{
   "study_date": {
       "type": "string",
       "format": "date"
   },
   "patient_id": {
       "type": "string"
   },
   "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
   },
   "patient_age": {
       "type": "number"
   },
   "medical_specialist": {
       "type": "string",
       "format": "email"
   },
   "duration": {
       "type": "number",
       "minimum": 10
   }
}

SAClient.delete_custom_fields(project, fields)#

Remove custom fields from a project’s custom metadata schema.

Parameters:

project (str) – project name (e.g., “project1”)
fields (list of strs) – list of field names to remove

Returns:

custom fields actual schema of the project

Return type:

dict

Request Example:

client = SAClient()
client.delete_custom_fields(
   project = "Medical Annotations",
   fields = ["duration", patient_age]
)

Response Example:

{
    "study_date": {
       "type": "string",
       "format": "date"
    },
    "patient_id": {
       "type": "string"
    },
    "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
    },
    "medical_specialist": {
       "type": "string",
       "format": "email"
    }
}

SAClient.upload_custom_values(project, items)#

Attach custom metadata to items. SAClient.get_item_metadata(), SAClient.search_items(), SAClient.query() methods will return the item metadata and custom metadata.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of dicts) – list of name-data pairs. The key of each dict indicates an existing item name and the value represents the custom metadata dict. The values for the corresponding keys will be added to an item or will be overridden.

Returns:

dictionary with succeeded and failed item names.

Return type:

dict

Request Example:

client = SAClient()

items_values = [
   {
       "image_1.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com"
       }
   },
   {
       "image_2.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9661",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com"
       }
   },
   {
       "image_3.png": {
           "study_date": "2011-10-05T14:48:00.000Z",
           "patient_": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer"
       }
   }
]

client.upload_custom_values(
   project = "Medical Annotations",
   items = items_values
)

Response Example:

{
   "successful_items_count": 2,
   "failed_items_names": ["image_3.png"]
}

SAClient.delete_custom_values(project, items)#

Remove custom data from items

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of dicts) – list of name-custom data dicts. The key of each dict element indicates an existing item in the project root or folder. The value should be the list of fields to be removed from the given item. Please note, that the function removes pointed metadata from a given item. To delete metadata for all items you should delete it from the custom metadata schema. To override values for existing fields, use SAClient.upload_custom_values()

Request Example:

client.delete_custom_values(
    project = "Medical Annotations",
    items = [
       {"image_1.png": ["study_date", "patient_sex"]},
       {"image_2.png": ["study_date", "patient_sex"]}
    ]
)

Subsets#

SAClient.get_subsets(project)#

Get Subsets

Parameters:: project (str) – project name (e.g., “project1”)
Returns:: subsets’ metadata
Return type:: list of dicts

SAClient.add_items_to_subset(project, subset, items)#

Associates selected items with a given subset. Non-existing subset will be automatically created.

Parameters:

project (str) – project name (e.g., “project1”)
subset (str) – a name of an existing/new subset to associate items with. New subsets will be automatically created.
items (list of dicts) – list of items metadata. Required keys are ‘name’ and ‘path’ if the ‘id’ key is not provided in the dict.

Returns:

dictionary with succeeded, skipped and failed items lists.

Return type:

dict

Request Example:

client = SAClient()

# option 1
queried_items = client.query(
    project="Image Project",
    query="instance(error = true)"
 )

client.add_items_to_subset(
    project="Medical Annotations",
    subset="Brain Study - Disapproved",
    items=queried_items
)
# option 2
items_list = [
    {
        'name': 'image_1.jpeg',
        'path': 'Image Project'
    },
    {
        'name': 'image_2.jpeg',
        'path': 'Image Project/Subfolder A'
    }
]

client.add_items_to_subset(
    project="Image Project",
    subset="Subset Name",
    items=items_list

)

Response Example:

{
    "succeeded": [
        {
            'name': 'image_1.jpeg',
            'path': 'Image Project'
        },
        {
            'name': 'image_2.jpeg',
            'path': 'Image Project/Subfolder A'
        }
    ],
    "failed": [],
    "skipped": []
}

Images#

SAClient.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 (str) – image name
local_dir_path (Path-like (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
include_overlay (bool) – enables overlay 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

SAClient.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 (str) – image name
local_dir_path (Path-like (str or Path)) – local directory path to download to

Returns:

paths of downloaded annotations

Return type:

tuple

SAClient.upload_image_annotations(project, image_name, annotation_json, mask=None, verbose=True, keep_status=False)#

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 (str) – image name
annotation_json (dict or Path-like (str or Path)) – annotations in SuperAnnotate format JSON dict or path to JSON file
mask (BytesIO or Path-like (str or Path)) – BytesIO object or filepath to mask annotation for pixel projects in SuperAnnotate format
verbose (bool) – Turns on verbose output logging during the proces.
keep_status (bool) – If False, the annotation status will be automatically updated to “InProgress,” otherwise the current status will be kept.

SAClient.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 (str) – image name
pin (bool) – sets to pin if True, else unpins image

SAClient.upload_priority_scores(project, scores)#

Upload priority scores for the given list of items.

Parameters:

project (str) – project name or folder path (e.g., “project1/folder1”)
scores (list of dicts) – list of score objects

Returns:

lists of uploaded, skipped items

Return type:

tuple (2 members) of lists of strs

Team#

SAClient.get_team_metadata()#

Returns team metadata

Returns:: team metadata
Return type:: dict

SAClient.get_integrations()#

Get all integrations per team

Returns:: metadata objects of all integrations of the team.
Return type:: list of dicts

SAClient.invite_contributors_to_team(emails, admin=False)#

Invites contributors to the team.

Parameters:

emails (list) – list of contributor emails
admin (bool) – enables admin privileges for the contributor

Returns:

lists of invited, skipped contributors of the team

Return type:

tuple (2 members) of lists of strs

SAClient.search_team_contributors(email=None, first_name=None, last_name=None, return_metadata=True)#

Search for contributors in the team

Parameters:

email (str) – filter by email
first_name (str) – filter by first name
last_name (str) – filter by last name
return_metadata (bool) – return metadata of contributors instead of names

Returns:

metadata of found users

Return type:

list of dicts

Neural Network#

SAClient.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 (dict) – the model that needs to be downloaded
output_dir (str) – the directory in which the files will be saved

Returns:

the metadata of the model

Return type:

dict

SAClient.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:

tuple of two lists, list of images on which the prediction has succeeded and failed respectively

Return type:

tuple

SAClient.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 (int) – 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": "admin@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": "NotStarted",
  "item_count": 123,
  "...": "..."
}

Setting metadata#

Setting metadata example:

{
 "attribute": "FrameRate",
 "value": 3
}

Export metadata#

Export metadata example:

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

Integration metadata#

Integration metadata example:

{
"name": "My S3 Bucket",
"type": "aws",
"root": "test-openseadragon-1212"
 }

Item metadata#

Item metadata example:

{
 "name": "example.jpeg",
 "path": "project/folder_1/meow.jpeg",
 "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
 "annotation_status": "NotStarted",
 "annotator_name": None,
 "qa_name": None,
 "entropy_value": None,
 "createdAt": "2022-02-15T20:46:44.000Z",
 "updatedAt": "2022-02-15T20:46:44.000Z"
  }

Image metadata#

Image metadata example:

{
   "name": "000000000001.jpg",
   "annotation_status": "Completed",
   "prediction_status": "NotStarted",
   "segmentation_status": "NotStarted",
   "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,
   "...": "...",
}

Priority score#

Priority score example:

{
     "name" : "image1.png",
     "priority": 0.567
 }

Attachment#

Attachment example:

{
   "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
   "name": "example.jpeg"
}

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": "admin@superannotate.com",
  "first_name": "First Name",
  "last_name": "Last Name",
  "email": "admin@superannotate.com",
  "user_role": 6
  "...": "...",
}

Annotation JSON helper functions#

Converting annotation format to and from src.superannotate format#

superannotate.import_annotation(input_dir, output_dir, dataset_format='superannotate', 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 format 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, convert_to)#

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.
convert_to (str) – the project type to which the current project should be converted.

Working with annotations#

SAClient.validate_annotations(project_type, annotations_json)#

Validates given annotation JSON.

Parameters:

project_type (str) – The project type Vector, Pixel, Video or Document
annotations_json (Path-like (str or Path)) – path to annotation JSON

Returns:

The success of the validation

Return type:

bool

SAClient.aggregate_annotations_as_df(project_root, project_type, folder_names=None)#

Aggregate annotations as pandas dataframe from project root.

Parameters:

project_root (Path-like (str or Path)) – the export path of the project
project_type (str) – the project type, Vector/Pixel, Video or Document
folder_names (list of Pathlike (str or Path) objects) – Aggregate the specified folders from project_root. If None aggregates all folders in the project_root

Returns:

DataFrame on annotations

Return type:

pandas DataFrame

CLI Reference#

With SuperAnnotate CLI, basic tasks can be accomplished using shell commands:

superannotatecli <command> <--arg1 val1> <--arg2 val2> [--optional_arg3 val3] [--optional_arg4] ...

Available commands#

Initialization and configuration#

To initialize CLI (and SDK) with team token:

superannotatecli init --token <token>
                      [--logging_level <NOTSET/INFO/DEBUG/WARNING/ERROR/CRITICAL (Default=INFO)>]
                      [--logging_path <Default=/Users/username/.superannotate/logs>]

Creating a project#

To create a new project:

superannotatecli create-project --name <project_name> --description <project_description> --type <project_type Vector or Pixel>

Creating a folder in a project#

To create a new folder:

superannotatecli create-folder --project <project_name> --name <folder_name>

Uploading images#

To upload images from folder to project use:

superannotatecli upload-images --project <project_name> --folder <folder_path> [--recursive] [--extensions <extension1>,<extension2>,...]

If optional argument recursive is given then subfolders of <folder_path> are also recursively scanned for available images.

Optional argument extensions accepts comma separated list of image extensions to look for. If the argument is not given then value jpg,jpeg,png,tif,tiff,webp,bmp is assumed.

Attaching image URLs#

To attach image URLs to project use:

superannotatecli attach-image-urls --project <project_name/folder_name> --attachments <csv_path> [--annotation_status <annotation_status>]

Uploading videos#

To upload videos from folder to project use:

superannotatecli upload-videos --project <project_name> --folder <folder_path>
                               [--recursive] [--extensions mp4,avi,mov,webm,flv,mpg,ogg]
                               [--target-fps <float>] [--start-time <float>]
                               [--end-time <float>]

If optional argument recursive is given then subfolders of <folder_path> are also recursively scanned for available videos.

Optional argument extensions accepts comma separated list of image extensions to look for. If the argument is not given then value mp4,avi,mov,webm,flv,mpg,ogg is assumed.

target-fps specifies how many frames per second need to extract from the videos (approximate). If not specified all frames will be uploaded.

start-time specifies time (in seconds) from which to start extracting frames, default is 0.0.

end-time specifies time (in seconds) up to which to extract frames. If it is not specified, then up to end is assumed.

Uploading preannotations#

To upload preannotations from folder to project use:

superannotatecli upload-preannotations --project <project_name> --folder <folder_path>
                                       [--format "COCO" or "SuperAnnotate"]
                                       [--dataset-name "<dataset_name_for_COCO_projects>"]
                                       [--task "<task_type_for_COCO_projects>"]

Optional argument format accepts input annotation format. It can have COCO or SuperAnnotate values. If the argument is not given then SuperAnnotate (the native annotation format) is assumed.

Only when COCO format is specified dataset-name and task arguments are required.

dataset-name specifies JSON filename (without extension) in <folder_path>.

task specifies the COCO task for conversion. Please see import_annotation_format for more details.

Uploading annotations#

To upload annotations from folder to project use:

superannotatecli upload-annotations --project <project_name> --folder <folder_path>
                                    [--format "COCO" or "SuperAnnotate"]
                                    [--dataset-name "<dataset_name_for_COCO_projects>"]
                                    [--task "<task_type_for_COCO_projects>"]

Optional argument format accepts input annotation format. It can have COCO or SuperAnnotate values. If the argument is not given then SuperAnnotate (the native annotation format) is assumed.

Only when COCO format is specified dataset-name and task arguments are required.

dataset-name specifies JSON filename (without extension) in <folder_path>.

task specifies the COCO task for conversion. Please see import_annotation_format for more details.

Exporting projects#

To export project

superannotatecli export-project --project <project_name> --folder <folder_path>
                                [--include-fuse]
                                [--disable-extract-zip-contents]
                                [--annotation-statuses <comma separated list of annotation statuses to export>]

SDK version information#

To show the version of the current SDK installation:

superannotatecli version

History#

All release highlights of this project will be documented in this file.

4.4.20 - April 11, 2024#

Updated

SAClient.get_annotations() added the ability to retrieve data by project/item IDs.

SAClient.upload_images_to_project() fixed an issue with providing two paths with the same image name.

4.4.19 - February 08, 2024#

Updated

SAClient.attach_items() added the ability to attach items from custom integrated storage.

4.4.18 - January 18, 2024#

Updated

Improved error handling.

Removed

dependency from jsonschema.

4.4.17 - December 21, 2023#

Added

SAClient.upload_annotations() added default values to the annotations during the upload.

Updated

Fixed SAClient.search_project() search with special characters.

pandas dependency pandas~=2.0

4.4.16 - November 12, 2023#

Added

SAClient.download_annotations() support for integrated storages.

Updated

Documentation updates

pillow dependency pillow>=9.5,~=10.0.

opencv dependency replaced by opencv-python-headless~=4.7.

pydantic dependency pydantic>=1.10,!=2.0.*.

4.4.15 - August 20, 2023#

Added

Support for relationship class types in the document project.

4.4.14 - August 20, 2023#

Added

New project type support CustomEditor.

Updated

SAClient.get_item_by_id() Fixed.

SAClient.consensus() Deprecation.

4.4.13 - June 04, 2023#

Updated

SAClient.download_annotations() Replaced ___objects.json and ___pixel.json postfixes to .json.

SAClient.set_approval_statuses() Added Document project support.

SAClient.convert_project_type() Added required argument convert_to.

SAClient.import_annotation() Replaced ___objects.json and ___pixel.json postfixes to .json.

SAClient.download_export() Replaced ___objects.json and ___pixel.json postfixes to .json.

Removed

SAClient.convert_json_version() method.

4.4.12 - April 23, 2023#

Updated

SAClient.get_annotations_per_frame() Added interpolation of polygonal and polyline annotations.

Fixed

SAClient.add_contributors_to_project() method.

SAClient.run_prediction() method.

Removed

SAClient.create_project_from_metadata() method.

SAClient.get_project_image_count() method.

4.4.11 - April 2, 2023#

Added

SAClient.set_project_status() method.

SAClient.set_folder_status() method.

Updated

SAClient.create_annotation_class() added OCR type attribute group support in the vector projects.

SAClient.create_annotation_classes_from_classes_json() added OCR type attribute group support in the vector projects.

4.4.10 - March 12, 2023#

Updated

Configuration file creation flow

SAClient.search_projects() method, removed include_complete_image_count argument, use include_complete_item_count instead.

SAClient.get_project_metadata() method, removed include_complete_image_count argument, use include_complete_item_count instead.

SAClient.create_project() method to support classes, workflows and instructions_link.

Fixed

SAClient.clone_project() method to address the issue of FPS mode is not being copied.

Deprecated

SAClient.create_project_from_metadata() method, use SAClient.create_project() instead.

SAClient.get_project_image_count() method, use SAClient.get_project_metadata() instead.

Removed

SAClient.class_distribution() method

SAClient.benchmark() method

4.4.9 - January 29, 2023#

Added

SAClient.set_approval_statuses method function to change the approval status of items (images, audio / videos) in bulk.

Updated

SAClient.convert_project_type method updated from Pixel to Vector converter, added polygon holes handling.

4.4.8 - December 25, 2022#

Added

New project types Tiled, PointCloud, Other.

SAClient.get_project_by_id method to get project metadata by id.

SAClient.get_folder_by_id method to get folder metadata by id.

SAClient.get_item_by_id method to get item metadata by id.

Updated

SAClient.consensus method to compute agreement scores between tag type annotations.

4.4.7 - December 04, 2022#

Updated

SAClient.search_folders method to add a new status argument for searching folders via status.

Schemas for Annotation Classes and Video Annotation to support text and numeric input attribute group types.

Fixed

SAClient.query method to address invalid exceptions.

SAClient.download_export method to address the issue with downloading for Windows OS.

SAClient.attach_items_from_integrated_storage method to address “integration not found” error.

SAClient.aggregate_annotations_as_df method to support files without “___objects” in their naming.

Removed

SAClient.add_annotation_bbox_to_image method, use SAClient.upload_annotations instead.

SAClient.add_annotation_point_to_image method, use SAClient.upload_annotations instead.

SAClient.add_annotation_comment_to_image method, use SAClient.upload_annotations instead.

4.4.6 - November 23, 2022#

Updated

SAClient.aggregate_annotations_as_df method to aggregate “comment” type instances.

SAClient.add_annotation_bbox_to_image, SAClient.add_annotation_point_to_image, SAClient.add_annotation_comment_to_image methods to add deprecation warnings.

Fixed

Special characters are being encoded after annotation upload (Windows)

SAClient.assign_folder method to address the invalid argument name.

SAClient.upload_images_from_folder_to_project method to address uploading of more than 500 items.

SAClient.upload_annotations_from_folder_to_project method to address the issue of a folder size being more than 25,5 MB.

SAClient.download_image method to address the KeyError ‘id’ when include_annotations is set to True.

Removed

SAClient.upload_preannotations_from_folder_to_project method

SAClient.copy_image method

4.4.5 - October 23, 2022#

Added

SAClient.add_items_to_subset method to associate given items with a Subset.

SAClient.upload_annotations method to upload annotations in SA format from the system memory.

Updated

SAClient.upload_annotations_from_folder_to_project & SAClient.upload_image_annotations methods to add keep_status argument to prevent the annotation status from changing to In Progress after the annotation upload.

Item metadata to add a new key for holding the id of an item.

SAClient.upload_preannotations_from_folder_to_project to add a deprecation warning message.

SAClient.copy_image to add a deprecation warning message.

Fixed

SAClient.validate_annotations method.

SAClient.search_items, SAClient.get_item_metadata methods to address defects related to pydantic 1.8.2.

A defect related to editor to address the issue of uploading a tag instance without attributes.

4.4.4 - September 11, 2022#

Updated

Improvements on working with large files.

Fixed

SAClient.upload_annotations_from_folder_to_project() method to address the issue of the disappearing progress bar.

SAClient.run_prediction() method to address the issue of the OCR model.

SAClient.validate_annotations() method to address the issue of missing log messages.

SAClient.create_project_from_metadata() method to address the issue of returning deprecated is_multiselect key.

SAClient.get_annotations() method to address the issue of returning error messages as annotation dicts.

4.4.2, 4.4.3 - August 21, 2022#

Updated

the schema of classes JSON to support new values for the "group_type" key for a given attribute group. "group_type": "radio" | "checklist" | "text" | "numeric".

the schema of video annotation JSON to support instances that have a "tag" type.

Fixed

SAClient.get_annotations() method to address the issue of working with the large projects.

SAClient.get_annotations_per_frame() method to address the issue of throwing an error on small videos when the fps is set to 1.

SAClient.upload_annotations_from_folder_to_project() to address the issue of timestamp values represented in seconds for the "lastAction".

SAClient.download_export() method to address the issue of empty logs.

SAClient.clone_project() method to address the issue of having a corrupted project clone, when the source project has a keypoint workflow.

4.4.1 - July 24, 2022#

Added

SAClient.create_custom_fields() method to create/add new custom fields to a project’s custom field schema.

SAClient.get_custom_fields() method to get a project’s custom field schema.

SAClient.delete_custom_fields() method to remove existing custom fields from a project’s custom field schema.

SAClient.upload_custom_values() method to attach custom field-value pairs to items.

SAClient.delete_custom_values() method to remove custom field-value pairs from items.

Updated

The schema of classes JSON to support the new "default_value" key to set a default attribute(s) for a given attribute group.

SAClient.get_item_metadata() method to add a new input argument include_custom_metadata to return custom metadata in the result items.

SAClient.search_items() method to add a new input argument include_custom_metadata to return custom metadata in the result items.

SAClient.query() method to return custom metadata in the result items.

Fixed

SAClient class to address the system crash that occurs on instantiation via config.json file.

SAClient.query() method to address the issue of not returning more than 50 items.

SAClient.upload_annotations_from_folder_to_project() to address the issue of some fields not being auto populated after the upload is finished.

SAClient.get_folder_metadata(), SAClient.search_folders() to address the issue of transforming the ‘+’ sign in a folder to a whitespace.

Removed

superannotate.assign_images() function. Please use the SAClient.assign_items() method instead.

superannotate.unassign_images() function. Please use the SAClient.unassign_items() method instead.

superannotate.delete_images() function. Please use the SAClient.delete_items() method instead.

4.4.0 - July 03, 2022#

Added

superannotate.SAClient() class to instantiate team-level authentication and inheriting methods to access the back-end.

SAClient.download_annotations() method to download annotations without preparing an Export object.

SAClient.get_subsets() method to get the existing subsets for a given project.

SAClient.assign_items() method to assign items in a given project to annotators or quality specialists.

SAClient.unassign_items() method to remove assignments from items.

SAClient.delete_items() method to delete items in a given project.

Updated

JSON Schema for video annotations to version 1.0.45 to show polygon and polyline annotations.

SAClient.get_annotations_per_frame() method to show polygon and polyline annotations.

SAClient.get_annotations_per_frame() method to pick instances closer to a given frame start instead of the median.

SAClient.query() method to add the subset argument to support querying in a subset.

Fixed

SAClient.set_annotation_statuses() method to address the issue occurring with more than 500 items.

SAClient.get_annotations() method to address the PayloadError occurring with more than 20000 items.

SAClient.get_annotations() method to address the missing 'duration' and 'tags' keys for newly uploaded and unannotated videos.

SAClient.get_annotations_per_frame() method to address missing 'duration' and 'tags' keys for newly uploaded and unannotated videos.

SAClient.get_annotations_per_frame() method to address the wrong classId value for unclassified instances.

Removed

superannotate.init() function. Please instantiate superannotate.SAClient() class to authenticate.

superannotate.set_image_annotation_status() function. Please use the SAClient.set_annotation_statuses() method instead.

superannotate.set_images_annotations_statuses() function. Please use the SAClient.set_annotation_statuses() method instead.

4.3.4 - May 22, 2022#

Updated

JSON Schema for video annotations to version x to reflect point annotations.

superannotate.download_export() function to preserve SA folder structure while downloading to S3 bucket.

superannotate.get_item_metadata() function to have string type values instead of int type for the approval_status key.

superannotate.get_item_metadata() function to change the value for the path key in the item metadata from project/folder/item format to project/folder.

superannotate.get_item_metadata() function to add the is_pinned key in the returned metadata.

superannotate.clone_project() function to have NotStarted project status for the newly created project.

Fixed

superannotate.query() function to address the missing value for the path key.

superannotate.import_annotation() function to address the extension issue with JPEG files while converting from VOC to SA.

superannotate.import_annotation() function to address int type pointlabels in the converted JSON from COCO to SA.

superannotate_get_annotations() & superannotate.add_annotation_comment_to_image() to address the issue with asyncio occurring on Windows.

superannotate.set_image_annotation_status() function add a deprecation warning.

superannotate.set_images_annotation_statuses() function add a deprecation warning.

Removed

share_projects() function.

superannotate.attach_image_urls_to_project() function. Please use the superannotate.attach_items() function instead.

superannotate.attach_document_urls_to_project() function. Please use the superannotate.attach_items() function instead.

superannotate.attach_video_urls_to_project() function. Please use the superannotate.attach_items() function instead.

superannotate.copy_images() function. Please use the superannotate.copy_items() function instead.

superannotate.move_images() function. Please use the superannotate.move_items() function instead.

4.3.3 - May 01 2022#

Added

attach_items() function to link items (images, videos, and documents) from external storages to SuperAnnotate using URLs.

copy_items() function to copy items (images, videos, and documents) in bulk between folders in a project.

move_items() function to move items (images, videos, and documents) in bulk between folders in a project.

set_annotation_statuses() function to change the annotation status of items (images, videos, and documents) in bulk.

Updated

aggregate_annotations_as_df() function now supports Text Projects.

Fixed

validate_annotations() function to accept only numeric type values for the points field.

prepare_export() function to address the issue when the entire project is prepared when a wrong folder name is provided.

search_team_contributors() function to address the error message when email parameter is used.

get_item_metadata() to address the issue with approved/disapproved items.

Removed

get_project_and_folder_metadata() function.

get_image_metadata() function. Please use get_item_metadata() instead.

search_images() function. Please use search_items() instead.

search images_all_folders() function. Please use search_items() instead.

4.3.2 - April 10 2022#

Added

query() function to run SAQuL queries via SDK.

search_items() function to search items by various filtering criteria for all supported project types. search_images() and search_images_all_folders() functions will be deprecated.

get_item_metadata() function to get item metadata for all supported project types. get_image_metadata() will be deprecated.

Updated

search_projects() function to add new parameter that gives an option to filter projects by project status.

get_annotation_per_frame() function to add a unique identifier for each annotation instance.

Fixed

pixel annotations to address the issue with the hex code.

sa.validate_annotations() function to address the incorrect error message.

create_project_from_metadata() function to address the issue with instructions.

Removed

get_image_annotations() function. Please use get_annotations()

upload_images_from_public_urls() function.

4.3.1 - March 20 2022#

Added

get_integrations() to list all existing integrations with cloud storages.

attach_items_from_integrated_storage() to attach items from an integrated cloud storage.

upload_priority_scores() to set priority scores for a given list of items.

Updated

JSON Schema to version 1.0.40 to add instance type differentiation for text annotations and "exclude" key for subtracted polygon instances for image annotations.

validate_annotations() to validate text and image annotations based on JSON schema version 1.0.40.

get_annotations() to get annotation instances based on JSON schema version 1.0.40.

prepare_export() to prepare for the download annotations with based on JSON schema version 1.0.40.

upload_annotations_from_folder_to_project() & upload_preannotations_from_folder_to_project() to handle upload based on JSON schema version 1.0.40.

create_project() to add "status" key in returned metadata.

get_project_metadata() to add "status" key.

create_project_from_project_metadata() to make "description" key not required.

clone_project() to add generic "description".

Fixed

sa.get_annotations_per_frame() to take correct attributes.

sa.get_annotations_per_frame() & get_annotations() to eliminate duplicate instances.

4.3.0 - Feb 27 2022#

Added

get_annotations to load annotations for the list of items.

get_annotations_per_frame to generate frame by frame annotations for the given video.

Updated

get_image_annotations() to reference get_annotations().

create_annotation_class() to add class_type in parameters to specify class type on creation.

create_annotation_classes_from_classes_json() to handle class type in classes JSON.

search_annotation_classes() to return class type in metadata.

upload_annotations_from_folder_to_project() to handle tag annotations.

upload_preannotations_from_folder_to_project() to handle tag annotations.

upload_image_annotations() to handle tag annotations.

validate_annotations() to validate vector annotation schema with tag instances.

aggregate_annotations_as_df() to handle tag annotations in annotations df.

class_distribution() to handle class distribution of tag instances.

upload_images_from_public_urls() for deprecation log.

Fixed

upload_images_from_folder_to_project() to upload images without invalid rotation.

upload-annotations CLI to upload annotations to specified folder.

create_project_from_metadata() to setup image quality and workflow from given metadata.

get_project_metadata() to return information on project contributors.

get_project_metadata() to return number of completed images in project root.

get_project_workflow() to return className in project workflow.

file handler permissions in GColab at import stage of the package.

4.2.9 - Jan 30 2022#

Added

superannotate_schemas as a stand alone package on annotation schemas.

Updated

upload_annotations_from_folder_to_project() to reference the validate_annotations().

upload_videos_from_folder_to_project() to remove code duplications.

clone_project() to set upload state of clone project to initial.

Fixed

validate_annotations() to fix rotated bounding box schema.

Removed

Third party logs from logging mechanism.

4.2.8 - Jan 9 2022#

Added

invite_contributers_to_team() for bulk team invite.

add_contributors_to_project() for bulk project sharing.

Updated

upload_images_from_folder_to_project() for non existing S3 path handling.

upload_annotations_from_folder_to_project() for template name and class processing on template annotation upload.

add_annotation_comment_to_image() for unrecognized author processing.

add_annotation_point_to_image() for valid point addition on empty state.

add_annotation_bbox_to_image() for valid bbox addition on empty state.

add_annotation_comment_to_image() for valid comment addition on empty state.

Fixed

superannotatecli upload_images to accept default list of image extensions.

Removed

invite_contributor_to_team() use invite_contributors_to_team() instead.

4.2.7 - Dec 12 2021#

Added

Logging mechanism.

Updated

Cloning projects with attached URLs.

Improve relation between image status and annotations.

Deprecate functions of zero usage.

Fixed

Small bug fix & enhancements.

4.2.6 - Nov 21 2021#

Added

Validation schemas for annotations.

Dataframe aggregation for video projects.

Fixed

Minor bug fixes and enhancements.

4.2.4 - Nov 2 2021#

Fixed

Minor bug fixes and enhancements.

4.2.3 - Oct 31 2021#

Fixed

Minor bug fixes and enhancements.

4.2.2 - Oct 22 2021#

Fixed

Minor bug fixes and enhancements.

4.2.1 - Oct 13 2021#

Fixed

init functionality.

upload_annotation functionality.

4.2.0 - Oct 10 2021#

Added

delete_annotations() for bulk annotation delete.

Updated

Project/folder limitations.

Fixed

Refactor and major bug fix.

4.1.9 - Sep 22 2021#

Added

Text project support.

4.1.8 - Aug 15 2021#

Added

Video project release.

4.1.7 - Aug 1 2021#

Fixed

Video upload refinements.

4.1.6 - Jul 19 2021#

Added

Training/Test data with folder structure.

Token validation.

Updated

Add success property on mixpanel events.

Fixed

Upload template enhancements.

4.1.5 - Jun 16 2021#

Added

Folder assignment.

Updated

COCO keypoint enhancements.

4.1.4 - May 26 2021#

Added

Mixpanel Integration.

Updated

Image upload enhancements.

Video upload enhancements.

Annotation upload enhancements.

Consensus enhancements.

Image copy/move enhancements.

COCO import/export enhancements.

AWS region enhancements.

4.1.3 - Apr 19 2021#

Added

Folder limitations.

4.1.2 - Apr 1 2021#

Fixed

Video upload to folder.

4.1.1 - Mar 31 2021#

Added

Attach image URLs.

4.1.0 - Mar 22 2021#

Added

Folder structure on platform.

4.0.1 - Mar 15 2021#

Updated

The FPS change during video upload has more stable frame choosing algorithm now.

4.0.0 - Feb 28 2021#

Updated

Improved image storage structure on platform, which requires this upgrade in SDK. This change in platform is backward incompatible with previous versions of SDK.

Changelog not maintained before version 4.0.0.

License#

MIT License#

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SuperAnnotate Python SDK#

Resources#

API Reference and User Guide available on Read the Docs
Platform documentation

Authentication#

from superannotate import SAClient
# by environment variable SA_TOKEN
sa_client = SAClient()
# by token
sa_client = SAClient(token='<team token>')
# by config file
# default path is ~/.superannotate/config.ini
sa_client = SAClient(config_path='~/.superannotate/dev_config.ini')

config.ini example#

[DEFAULT]
SA_TOKEN = <Token>
LOGGING_LEVEL = INFO

Using superannotate#

from superannotate import SAClient


sa_client =SAClient()

project = 'Dogs'

sa_client.create_project(
        project_name=project,
        project_description='Test project generated via SDK',
        project_type='Vector'
    )

sa_client.create_annotation_class(
    project=project,
    name='dog',
    color='#F9E0FA',
    class_type='tag'
)

sa_client.attach_items(
        project=project,
        attachments=[
            {
                'url': 'https://drive.google.com/uc?export=download&id=1ipOrZNSTlPUkI_hnrW9aUD5yULqqq5Vl',
                'name': 'dog.jpeg'
            }
        ]
    )

sa_client.upload_annotations(
        project=project,
        annotations=[
            {
                'metadata': {'name': 'dog.jpeg'},
                'instances': [
                    {'type': 'tag', 'className': 'dog'}
                ]
            }
        ]
    )

sa_client.get_annotations(project=project, items=['dog.jpeg'])

Installation#

SuperAnnotate python SDK is available on PyPI:

pip install superannotate

The package officially supports Python 3.7+ and was tested under Linux and Windows (Anaconda ) platforms.

For more detailed installation steps and package usage please have a look at the tutorial

Supported Features#

search/get/create/clone/update/delete projects
search/get/create/delete folders
assign folders to project contributors
upload items to a project from a local or AWS S3 folder
attach items by URL or from an integrated storage, meanwhile keeping them secure in your cloud provider
get integrated cloud storages
upload annotations (also from local or AWS S3 folder)
delete annotations
set items annotations statuses
get/download/export annotations from a project (also to a local or AWS S3 folder)
invite/search team contributors or add contributors to a specific project
search/get/copy/move items in a project
query items using SA Query Language
define custom metadata for items and upload custom values (query based on your custom metadata)
upload priority scores
get available subsets (sets of segregated items), query items in a subset or add items to a subset
assign or anassign items to project contributors
download an image that has been uploaded to project
search/create/download/delete project annotation classes
search/download models
run predictions
convert annotations from/to COCO format
convert annotation from VOC, SuperVisely, LabelBox, DataLoop, VGG, VoTT, SageMaker, GoogleCloud, YOLO formats
CLI commands for simple tasks

Questions and Issues#

For questions and issues please use this repo’s issue tracker on GitHub or contact support@superannotate.com.