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.