matrice.annotation module#

Module to handle annotation-related operations within a project.

class matrice.annotation.Annotation(session, annotation_id=None, annotation_name=None)[source]#

Bases: object

Initialize an Annotation instance for managing annotation-related operations.

This constructor sets up the Annotation instance using the provided session, and either the annotation_id or annotation_name. If only annotation_name is provided, the class attempts to retrieve the annotation_id based on the name. Similarly, if both annotation_id and annotation_name are given, the method checks for consistency.

Parameters:

  • session (Session) – The session object that manages the connection to the API.

  • annotation_id (str, optional) – The unique identifier for the annotation (default is None).

  • annotation_name (str, optional) – The name of the annotation to fetch if annotation_id is not provided (default is “”).

Raises:

ValueError – If neither annotation_id nor annotation_name is provided, or if there is a mismatch between annotation_id and annotation_name.

project_id#

Identifier for the project to which the annotation belongs.

Type:

str

annotation_id#

Identifier for the annotation, retrieved based on the provided annotation_name if not specified.

Type:

str

annotation_name#

Name of the annotation.

Type:

str

rpc#

The RPC interface from the session for communicating with the API.

Type:

RPC

annotation_details#

Detailed information about the annotation, retrieved during initialization.

Type:

dict

version_status#

The processing status of the latest annotation version.

Type:

str

latest_version#

Identifier of the latest version of the annotation dataset.

Type:

str

last_updated_at#

Timestamp indicating when the annotation was last updated.

Type:

str

project_type#

The type of project associated with the annotation.

Type:

str

Example

>>> session = Session(account_number="account_number", access_key="access_key", secret_key="secret_key")
>>> annotation = Annotation(session, annotation_id="5678",annotation_name="annotation_name")
>>> print(annotation.annotation_name)
>>> print(annotation.version_status)
__init__(session, annotation_id=None, annotation_name=None)[source]#
add_label(labelname)[source]#

Adds a new label for the annotation. The annotation_id and project_id must be set in the class instance.

Parameters:

labelname (str) – The name of the new label.

Returns:

A tuple containing three elements: - dict: The API response confirming the addition of the label, including:

  • _id (str): Unique identifier for the new label.

  • name (str): Name of the label.

  • createdAt (str): Timestamp when the label was created.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Raises:

SystemExit – If the annotation_id is not set.

Example

>>> from pprint import pprint
>>> label_resp, err, msg = annotation.add_label(labelname="Animal")
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(label_resp)
annotate_classification_item(file_id, annotation_item_id, classification_label, labeller, reviewer, status, issues, label_time, review_time)[source]#

Add annotation data to a specific file. The annotation_id and project_id must be set in the class instance.

Parameters:

  • file_id (str) – The ID of the file being annotated.

  • annotation_item_id (str) – The ID of the annotation item.

  • classification_label (dict) –

    The classification label for the item, structured as:

    • _idCategory (str): The ID of the category.

    • categoryName (str): The name of the category.

  • labeller (dict) –

    Information about the labeller, including:

    • _idUser (str): The user ID of the labeller.

    • name (str): Name of the labeller.

  • reviewer (dict) –

    Information about the reviewer, including:

    • _idUser (str): The user ID of the reviewer.

    • name (str): Name of the reviewer.

  • status (str) – The status of the annotation (e.g., “Completed”).

  • issues (str) – Any issues identified during the annotation process.

  • label_time (int) – The time taken to label the item, in seconds.

  • review_time (int) – The time taken to review the item, in seconds.

Returns:

A tuple containing three elements: - dict: The API response confirming the addition of the annotation item. - str or None:

Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> annotation_resp, err, msg = annotation.annotate_classification_item(
...     file_id="file123", annotation_item_id="item456",
...     classification_label={"_idCategory": "cat1", "categoryName": "Dog"},
...     labeller={"_idUser": "user123", "name": "John Doe"},
...     reviewer={"_idUser": "user456", "name": "Jane Doe"},
...     status="Completed", issues="", label_time=120, review_time=30
... )
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(annotation_resp)
create_dataset(is_create_new, old_dataset_version, new_dataset_version, new_version_description)[source]#

Create or update a dataset based on annotation data. The annotation_id and project_id must be set in the class instance.

Parameters:

  • is_create_new (bool) – Whether to create a new dataset version (True) or update an existing one (False).

  • old_dataset_version (str) – The version identifier of the old dataset.

  • new_dataset_version (str) – The version identifier of the new dataset.

  • new_version_description (str) – The description for the new dataset version.

Returns:

A tuple containing three elements: - dict:

The API response confirming the creation or update of the dataset.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> dataset_resp, err, msg = annotation.create_dataset(
...     is_create_new=True, old_dataset_version="v1.0",
...     new_dataset_version="v2.0", new_version_description="Updated Version"
... )
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(dataset_resp)
delete()[source]#

Delete the entire annotation task. The annotation_id and project_id must be set in the class instance.

Returns:

A tuple containing three elements: - dict:

The API response confirming the annotation deletion.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Raises:

SystemExit – If the annotation_id is not set.

Example

>>> from pprint import pprint
>>> delete, err, msg = annotation.delete()
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(delete)
delete_item(annotation_item_id)[source]#

Delete a specific annotation item. The annotation_id and project_id must be set in the class instance.

Parameters:

annotation_item_id (str) – The ID of the annotation item to delete.

Returns:

A tuple containing three elements: - dict: The API response confirming the deletion of the annotation item. - str or None:

Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Raises:

SystemExit – If the annotation_id is not set.

Example

>>> from pprint import pprint
>>> delete_resp, err, msg = annotation.delete_item(annotation_item_id="item123")
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(delete_resp)
get_annotation_files(page_size=10, page_number=0)[source]#

Fetch the files associated with a specific annotation. The annotation_id and project_id must be set in the class instance.

Parameters:

  • page_size (int, optional) – Number of files to retrieve per page (default is 10).

  • page_number (int, optional) – Page number to retrieve (default is 0).

Returns:

A tuple containing three elements: - dict:

The API response with a list of files associated with the annotation.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> files, err, msg = annotation.get_annotation_files(page_size=10, page_number=0)
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(files)
get_categories()[source]#

Fetch categories for a specific annotation by its ID. The annotation_id must be set in the class instance.

Returns:

A tuple containing three elements: - dict:

The API response with details about the categories.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> categories, err, msg = annotation.get_categories()
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(categories)
get_item_history(annotation_item_id)[source]#

Fetch the annotation history for a specific item. The annotation_id and project_id must be set in the class instance.

Parameters:

annotation_item_id (str) – The ID of the annotation item for which history is being fetched.

Returns:

A tuple containing three elements: - dict:

The API response with the annotation history details.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> history, err, msg = annotation.get_annotation_history(annotation_item_id="12345")
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(history)
list_items(page_size=10, page_number=0)[source]#

Retrieve a paginated list of items associated with the annotation. The annotation_id and project_id must be set in the class instance.

Parameters:

  • page_size (int, optional) – The number of items to retrieve per page (default is 10).

  • page_number (int, optional) – The page number to retrieve (default is 0).

Returns:

A tuple containing three elements: - dict:

The API response with the annotation items.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Raises:

SystemExit – If the annotation_id is not set.

Example

>>> from pprint import pprint
>>> items, err, msg = annotation.list_items(page_size=10, page_number=0)
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(items)
refresh()[source]#

Refresh the instance by reinstantiating it with the previous values.

rename(annotation_title)[source]#

Rename the annotation with the specified title. The annotation ID must be set in the class instance.

Parameters:

annotation_title (str) – The new title for the annotation.

Returns:

A tuple containing three elements: - dict:

The API response confirming the annotation title update.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Raises:

SystemExit – If the annotation_id is not set.

Example

>>> from pprint import pprint
>>> rename, err, msg = annotation.rename(annotation_title="New Title")
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(rename)
update_classification_item(file_id, annotation_item_id, updated_classification_label, labeller, reviewer, status, issues, label_time, review_time)[source]#

Update annotation data for a specific file. The annotation_id and project_id must be set in the class instance.

Parameters:

  • file_id (str) – The ID of the file being annotated.

  • annotation_item_id (str) – The ID of the annotation item.

  • updated_classification_label (dict) –

    The updated classification label for the item, structured as:

    • _idCategory (str): The ID of the category.

    • categoryName (str): The name of the category.

  • labeller (dict) –

    Information about the labeller, including:

    • _idUser (str): The user ID of the labeller.

    • name (str): Name of the labeller.

  • reviewer (dict) –

    Information about the reviewer, including:

    • _idUser (str): The user ID of the reviewer.

    • name (str): Name of the reviewer.

  • status (str) – The status of the annotation (e.g., “Completed”).

  • issues (str) – Any issues identified during the annotation process.

  • label_time (int) – The time taken to label the item, in seconds.

  • review_time (int) – The time taken to review the item, in seconds.

Returns:

A tuple containing three elements: - dict:

The API response confirming the update of the annotation item.

  • str or None:

    Error message if an error occurred, None otherwise.

  • str:

    Status message indicating success or failure.

Return type:

tuple

Example

>>> from pprint import pprint
>>> update_resp, err, msg = annotation.update_classification_item(
...     file_id="file123", annotation_item_id="item456",
...     updated_classification_label={"_idCategory": "cat1", "categoryName": "Dog"},
...     labeller={"_idUser": "user123", "name": "John Doe"},
...     reviewer={"_idUser": "user456", "name": "Jane Doe"},
...     status="Completed", issues="", label_time=120, review_time=30
... )
>>> if err:
>>>     pprint(err)
>>> else:
>>>     pprint(update_resp)
On this page
Show Source