Annotation Management

`list`

Lists all annotations of a specific asset.

Parameters

Name	Type	Description
pagination	`dict`	A dictionary containing the limit of the number of assets to be returned in each page (defaults to 100), and the page cursor for page selection (defaults to the first page)
filters	`dict`	A dictionary containing the filters of the annotations to be returned.
`include_attributes`	`bool`	A flag indicating whether to include the annotation attributes.

Return

A list of msgspec struct containing annotation metadata with the following structure:

PaginationResponse(
    next_page='NjVhYTE0ZDY3YzQ5MThlMTJjYTUyOGRk', 
    prev_page=None, 
    data=[
        Annotation(
            id='annot_e5028bdc-122e-4837-b354-d82b95320b69',
            project_id='proj_cd067221d5a6e4007ccbb4afb5966535', 
            asset_id='asset_6647b58e-86af-460c-9a85-efead830aee8', 
            tag='dog', 
            bound_type='Polygon', 
            bound=[
                [0.42918, 0.45322666666666667], 
                [0.43677999999999995, 0.4579466666666666], 
                [0.43677999999999995, 0.46941333333333335], 
                [0.44236000000000003, 0.4788800000000001], 
                [0.45146, 0.4829333333333333], 
                [0.45754, 0.48696000000000006], 
                [0.48234, 0.4842666666666666], 
                [0.4869, 0.43432000000000004], 
                [0.50514, 0.4302666666666667]
            ], 
            create_date=None,
            ontology_id='ontology_843e486c-58d7-45a7-b722-f4948e204a56',
            attributes=[
                OntologyAttributeValue(
                    id='attri_d0877827-63d6-4794-b520-ef3e0c57ef71',
                    name='Tag Group',
                    value=['person']
                )
            ]
        )
    ]
)

Examples

List all annotations of a specific asset ID:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

project.annotations.list(
  pagination = {
    "limit": 500,
    "page": "NjVhYTE0ZDY3YzQ5MThlMTJjYTUyOGRk"
  },
  filters = {
    "asset_ids": ["asset_6647b58e-86af-460c-9a85-efead830aee8"]
  },
  include_attributes = True
)

List all annotations of a specific asset file name:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

// Get asset by filename
asset = datature.assets.get("image.png")

// Filter annotations by asset id
project.annotations.list(filters = {
    "asset_ids": [asset.id]
  })

`create`

Creates an annotation.

Parameters

Name	Type	Description
`annotation`	`dict`	The metadata of the annotation.

Return

A msgspec struct containing the annotation metadata with the following structure:

[
    Annotation(
        id='annot_a9ff9b21-c0e2-49ff-8a69-773aaf00a6f8',
        project_id='proj_cd067221d5a6e4007ccbb4afb5966535',
        asset_id='asset_f4dcb429-0332-4dd6-a1b4-fee794031ba6',
        tag='boat',
        bound_type='Rectangle',
        create_date=1701927649302,
        bound=[
            [0.2772511848341232, 0.34635416666666663],
            [0.2772511848341232, 0.46875],
            [0.54739336492891, 0.46875],
            [0.54739336492891, 0.34635416666666663]
        ]
    )
]

Examples

Create annotation for a specific asset ID:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

project.annotations.create({
    "bound_type": "Rectangle",
    "bound": [[0.2772511848341232, 0.34635416666666663],
            [0.2772511848341232, 0.46875],
            [0.54739336492891, 0.46875],
            [0.54739336492891, 0.34635416666666663]],
    "asset_id":
        "asset_f4dcb429-0332-4dd6-a1b4-fee794031ba6",
    "tag": "boat"
})

Create annotation for a specific asset file name:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

// Get asset by filename
image_asset = datature.assets.get("image.png")

// Create annotation
datature.annotations.create({
    "bound_type": "Rectangle",
    "bound": [[0.425, 0.49382716049382713], [0.425, 0.6419753086419753],
              [0.6, 0.6419753086419753], [0.6, 0.49382716049382713]],
    "asset_id": image_asset.id,
    "tag": "boat"
})

`get`

Retrieves a specific annotation using the annotation ID.

Parameters

Name	Type	Description
`annotation_id`	`str`	The ID of the annotation.
`include_attributes`	`bool`	A flag indicating whether to include the annotation attributes.

Return

A msgspec struct containing the specific annotation metadata with the following structure:

Annotation(
    id='annot_a9ff9b21-c0e2-49ff-8a69-773aaf00a6f8', 
    project_id='proj_cd067221d5a6e4007ccbb4afb5966535', 
    asset_id='asset_f4dcb429-0332-4dd6-a1b4-fee794031ba6', 
    tag='boat', 
    bound_type='Rectangle',
    create_date=1701927649302,
    bound=[
        [0.2772511848341232, 0.34635416666666663], 
        [0.2772511848341232, 0.46875], 
        [0.54739336492891, 0.46875], 
        [0.54739336492891, 0.34635416666666663]
    ],
    ontology_id='ontology_843e486c-58d7-45a7-b722-f4948e204a56',
    attributes=[
        OntologyAttributeValue(
            id='attri_d0877827-63d6-4794-b520-ef3e0c57ef71',
            name='Tag Group',
            value=['person']
        )
    ]
)

Examples

Retrieve annotation by annotation ID:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
project.annotations.get("asset_6aea3395-9a72-4bb5-9ee0-19248c903c56", include_attributes=True)

`delete`

Deletes a specific annotation from the project.

❗️
Deleted annotations are permanently deleted - This action cannot be undone, so only delete your annotations when you are absolutely sure.

Parameters

Name	Type	Description
`annotation_id`	`str`	The ID of the annotation.

Return

A msgspec struct containing the deleted annotation ID and the deletion status with the following structure:

DeleteResponse(deleted=True, id='annot_8188782f-a86b-4961-9e2a-697509085460')

Examples

Delete annotation with specific annotation ID:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
project.annotations.delete("asset_6aea3395-9a72-4bb5-9ee0-19248c903c56")

Delete first annotation with "dog" tag:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

asset_id = project.assets.get("image.png")
annotation_id = [
    annotation for annotation in project.annotations.list(asset_id)
    if annotation.tag == "dog"
][0].id

project.annotations.delete(annotation_id)

`create_export`

Exports all annotations from the project in a specific annotation format. This creates a download link that you can retrieve using annotations.download_exported_file(), together with the operation id in the return msgspec struct.

Parameters

Name	Type	Description
`export_metadata`	`dict`	A dictionary containing the export format and options.
`background`	`bool`	Signal to complete the annotation export process in the background. Defaults to False.

Return

A msgspec struct containing the operation metadata of the annotation export with the following structure:

Operation(
    id='op_ea10c06e-0e2a-4087-b2cf-1a1c9c42d83d',
    kind='nexus.annotations.export',
    status=OperationStatus(
        overview='Finished',
        message='Operation finished',
        progress=OperationProgress(
            unit='whole operation',
            with_status=OperationProgressWithStatus(
                Queued=0,
                Running=0,
                Finished=1,
                Cancelled=0,
                Errored=0
            )
        )
    ),
    create_date=1701927649302,
    update_date=1701927649302
)

Examples

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

operation = project.annotations.create_export({
  "format": "csv_fourcorner",
  "options": {
    "split_ratio": 0.5,
    "seed": 1337,
    "normalized": True
  }
})
# download file to local folder
download_exported_file(operation.id, "local")

`download_exported_file`

Download the successfully exported annotations from project.annotations.create_export().

Parameters

Name	Type	Description
`op_id`	`str`	The operation ID of the annotation export.
`path`	`str`	The download path for the annotation. Default current path.

Return

A msgspec struct with the download metadata of the annotation export with the following structure:

LocalAnnotations(
    download_path='local',
    file_names=[
        'cd067221d5a6e4007ccbb4afb5966535/train.csv',
        'cd067221d5a6e4007ccbb4afb5966535/validate.csv'
    ]
)

Examples

Retrieve metadata of the exported annotations:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

project.annotations.download_exported_file(
    "op_cf8c538a-bcb5-49a9-82cf-fb0d13b49bb1",
    "local"
)

`create_import_session`

Uploads annotations to the project via supported file formats. For bulk annotation import, we allow the user to add up to 1000 files in one import session. To add the file to the import session, include its file path as an argument when calling the add_path function or include its file bytes and filename as arguments when calling the add_bytes. Once all files have been added, it will initiate the upload process automatically.

Parameters

Name	Type	Description
`background`	`bool`	Signal to complete the annotation process in the background. Defaults to False.

🚧
What the Background means?
If background is set to False, the function will wait for our backend to finish processing the annotations, and the annotations will be immediately visible on Nexus. If set to True, the function will exit after finishing uploading files to our platform. You can use wait_until_done to manage your own logic.

Return

An instance of the ImportSession class, which contains four functions add_path, add_bytes, and wait_until_done.

Examples

Upload annotation file in the CSV 4-corner format (upload does not occur in the background by default):

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

# Import session context manager
# If background is set to True,
# the import session will be processed in the background
import_session = project.annotations.create_import_session(background=True)

with import_session as session:
    # Function 1: add file path
    session.add_path("path/to/annotation1.csv")

    # Function 2: add folder path
    session.add_path("folder/path/to/files")

    # Function 3: or even you can add bytes data
    session.add_bytes(b"bytes/of/file", "filename")

`ImportSession`

The ImportSession class is designed with four methods, add_path, add_bytes, and wait_until_done to support simple and quick batch uploads.

`add_path`

Adds local file based on file_path to an import session. See here for what types of files can be added.

Parameters

Name	Type	Description
file_path	`str`	This file path or folder path should lead to the annotation file you are trying to import.

Examples

Add annotation file in the CSV 4-corner format.

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

import_session = project.annotations.create_import_session()

with import_session as session:
  session.add_path("path/to/annotation1.csv")

Add the whole folder to the import session, the function will determine all supported annotation files.

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")

import_session = project.annotations.create_import_session()

with import_session as session:
  session.add_path("path/to/folder")

`add_bytes`

Adds annotation file bytes to an import session.

Parameters

Name	Type	Description
file_bytes	`bytes`	This file bytes.
filename	`str`	The name of the file and the file extension is required.

Examples

from datature.nexus import Client

with open("path/annotation.csv", "rb") as f:
  file_bytes = f.read()
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")
import_session = project.annotations.create_import_session()

with import_session as session:
  session.add_bytes(file_bytes, "annotation.csv")

`wait_until_done`

Wait for annotations to be committed into Nexus. This function only works when the background is set to True.

from datature.nexus import Client

with open("path/annotation.csv", "rb") as f:
  file_bytes = f.read()
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")
import_session = project.annotations.create_import_session(background=True)

with import_session as session:
  session.add_bytes(file_bytes, "annotation.csv")

import_session.wait_until_done()

`get_logs`

Retrieves the import session log, if no errors occurred, the logs will be empty, otherwise it will provide details.

Return

A list of msgspec structs containing the logs with the following structure:

ImportSessionLog(
  id='annotsess_22f18123-f4e6-411d-9eb4-7a444e49e999', 
  project_id='proj_cd067221d5a6e4007ccbb4afb5966535', 
  logs=[
    ImportSessionLogLogItem(
      timestamp=1700723955761.0, 
      level='Error', 
      message='At test_annotations2.csv:19: Point 259.0, 259.0 is out of bounds.\n\nHint: The asset for this annotation has dimensions 400 x 243 pixels.'
    )]
)

Examples

from datature.nexus import Client

with open("path/annotation.csv", "rb") as f:
  file_bytes = f.read()
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")
import_session = project.annotations.create_import_session()

try:
  with import_session as session:
    session.add_bytes(file_bytes, "annotation.csv")
except:
  import_session.get_logs()

list

Parameters

Return

Examples

create

Parameters

Return

Examples

get

Parameters

Return

Examples

delete

❗️

Parameters

Return

Examples

create_export

Parameters

Return

Examples

download_exported_file

Parameters

Return

Examples

create_import_session

Parameters

🚧What the Background means?

Return

Examples

ImportSession

add_path

Parameters

Examples

add_bytes

Parameters

Examples

wait_until_done

get_logs

Return

Examples

`list`

`create`

`get`

`delete`

`create_export`

`download_exported_file`

`create_import_session`

🚧
What the Background means?

`ImportSession`

`add_path`

`add_bytes`

`wait_until_done`

`get_logs`