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.


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.

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.


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


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.