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)