API Reference¶
Contents
Remote functions¶
Initialization and authentication¶
-
superannotate.
init
(path_to_config_json)¶ Initializes and authenticates to SuperAnnotate platform using the config file. If not initialized then $HOME/.superannotate/config.json will be used.
Parameters: path_to_config_json (str or Path) – Location to config JSON file
Projects¶
-
superannotate.
search_projects
(name=None, return_metadata=False)¶ 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 images instead of names
Returns: project names or metadatas
Return type: list of strs or dicts
-
superannotate.
create_project
(project_name, project_description, project_type)¶ Create a new project in the team.
Parameters: - project_name (str) – the new project’s name
- project_description (str) – the new project’s description
- project_type (str) – the new project type, Vector or Pixel.
Returns: dict object metadata the new project
Return type: dict
-
superannotate.
create_project_from_metadata
(project_metadata)¶ Create a new project in the team using project metadata object dict. Mandatory keys in project_metadata are “name”, “description” and “type” (Vector or Pixel) Non-mandatory keys: “workflow”, “contributors”, “settings” and “annotation_classes”.
Returns: dict object metadata the new project Return type: dict
-
superannotate.
clone_project
(project_name, from_project, project_description=None, copy_annotation_classes=True, copy_settings=True, copy_workflow=True, copy_contributors=False)¶ Create a new project in the team using annotation classes and settings from from_project.
Parameters: - project_name (str) – new project’s name
- from_project (str or dict) – the name or metadata of the project being used for duplication
- project_description (str) – the new project’s description. If None, from_project’s description will be used
- copy_annotation_classes (bool) – enables copying annotation classes
- copy_settings (bool) – enables copying project settings
- copy_workflow (bool) – enables copying project workflow
- copy_contributors (bool) – enables copying project contributors
Returns: dict object metadata of the new project
Return type: dict
-
superannotate.
delete_project
(project)¶ Deletes the project
Parameters: project (str or dict) – project name or metadata of the project to be deleted
-
superannotate.
rename_project
(project, new_name)¶ Renames the project
Parameters: - project (str or dict) – project name or metadata of the project to be deleted
- new_name (str) – project’s new name
-
superannotate.
get_project_metadata
(project, include_annotation_classes=False, include_settings=False, include_workflow=False, include_contributors=False)¶ Returns project metadata
Parameters: - project (str or dict) – project name or project metadata from previous calls
- include_annotation_classes (bool) – enables project annotation classes output under the key “annotation_classes”
- include_settings (bool) – enables project settings output under the key “settings”
- include_workflow (bool) – enables project workflow output under the key “workflow”
- include_contributors (bool) – enables project contributors output under the key “contributors”
Returns: metadata of project
Return type: dict
-
superannotate.
get_project_image_count
(project)¶ Returns number of images in the project.
Parameters: project (str or dict) – project name or metadata of the project Returns: number of images in the project Return type: int
-
superannotate.
upload_images_to_project
(project, img_paths, annotation_status='NotStarted', from_s3_bucket=None, image_quality_in_editor=None)¶ Uploads all images given in list of path objects in img_paths to the project. Sets status of all the uploaded images to set_status if it is not None.
If an image with existing name already exists in the project it won’t be uploaded, and its path will be appended to the third member of return value of this function.
Parameters: - project (str or dict) – project name or metadata of the project to upload images to
- img_paths (list) – list of Pathlike (str or Path) objects to upload
- annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
- from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded, could-not-upload, existing-images filepaths
Return type: tuple (3 members) of list of strs
-
superannotate.
upload_images_from_public_urls_to_project
(project, img_urls, img_names=None, annotation_status='NotStarted', image_quality_in_editor=None)¶ Uploads all images given in the list of URL strings in img_urls to the project. Sets status of all the uploaded images to annotation_status if it is not None.
Parameters: - project (str or dict) – project name or metadata of the project to upload images to
- img_urls (list) – list of str objects to upload
- img_names (list) – list of str names for each urls in img_url list
- annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type: tuple of list of strs
-
superannotate.
upload_images_from_google_cloud_to_project
(project, google_project, bucket_name, folder_path, annotation_status='NotStarted', image_quality_in_editor=None)¶ Uploads all images present in folder_path at bucket_name in google_project to the project. Sets status of all the uploaded images to set_status if it is not None.
Parameters: - project (str or dict) – project name or metadata of the project to upload images to
- google_project (str) – the project name on google cloud, where the bucket resides
- bucket_name (str) – the name of the bucket where the images are stored
- folder_path (str) – path of the folder on the bucket where the images are stored
- annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type: tuple of list of strs
-
superannotate.
upload_images_from_azure_blob_to_project
(project, container_name, folder_path, annotation_status='NotStarted', image_quality_in_editor=None)¶ Uploads all images present in folder_path at container_name Azure blob storage to the project. Sets status of all the uploaded images to set_status if it is not None.
Parameters: - project (str or dict) – project name or metadata of the project to upload images to
- container_name (str) – container name of the Azure blob storage
- folder_path (str) – path of the folder on the bucket where the images are stored
- annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded images’ urls, uploaded images’ filenames, duplicate images’ filenames and not-uploaded images’ urls
Return type: tuple of list of strs
-
superannotate.
upload_image_to_project
(project, img, image_name=None, annotation_status='NotStarted', from_s3_bucket=None, image_quality_in_editor=None)¶ Uploads image (io.BytesIO() or filepath to image) to project. Sets status of the uploaded image to set_status if it is not None.
Parameters: - project (str or dict) – project name or metadata of the project to upload image to
- img (io.BytesIO() or Pathlike (str or Path)) – image to upload
- image_name (str) – image name to set on platform. If None and img is filepath, image name will be set to filename of the path
- annotation_status (str) – value to set the annotation statuses of the uploaded image NotStarted InProgress QualityCheck Returned Completed Skipped
- from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
-
superannotate.
upload_images_from_folder_to_project
(project, folder_path, extensions=None, annotation_status='NotStarted', from_s3_bucket=None, exclude_file_patterns=None, 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 metadata of the project to upload images_to
- folder_path (Pathlike (str or Path)) – from which folder to upload the images
- extensions (list of str) – list of filename extensions to include from folder, if None, then “jpg”, “jpeg”, “png”, “tif”, “tiff”, “webp”, “bmp” are included
- 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 of strs) – filename patterns to exclude from uploading, default value is to exclude SuperAnnotate pixel project annotation mask output file pattern. If None, SuperAnnotate related [“___save.png”, “___fuse.png”] will bet set as default exclude_file_patterns.
- recursive_subfolders (bool) – enable recursive subfolder parsing
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded, could-not-upload, existing-images filepaths
Return type: tuple (3 members) of list of strs
-
superannotate.
upload_video_to_project
(project, video_path, target_fps=None, start_time=0.0, end_time=None, annotation_status='NotStarted', image_quality_in_editor=None)¶ Uploads image frames from video to platform. Uploaded images will have names “<video_name>_<frame_no>.jpg”.
Parameters: - project (str or dict) – project name or metadata of the project to upload video frames to
- video_path (Pathlike (str or Path)) – video to upload
- target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded
- start_time (float) – Time (in seconds) from which to start extracting frames
- end_time (float) – Time (in seconds) up to which to extract frames. If None up to end
- annotation_status (str) – value to set the annotation statuses of the uploaded video frames NotStarted InProgress QualityCheck Returned Completed Skipped
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: filenames of uploaded images
Return type: list of strs
-
superannotate.
upload_videos_from_folder_to_project
(project, folder_path, extensions=None, exclude_file_patterns=None, 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 or dict) – project name or metadata of the project to upload videos to
- folder_path (Pathlike (str or Path)) – from which folder to upload the videos
- extensions (list of str) – list of filename extensions to include from folder, if None, then extensions = [“mp4”, “avi”, “mov”, “webm”, “flv”, “mpg”, “ogg”]
- exclude_file_patterns (list of strs) – filename patterns to exclude from uploading
- recursive_subfolders (bool) – enable recursive subfolder parsing
- target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded
- start_time (float) – Time (in seconds) from which to start extracting frames
- end_time (float) – Time (in seconds) up to which to extract frames. If None up to end
- annotation_status (str) – value to set the annotation statuses of the uploaded images NotStarted InProgress QualityCheck Returned Completed Skipped
- image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.
Returns: uploaded and not-uploaded video frame images’ filenames
Return type: tuple of list of strs
-
superannotate.
upload_annotations_from_folder_to_project
(project, folder_path, from_s3_bucket=None, recursive_subfolders=False)¶ Finds and uploads all JSON files in the folder_path as annotations to the project.
The JSON files should follow specific naming convention. For Vector projects they should be named “<image_filename>___objects.json” (e.g., if image is cats.jpg the annotation filename should be cats.jpg___objects.json), for Pixel projects JSON file should be named “<image_filename>___pixel.json” and also second mask image file should be present with the name “<image_name>___save.png”. In both cases image with <image_name> should be already present on the platform.
Existing annotations will be overwritten.
Parameters: - project (str or dict) – project name or metadata of the project to upload annotations to
- folder_path (Pathlike (str or Path)) – from which folder to upload the annotations
- from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
- recursive_subfolders (bool) – enable recursive subfolder parsing
Returns: paths to annotations uploaded, could-not-upload, missing-images
Return type: tuple of list of strs
-
superannotate.
upload_preannotations_from_folder_to_project
(project, folder_path, from_s3_bucket=None, recursive_subfolders=False)¶ Finds and uploads all JSON files in the folder_path as pre-annotations to the project.
The JSON files should follow specific naming convention. For Vector projects they should be named “<image_filename>___objects.json” (e.g., if image is cats.jpg the annotation filename should be cats.jpg___objects.json), for Pixel projects JSON file should be named “<image_filename>___pixel.json” and also second mask image file should be present with the name “<image_name>___save.png”. In both cases image with <image_name> should be already present on the platform.
Existing pre-annotations will be overwritten.
Parameters: - project (str or dict) – project name or metadata of the project to upload pre-annotations to
- folder_path (Pathlike (str or Path)) – from which folder to upload the pre-annotations
- from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem
- recursive_subfolders (bool) – enable recursive subfolder parsing
Returns: paths to pre-annotations uploaded and could-not-upload
Return type: tuple of list of strs
Share project with user.
Parameters: - project (str or dict) – project name or metadata of the project
- user (str or dict) – user email or metadata of the user to share project with
- user_role (str) – user role to apply, one of Admin , Annotator , QA , Customer , Viewer
Unshare (remove) user from project.
Parameters: - project (str or dict) – project name or metadata of the project
- user (str or dict) – user email or metadata of the user to unshare project
-
superannotate.
get_project_settings
(project)¶ Gets project’s settings.
Return value example: [{ “attribute” : “Brightness”, “value” : 10, …},…]
Parameters: project (str or dict) – project name or metadata Returns: project settings Return type: list of dicts
-
superannotate.
set_project_settings
(project, new_settings)¶ Sets project’s settings.
New settings format example: [{ “attribute” : “Brightness”, “value” : 10, …},…]
Parameters: - project (str or dict) – project name or metadata
- new_settings (list of dicts) – new settings list of dicts
Returns: updated part of project’s settings
Return type: list of dicts
-
superannotate.
get_project_default_image_quality_in_editor
(project)¶ Gets project’s default image quality in editor setting.
Parameters: project (str or dict) – project name or metadata Returns: “original” or “compressed” setting value Return type: str
-
superannotate.
set_project_default_image_quality_in_editor
(project, image_quality_in_editor)¶ Sets project’s default image quality in editor setting.
Parameters: - project (str or dict) – project name or metadata
- image_quality_in_editor (str) – new setting value, should be “original” or “compressed”
-
superannotate.
get_project_workflow
(project)¶ Gets project’s workflow.
Return value example: [{ “step” : <step_num>, “className” : <annotation_class>, “tool” : <tool_num>, …},…]
Parameters: project (str or dict) – project name or metadata Returns: project workflow Return type: list of dicts
-
superannotate.
set_project_workflow
(project, new_workflow)¶ Sets project’s workflow.
new_workflow example: [{ “step” : <step_num>, “className” : <annotation_class>, “tool” : <tool_num>, …},…]
Parameters: - project (list of dicts) – project name or metadata
- project – new workflow list of dicts
Returns: updated part of project’s workflow
Return type: list of dicts
Exports¶
-
superannotate.
prepare_export
(project, annotation_statuses=None, include_fuse=False, only_pinned=False)¶ Prepare annotations and classes.json for export. Original and fused images for images with annotations can be included with include_fuse flag.
Parameters: - project (str or dict) – project name or metadata of the project
- annotation_statuses (list of strs) – images with which status to include, if None, [ “InProgress”, “QualityCheck”, “Returned”, “Completed”] will be chose list elements should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
- include_fuse (bool) – enables fuse images in the export
- only_pinned (bool) – enable only pinned output in export. This option disables all other types of output.
Returns: metadata object of the prepared export
Return type: dict
-
superannotate.
download_export
(project, export, folder_path, extract_zip_contents=True, to_s3_bucket=None)¶ Download prepared export.
WARNING: Starting from version 1.9.0 download_export additionally requires
project
as first argument.Parameters: - project (str or dict) – project name or metadata of the project
- export (str or dict) – export name or metadata of the prepared export
- folder_path (Pathlike (str or Path)) – where to download the export
- extract_zip_contents (bool) – if False then a zip file will be downloaded, if True the zip file will be extracted at folder_path
- to_s3_bucket – AWS S3 bucket to use for download. If None then folder_path is in local filesystem.
-
superannotate.
get_exports
(project, return_metadata=False)¶ Get all prepared exports of the project.
Parameters: - project (str or dict) – project name or metadata of the project
- return_metadata (bool) – return metadata of images instead of names
Returns: names or metadata objects of the all prepared exports of the project
Return type: list of strs or dicts
Images¶
-
superannotate.
search_images
(project, image_name_prefix=None, annotation_status=None, return_metadata=False)¶ Search images by name_prefix (case-insensitive) and annotation status
Parameters: - project (str or dict) – project name or metadata of the project
- image_name_prefix (str) – image name prefix for search
- annotation_status (str) – if not None, annotation statuses of images to filter, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
- return_metadata (bool) – return metadata of images instead of names
Returns: metadata of found images or image names
Return type: list of dicts or strs
-
superannotate.
get_image_metadata
(project, image_name)¶ Returns image metadata
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
Returns: metadata of image
Return type: dict
-
superannotate.
get_image_bytes
(project, image_name, variant='original')¶ Returns an io.BytesIO() object of the image. Suitable for creating PIL.Image out of it.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- variant (str) – which resolution to get, can be ‘original’ or ‘lores’ (low resolution)
Returns: io.BytesIO() of the image
Return type: io.BytesIO()
-
superannotate.
download_image
(project, image_name, local_dir_path='.', include_annotations=False, include_fuse=False, include_overlay=False, variant='original')¶ Downloads the image (and annotation if not None) to local_dir_path
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- local_dir_path (Pathlike (str or Path)) – where to download the image
- include_annotations (bool) – enables annotation download with the image
- include_fuse (bool) – enables fuse image download with the image
- variant (str) – which resolution to download, can be ‘original’ or ‘lores’ (low resolution used in web editor)
Returns: paths of downloaded image and annotations if included
Return type: tuple
-
superannotate.
set_image_annotation_status
(project, image_name, annotation_status)¶ Sets the image annotation status
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- annotation_status (str) – annotation status to set, should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
Returns: metadata of the updated image
Return type: dict
-
superannotate.
get_image_annotations
(project, image_name, project_type=None)¶ Get annotations of the image.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
Returns: dict object with following keys: “annotation_json”: dict object of the annotation, “annotation_json_filename”: filename on server, “annotation_mask”: mask (for pixel), “annotation_mask_filename”: mask filename on server
Return type: dict
-
superannotate.
get_image_preannotations
(project, image_name)¶ Get pre-annotations of the image. Only works for “vector” projects.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
Returns: dict object with following keys: “preannotation_json”: dict object of the annotation, “preannotation_json_filename”: filename on server,
Return type: dict
-
superannotate.
download_image_annotations
(project, image_name, local_dir_path)¶ Downloads annotations of the image (JSON and mask if pixel type project) to local_dir_path.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- local_dir_path (Pathlike (str or Path)) – local directory path to download to
Returns: paths of downloaded annotations
Return type: tuple
-
superannotate.
download_image_preannotations
(project, image_name, local_dir_path)¶ Downloads pre-annotations of the image to local_dir_path. Only works for “vector” projects.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- local_dir_path (Pathlike (str or Path)) – local directory path to download to
Returns: paths of downloaded pre-annotations
Return type: tuple
-
superannotate.
upload_image_annotations
(project, image_name, annotation_json, mask=None, verbose=True)¶ Upload annotations from JSON (also mask for pixel annotations) to the image.
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON dict or path to JSON file
- mask (BytesIO or Pathlike (str or Path)) – BytesIO object or filepath to mask annotation for pixel projects in SuperAnnotate format
-
superannotate.
copy_image
(source_project, image_name, destination_project, include_annotations=False, copy_annotation_status=False, copy_pin=False)¶ Copy image to a project. The image’s project is the same as destination project then the name will be changed to <image_name>_(<num>).<image_ext>, where <num> is the next available number deducted from project image list.
Parameters: - source_project (str or dict) – project name or metadata of the project of source project
- image_name – image name
- destination_project (str or dict) – project name or metadata of the project of destination project
- include_annotations (bool) – enables annotations copy
- copy_annotation_status (bool) – enables annotations status copy
- copy_pin (bool) – enables image pin status copy
-
superannotate.
move_image
(source_project, image_name, destination_project, include_annotations=True, copy_annotation_status=True, copy_pin=True)¶ Move image from source_project to destination_project. source_project and destination_project cannot be the same.
Parameters: - source_project (str or dict) – project name or metadata of the project of source project
- image_name – image name
- destination_project (str or dict) – project name or metadata of the project of destination project
- include_annotations (bool) – enables annotations move
- copy_annotation_status (bool) – enables annotations status copy
- copy_pin (bool) – enables image pin status copy
-
superannotate.
pin_image
(project, image_name, pin=True)¶ Pins (or unpins) image
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- pin (bool) – sets to pin if True, else unpins image
-
superannotate.
assign_images
(project, image_names, user)¶ Assigns images to a user. The assignment role, QA or Annotator, will be deduced from the user’s role in the project. With SDK, the user can be assigned to a role in the project with the share_project function.
Parameters: - project (str or dict) – project name or metadata of the project
- image_names (list of str) – list of image names to assign
- user (str) – user email
-
superannotate.
delete_image
(project, image_name)¶ Deletes image
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
-
superannotate.
add_annotation_bbox_to_image
(project, image_name, bbox, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a bounding box annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>” }, “groupName” : “<attribute_group>”} ], … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- bbox (list of floats) – 4 element list of top-left x,y and bottom-right x, y coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_polygon_to_image
(project, image_name, polygon, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a polygon annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- polygon (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_polyline_to_image
(project, image_name, polyline, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a polyline annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- polyline (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_point_to_image
(project, image_name, point, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a point annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- point (list of floats) – [x,y] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_ellipse_to_image
(project, image_name, ellipse, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add an ellipse annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- ellipse (list of floats) – [center_x, center_y, r_x, r_y, angle] list of coordinates and angle
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_template_to_image
(project, image_name, template_points, template_connections, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a template annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- template_points (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- template_connections (list of ints) – [from_id_1,to_id_1,from_id_2,to_id_2,…] list of indexes from -> to. Indexes are based on template_points. E.g., to have x1,y1 to connect to x2,y2 and x1,y1 to connect to x4,y4, need: [1,2,1,4,…]
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_cuboid_to_image
(project, image_name, cuboid, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a cuboid annotation to image annotations
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- cuboid (list of floats) – [x_front_tl,y_front_tl,x_front_br,y_front_br, x_back_tl,y_back_tl,x_back_br,y_back_br] list of coordinates of front rectangle and back rectangle, in top-left and bottom-right format
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_comment_to_image
(project, image_name, comment_text, comment_coords, comment_author, resolved=False)¶ Add a comment to SuperAnnotate format annotation JSON
Parameters: - project (str or dict) – project name or metadata of the project
- image_name – image name
- comment_text (str) – comment text
- comment_coords (list) – [x, y] coords
- comment_author (str) – comment author email
- resolved (bool) – comment resolve status
-
superannotate.
create_fuse_image
(image, classes_json, project_type, in_memory=False, output_overlay=False)¶ Creates fuse for locally located image and annotations
Parameters: - image (list or Pathlike) – path to image
- image_name – annotation classes or path to their JSON
- project_type (str) – project type, “Vector” or “Pixel”
- in_memory (bool) – enables pillow Image return instead of saving the image
Returns: path to created fuse image or pillow Image object if in_memory enabled
Return type: str of PIL.Image
Annotation Classes¶
-
superannotate.
create_annotation_class
(project, name, color, attribute_groups=None)¶ Create annotation class in project
Parameters: - project (str or dict) – project name or metadata of the project
- name (str) – name for the class
- color (str) – RGB hex color value, e.g., “#FFFFAA”
- attribute_groups (list of dicts) – example: [ { “name”: “tall”, “is_multiselect”: 0, “attributes”: [ { “name”: “yes” }, { “name”: “no” } ] }, { “name”: “age”, “is_multiselect”: 0, “attributes”: [ { “name”: “young” }, { “name”: “old” } ] } ]
Returns: new class metadata
Return type: dict
-
superannotate.
create_annotation_classes_from_classes_json
(project, classes_json, from_s3_bucket=None)¶ Creates annotation classes in project from a SuperAnnotate format annotation classes.json.
Parameters: - project (str or dict) – project name or metadata of the project
- classes_json (list or Pathlike (str or Path)) – JSON itself or path to the JSON file
- from_s3_bucket (str) – AWS S3 bucket to use. If None then classes_json is in local filesystem
Returns: list of created annotation class metadatas
Return type: list of dicts
-
superannotate.
get_annotation_class_metadata
(project, annotation_class_name)¶ Returns annotation class metadata
Parameters: - project (str or dict) – project name or metadata of the project
- annotation_class_name (str) – annotation class name
Returns: metadata of annotation class
Return type: dict
-
superannotate.
search_annotation_classes
(project, name_prefix=None)¶ Searches annotation classes by name_prefix (case-insensitive)
Parameters: - project (str or dict) – project name or metadata of the project
- name_prefix (str) – name prefix for search. If None all annotation classes will be returned
Returns: annotation classes of the project
Return type: list of dicts
-
superannotate.
download_annotation_classes_json
(project, folder)¶ Downloads project classes.json to folder
Parameters: - project (str or dict) – project name or metadata of the project
- folder (Pathlike (str or Path)) – folder to download to
Returns: path of the download file
Return type: str
-
superannotate.
delete_annotation_class
(project, annotation_class)¶ Deletes annotation class from project
Parameters: - project (str or dict) – project name or metadata of the project
- project – annotation class name or metadata
Team contributors¶
-
superannotate.
get_team_metadata
()¶ Returns team metadata
Parameters: convert_users_role_to_string (bool) – convert integer team users’ roles to human comprehensible strings Returns: team metadata Return type: dict
-
superannotate.
invite_contributor_to_team
(email, admin=False)¶ Invites a contributor to team
Parameters: - email (str) – email of the contributor
- admin (bool) – enables admin priviledges for the contributor
-
superannotate.
delete_contributor_to_team_invitation
(email)¶ Deletes team contributor invitation
Parameters: email (str) – invitation email
Remote metadata reference¶
Projects metadata¶
Project metadata example:
{
"name": "Example Project test",
"description": "test vector",
"creator_id": "hovnatan@superannotate.com",
"updatedAt": "2020-08-31T05:43:43.118Z",
"createdAt": "2020-08-31T05:43:43.118Z"
"type": "Vector",
"attachment_name": None,
"attachment_path": None,
"entropy_status": 1,
"status": 0,
"...": "..."
}
Export metadata¶
Export metadata example:
{
"name": "Aug 17 2020 15:44 Hovnatan.zip",
"user_id": "hovnatan@gmail.com",
"status": 2,
"createdAt": "2020-08-17T11:44:26.000Z",
"...": "..."
}
Image metadata¶
Image metadata example:
{
"name": "000000000001.jpg",
"annotation_status": "Completed",
"prediction_status": 1,
"segmentation_status": 1,
"annotator_id": None,
"annotator_name": None,
"qa_id": None,
"qa_name": None,
"entropy_value": None,
"approval_status": None,
"createdAt": "2020-08-18T07:30:06.000Z",
"updatedAt": "2020-08-18T07:30:06.000Z"
"is_pinned": 0,
"...": "...",
}
Annotation class metadata¶
Annotation class metadata example:
{
"id": 4444,
"name": "Human",
"color": "#e4542b",
"attribute_groups": [
{
"name": "tall",
"attributes": [
{
"name": "yes"
},
{
"name": "no"
}
]
},
{
"name": "age",
"attributes": [
{
"name": "young"
},
{
"name": "old"
}
]
}
],
"...": "..."
}
Team contributor metadata¶
Team contributor metadata example:
{
"id": "hovnatan@superannotate.com",
"first_name": "Hovnatan",
"last_name": "Karapetyan",
"email": "hovnatan@superannotate.com",
"user_role": 6
"...": "...",
}
Annotation JSON helper functions¶
Converting annotation format to and from SuperAnnotate format¶
-
superannotate.
import_annotation
(input_dir, output_dir, dataset_format, dataset_name='', project_type='Vector', task='object_detection', images_root='', images_extensions=['jpg'])¶ Converts other annotation formats to SuperAnnotate annotation format. Currently available (project_type, task) combinations for converter presented below:
From COCO to SA project_type task Pixel panoptic_segmentation Pixel instance_segmentation Vector instance_segmentation Vector object_detection Vector keypoint_detection From VOC to SA project_type task Pixel instance_segmentation Vector instance_segmentation Vector object_detection From LabelBox to SA project_type task Vector object_detection Vector instance_segmentation Vector vector_annotation Pixel instance_segmentation From DataLoop to SA project_type task Vector object_detection Vector instance_segmentation Vector vector_annotation From Supervisely to SA project_type task Vector object_detection Vector keypoint_detection Vector vector_annotation Vector instance_segmentation Pixel instance_segmentation From VoTT to SA project_type task Vector instance_segmentation Vector object_detection Vector vector_annotation From SageMaker to SA project_type task Pixel instance_segmentation Vector objcet_detection From VGG to SA project_type task Vector instance_segmentation Vector object_detection Vector vector_annotation From GoogleCloud to SA project_type task Vector object_detection From YOLO to SA project_type task Vector object_detection Parameters: - input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
- output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
- dataset_format (str) – Annotation format to convert SuperAnnotate annotation format. Available candidates are: [“COCO”, “VOC”, “LabelBox”, “DataLoop”, “Supervisely”, ‘VGG’, ‘YOLO’, ‘SageMake’, ‘VoTT’, ‘GoogleCloud’]
- dataset_name (str) – Name of the json file in the input_dir, which should be converted.
- project_type (str) – SuperAnnotate project type is either ‘Vector’ or ‘Pixel’ (Default: ‘Vector’) ‘Vector’ project creates <image_name>___objects.json for each image. ‘Pixel’ project creates <image_name>___pixel.jsons and <image_name>___save.png annotation mask for each image.
- task – Task can be one of the following: [‘panoptic_segmentation’, ‘instance_segmentation’, ‘keypoint_detection’, ‘object_detection’, ‘vector_annotation’]. (Default: “object_detection”). ‘keypoint_detection’ can be used to converts keypoints from/to available annotation format. ‘panoptic_segmentation’ will use panoptic mask for each image to generate bluemask for SuperAnnotate annotation format and use bluemask to generate panoptic mask for invert conversion. Panoptic masks should be in the input folder. ‘instance_segmentation’ ‘Pixel’ project_type converts instance masks and ‘Vector’ project_type generates bounding boxes and polygons from instance masks. Masks should be in the input folder if it is ‘Pixel’ project_type. ‘object_detection’ converts objects from/to available annotation format ‘vector_annotation’ can be used to convert all annotations (point, ellipse, circule, cuboid and etc) to SuperAnnotate vector project.
- images_root (str) – Additonal path to images directory in input_dir
- image_extensions (list) – List of image files xtensions in the images_root folder
-
superannotate.
export_annotation
(input_dir, output_dir, dataset_format, dataset_name, project_type='Vector', task='object_detection')¶ Converts SuperAnnotate annotation formate to the other annotation formats. Currently available (project_type, task) combinations for converter presented below:
From SA to COCO project_type task Pixel panoptic_segmentation Pixel instance_segmentation Vector instance_segmentation Vector object_detection Vector keypoint_detection Parameters: - input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
- output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
- dataset_format (str) – One of the formats that are possible to convert. Available candidates are: [“COCO”]
- dataset_name (str) – Will be used to create json file in the output_dir.
- project_type (str) – SuperAnnotate project type is either ‘Vector’ or ‘Pixel’ (Default: ‘Vector’) ‘Vector’ project creates <image_name>___objects.json for each image. ‘Pixel’ project creates <image_name>___pixel.jsons and <image_name>___save.png annotation mask for each image.
- task (str) – Task can be one of the following: [‘panoptic_segmentation’, ‘instance_segmentation’, ‘keypoint_detection’, ‘object_detection’]. (Default: “object_detection”). ‘keypoint_detection’ can be used to converts keypoints from/to available annotation format. ‘panoptic_segmentation’ will use panoptic mask for each image to generate bluemask for SuperAnnotate annotation format and use bluemask to generate panoptic mask for invert conversion. Panoptic masks should be in the input folder. ‘instance_segmentation’ ‘Pixel’ project_type converts instance masks and ‘Vector’ project_type generates bounding boxes and polygons from instance masks. Masks should be in the input folder if it is ‘Pixel’ project_type. ‘object_detection’ converts objects from/to available annotation format
-
superannotate.
convert_project_type
(input_dir, output_dir)¶ Converts SuperAnnotate ‘Vector’ project type to ‘Pixel’ or reverse.
Parameters: - input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
- output_dir (Pathlike(str or Path)) – Path to the folder where you want to have converted files.
-
superannotate.
coco_split_dataset
(coco_json_path, image_dir, output_dir, dataset_list_name, ratio_list)¶ Splits COCO dataset to few datsets.
Parameters: - coco_json_path (str or Pathlike) – Path to main COCO JSON dataset, which should be splitted.
- image_dir – Path to all images in the original dataset.
- coco_json_path – Path to the folder where you want to output splitted COCO JSON files.
- dataset_list_name (list) – List of dataset names.
- ratio_list (list) – List of ratios for each splitted dataset.
-
superannotate.
convert_json_version
(input_dir, output_dir, version=2)¶ Converts SuperAnnotate JSON versions. Newest JSON version is 2.
Parameters: - input_dir (Pathlike(str or Path)) – Path to the dataset folder that you want to convert.
- output_dir (Pathlike(str or Path)) – Path to the folder, where you want to have converted dataset.
- version (int) – Output version number. Currently is either 1 or 2. Default value is 2. It will upgrade version 1 to version 2. Set 1 to degrade from version 2 to version 1.
Returns: List of converted files
Return type: list
Working with annotations¶
-
superannotate.
add_annotation_bbox_to_json
(annotation_json, bbox, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a bounding box annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- bbox (list of floats) – 4 element list of top-left x,y and bottom-right x, y coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_polygon_to_json
(annotation_json, polygon, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a polygon annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- polygon (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_polyline_to_json
(annotation_json, polyline, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a polyline annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- polyline (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_point_to_json
(annotation_json, point, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a point annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- point (list of floats) – [x,y] list of coordinates
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_ellipse_to_json
(annotation_json, ellipse, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add an ellipse annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- ellipse (list of floats) – [center_x, center_y, r_x, r_y, angle] list of coordinates and rotation angle in degrees around y axis
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_template_to_json
(annotation_json, template_points, template_connections, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a template annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- template_points (list of floats) – [x1,y1,x2,y2,…] list of coordinates
- template_connections (list of ints) – [from_id_1,to_id_1,from_id_2,to_id_2,…] list of indexes from -> to. Indexes are based on template_points. E.g., to have x1,y1 to connect to x2,y2 and x1,y1 to connect to x4,y4, need: [1,2,1,4,…]
- annotation_class_name (str) – annotation class name
- annotation_class_attributes (list of 2 element dicts) – list of annotation class attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_cuboid_to_json
(annotation_json, cuboid, annotation_class_name, annotation_class_attributes=None, error=None)¶ Add a cuboid annotation to SuperAnnotate format annotation JSON
annotation_class_attributes has the form [ {“name” : “<attribute_value>”, “groupName” : “<attribute_group>”}, … ]
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- cuboid (list of floats) – [x_front_tl,y_front_tl,x_front_br,y_front_br, x_rear_tl,y_rear_tl,x_rear_br,y_rear_br] list of coordinates of front rectangle and back rectangle, in top-left (tl) and bottom-right (br) format
- annotation_class_name (str) – annotation class name
- annotation_class_attributes – list of attributes
- error (bool) – if not None, marks annotation as error (True) or no-error (False)
-
superannotate.
add_annotation_comment_to_json
(annotation_json, comment_text, comment_coords, comment_author, resolved=False)¶ Add a comment to SuperAnnotate format annotation JSON
Parameters: - annotation_json (dict or Pathlike (str or Path)) – annotations in SuperAnnotate format JSON or filepath to JSON
- comment_text (str) – comment text
- comment_coords (list) – [x, y] coords
- comment_author (str) – comment author email
- resolved (bool) – comment resolve status
-
superannotate.
aggregate_annotations_as_df
(project_root, include_classes_wo_annotations=False, include_comments=False, include_tags=False, verbose=True)¶ Aggregate annotations as pandas dataframe from project root.
Parameters: - project_root (Pathlike (str or Path)) – export path of the project
- include_classes_wo_annotations (bool) – enables inclusion of classes info that have no instances in annotations
- include_comments (bool) – enables inclusion of comments info as commentResolved column
- include_tags (bool) – enables inclusion of tags info as tag column
Returns: DataFrame on annotations with columns: “imageName”, “instanceId”, “className”, “attributeGroupName”, “attributeName”, “type”, “error”, “locked”, “visible”, “trackingId”, “probability”, “pointLabels”, “meta” (geometry information as string), “commentResolved”, “classColor”, “groupId”, “imageWidth”, “imageHeight”, “imageStatus”, “imagePinned”, “createdAt”, “creatorRole”, “creationType”, “creatorEmail”, “updatedAt”, “updatorRole”, “updatorEmail”, “tag”
Return type: pandas DataFrame
-
superannotate.
df_to_annotations
(df, output_dir)¶ Converts and saves pandas DataFrame annotation info (see aggregate_annotations_as_df) in output_dir. The DataFrame should have columns: “imageName”, “className”, “attributeGroupName”, “attributeName”, “type”, “error”, “locked”, “visible”, trackingId”, “probability”, “pointLabels”, “meta”, “commentResolved”, “classColor”, “groupId”
Currently only works for Vector projects.
Parameters: - df (pandas.DataFrame) – pandas DataFrame of annotations possibly created by aggregate_annotations_as_df
- output_dir (str or Pathlike) – output dir for annotations and classes.json
-
superannotate.
filter_annotation_instances
(annotations_df, include=None, exclude=None)¶ Filter annotation instances from project annotations pandas DataFrame.
include and exclude rules should be a list of rules of the following type: [{“className”: “<className>”, “type” : “<bbox, polygon,…>”, “error”: <True or False>, “attributes” : [{“name” : “<attribute_value>”, “groupName” : “<attribute_group_name>”},…]},…]
Parameters: - annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
- include (list of dicts) – include rules
- exclude (list of dicts) – exclude rules
Returns: filtered DataFrame
Return type: pandas.DataFrame
-
superannotate.
filter_images_by_comments
(annotations_df, include_unresolved_comments=True, include_resolved_comments=False, include_without_comments=False)¶ Filter images on comment resolve status and comment existence
Parameters: - annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
- include_unresolved_comments (bool) – include images with unresolved state
- include_resolved_comments (bool) – include images with resolved state
- include_without_comments (bool) – include images without any comments
Returns: filtered image names
Return type: list of strs
Filter images on tags
Parameters: - annotations_df (pandas.DataFrame) – pandas DataFrame of project annotations
- include (list of strs) – include images with given tags
- exclude (list of strs) – exclude images with given tags
Returns: filtered image names
Return type: list of strs
Aggregating class/attribute distribution from annotations¶
-
superannotate.
class_distribution
(export_root, project_names, visualize=False)¶ Aggregate distribution of classes across multiple projects.
Parameters: - export_root (Pathlike (str or Path)) – root export path of the projects
- project_names (list of str) – list of project names to aggregate through
- visualize (bool) – enables class histogram plot
Returns: DataFrame on class distribution with columns [“className”, “count”]
Return type: pandas DataFrame
-
superannotate.
attribute_distribution
(export_root, project_names, visualize=False)¶ Aggregate distribution of attributes across multiple projects.
Parameters: - export_root (Pathlike (str or Path)) – root export path of the projects
- project_names (list of str) – list of project names to aggregate through
- visulaize – enables attribute histogram plot
Returns: DataFrame on attribute distribution with columns [“className”, “attributeGroupName”, “attributeName”, “count”]
Return type: pandas DataFrame
Utility functions¶
-
superannotate.
dicom_to_rgb_sequence
(input_dicom_file, output_dir, output_image_quality='original')¶ Converts DICOM file to RGB image sequence. Output file format is <input_dicom_file_name_woextension>_<frame_number>.jpg
Parameters: - input_dicom_file (str or Pathlike) – path to DICOM file
- output_dir (str or Pathlike) – path to output directory
- output_image_quality (str) – output quality “original” or “compressed”
Returns: paths to output images
Return type: list of strs
-
superannotate.
consensus
(project_names, export_root=None, image_list=None, annot_type='bbox', show_plots=False)¶ Computes consensus score for each instance of given images that are present in at least 2 of the given projects:
Parameters: - project_names (list of str) – list of project names to aggregate through
- export_root (Pathlike (str or Path)) – root export path of the projects
- image_list (list) – List of image names from the projects list that must be used. If None, then all images from the projects list will be used. Default: None
- annot_type (str) – Type of annotation instances to consider. Available candidates are: [“bbox”, “polygon”, “point”]
- show_plots (bool) – If True, show plots based on results of consensus computation. Default: False
-
superannotate.
benchmark
(gt_project_name, project_names, export_root=None, image_list=None, annot_type='bbox', show_plots=False)¶ Computes benchmark score for each instance of given images that are present both gt_project_name project and projects in project_names list:
Parameters: - gt_project_name (str) – Project name that contains the ground truth annotations
- project_names (list of str) – list of project names to aggregate through
- export_root (Pathlike (str or Path)) – root export path of the projects
- image_list (list) – List of image names from the projects list that must be used. If None, then all images from the projects list will be used. Default: None
- annot_type (str) – Type of annotation instances to consider. Available candidates are: [“bbox”, “polygon”, “point”]
- show_plots (bool) – If True, show plots based on results of consensus computation. Default: False