Projects#

SAClient.create_project(project_name, project_description, project_type, settings=None, classes=None, workflows=None, instructions_link=None, workflow=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, Multimodal.
settings (list of dicts) – list of settings objects
classes (list of dicts) – list of class objects
workflows (list of dicts) – Deprecated
workflow (str) – the name of the workflow already created within the team, which must match exactly. If None, the default “System workflow” workflow will be set.
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) – Deprecated
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) – Deprecated
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=None, 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) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.
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=None, 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) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.
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=None, 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) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.
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=None, 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) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.
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_steps(project, steps)#

Sets project’s steps.

Parameters:

project (str or dict) – project name or metadata
steps (list of dicts) – new workflow list of dicts

Request Example:

sa.set_project_steps(
    project="Medical Annotations",
    steps=[
        {
            "step": 1,
            "className": "Anatomy",
            "tool": 2,
            "attribute": [
                {
                    "attribute": {
                        "name": "Lung",
                        "attribute_group": {"name": "Organs"}
                    }
                }
            ]
        }
    ]
)

SAClient.get_project_steps(project)#

Gets project’s steps.

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

Parameters:: project (str or dict) – project name or metadata
Returns:: project steps
Return type:: list of dicts

Response Example:

[
    {
        "step": 1,
        "className": "Anatomy",
        "tool": 2,
        "attribute": [
            {
                "attribute": {
                    "name": "Lung",
                    "attribute_group": {"name": "Organs"}
                }
            }
        ]
    }
]

SAClient.set_project_workflow(project, new_workflow)#

Deprecated

Parameters:

project (ConstrainedStrValue | dict) –
new_workflow (List[dict]) –

SAClient.get_project_workflow(project)#

Deprecated

Parameters:: project (str | dict) –