Asset Management

`list`

Retrieves a list of all assets in the project. To handle large datasets, assets are returned in pages (defaults to 100 assets per page). Page cursors are provided in the results list to easily navigate to the next or previous page.

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 assets to be returned.

Return

A msgspec struct of pagination response with the following structure:

PaginationResponse(
    next_page='T2YAGDY1NWFlNDcyMzZkiMDYwMTQ5N2U2',
    prev_page=None,
    data=[
        Asset(
            id='asset_8208740a-2d9c-46e8-abb9-5777371bdcd3',
            filename='boat180.png',
            project='proj_cd067221d5a6e4007ccbb4afb5966535',
            status='None',
            create_date=1701927649302,
            url='',
            metadata=AssetMetadata(
                file_size=186497,
                mime_type='image/png',
                height=243,
                width=400,
                groups=['main'],
                custom_metadata={'captureAt': '2021-03-10T09:00:00Z'}
            ),
            statistic=AssetAnnotationsStatistic(
                tags_count=[],
                total_annotations=0
            )
        )
    ]
)

Examples

Default listing of assets (shows first 100 assets):

from datature.nexus import Client

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

project.assets.list()

View the next page of results:

from datature.nexus import Client

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

next_page = project.assets.list()["next_page"]

project.assets.list({"page": next_page})

View the previous page of results:

from datature.nexus import Client

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

prev_page = project.assets.list({
    "page": "ZjYzYmJkM2FjN2UxOTA4ZmU0ZjE0Yjk5Mg"}
)["prev_page"]

project.assets.list({"page": prev_page})

List a specific page of assets that returns 2 assets on that page:

from datature.nexus import Client
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")

project.assets.list({
    "limit": 2,
    "page": "ZjYzYmJkM2FjN2UxOTA4ZmU0ZjE0Yjk5Mg"
})

`get`

Retrieves a specific asset using the asset ID or file name. Both the asset ID and file name are unique to each asset, since Nexus does not allow uploads with duplicate file names.

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.

Return

A msgspec struct containing the metadata of one asset with the following structure:

Asset(
    id='asset_8208740a-2d9c-46e8-abb9-5777371bdcd3',
    filename='boat180.png',
    project='proj_cd067221d5a6e4007ccbb4afb5966535',
    status='None',
    create_date=1701927649302,
    url='',
    metadata=AssetMetadata(
        file_size=186497,
        mime_type='image/png',
        height=243,
        width=400,
        groups=['main'],
        custom_metadata={'captureAt': '2021-03-10T09:00:00Z'}
    ),
    statistic=AssetAnnotationsStatistic(
        tags_count=[],
        total_annotations=0
    )
)

Examples

Retrieve asset by asset ID:

from datature.nexus import Client

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

Retrieve asset by file name:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
project.assets.get("image.png")

Download asset by file name:

import wget
from datature.nexus import Client

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

project.assets.get("image.png")["url"]
wget.download(url)

❗️
This method is deprecated and will be removed in a future version. To add metadata to your assets, use the add_custom_metadata() method instead.

`update`

Updates the metadata of a specific asset. Currently, we only support the modification of annotation status of an asset. Click here to view the supported annotation statuses.

🚧
Only single-layered JSON objects are allowed to be uploaded as metadata. Examples of supported metadata types include strings, integers, floats. and boolean values. Nested lists and dictionaries are currently not supported.

Parameters

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.
asset_meta	`dict`	The new metadata of the asset to be updated.

Return

A msgspec struct containing the metadata of one asset with the following structure:

Asset(
    id='asset_f4dcb429-0332-4dd6-a1b4-fee794031ba6',
    project_id='proj_cd067221d5a6e4007ccbb4afb5966535',
    filename='boat194.png',
    status='None',
    create_date=1701927649302,
    url='',
    metadata=AssetMetadata(
        file_size=172676,
        mime_type='image/png',
        height=384,
        width=422,
        groups=['main'],
        custom_metadata={'captureAt': '2021-03-10T09:00:00Z'}
    ),
    statistic=AssetAnnotationsStatistic(
        tags_count=[],
        total_annotations=0
    )
)

Example

from datature.nexus import Client

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

/* Update asset status  */
project.assets.update(
    "asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
    {
        "status": "Annotated"
    }
)

/* Or update the custom metadata */
project.assets.update(
    "asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
    {
        "custom_metadata": {
            "capturedAt": 1698402314,
            "latitude": 1.2796709,
            "longitude": 103.8564199,
        }
    }
)

`delete`

Deletes a specific asset from the project using the asset ID or file name.

❗️
Deleted assets are permanently deleted - all information of the assets, including annotations, will be deleted and cannot be recovered. This action cannot be undone, so only delete your assets when you are absolutely sure.

Parameters

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.

Return

A dictionary containing the deleted asset ID and the deletion status with the following structure.

DeleteResponse(deleted=True, id='asset_8208740a-2d9c-46e8-abb9-5777371bdcd3')

Example

from datature.nexus import Client

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

project.assets.delete("asset_8208740a-2d9c-46e8-abb9-5777371bdcd3")

`create_upload_session`

Creates an upload session to upload or update assets.

The function accepts two parameters, The groups flag accepts a list of strings which means what group those assets belong to, and the background flag accepts a boolean value that indicates whether the process should run in the background. The upload process will autosomally be triggered after finishing the add_path or add_bytesfunctions.

Parameters

Name	Type	Description
groups	`List[str]`	A list of group names to categorize the upload. Default is `["main"]`.
background	`bool`	A flag indicating whether the process should run in the background. Default is False.

🚧
What does the Background flag mean?
If background is set to False, the function will wait for our backend to finish generating the thumbnails, and the assets will be immediately visible on Nexus. If set to True, the function will exit after finishing uploading assets to our platform. You can use wait_until_done or get_operation_ids to manage your own logic.

Return

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

Example

from datature.nexus import Client

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

upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  # add assets path to upload session
  session.add_path(
    "folder/path/to/files",
    custom_metadata={"key": "value"}
  )

  # add bytes path to upload session
  session.add_bytes(
    b"bytes/of/file",
    "filename.jpg",
    custom_metadata={"key": "value"}
  )

UploadSession

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

`add_path`

Adds local file based on file_path to an upload session. You can include the upload of important metadata to the Nexus platform with the custom_metadata field. See here for what types of assets can be added.

📘
To or update add asset metadata, please use the assets.update() function. The metadata size that can be attached depends on your price plan. Please reference here for more information!

Parameters

Name	Type	Description
file_path	`str`	This file path or folder path should lead to the asset file you are trying to upload.
nifti_orientation	`str`	(optional, only applicable for 2D NIfTI assets) The orientation axis of the NIfTI file, if not provided, will save assets for each axis. [`x`, `y`, `z`]

Examples

Adding images (.png, .jpg, .jpeg):

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  session.add_path("image.png")

Adding videos (.mp4):

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  session.add_path("example.mp4")

Adding DICOM files:

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  session.add_path("dicom.dcm")

Adding NIfTI files (all orientations - this uploads 3 files corresponding to the x, y, and z orientations respectively):

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  session.add_path("nifti.nii")

Adding NIfTI files (with specified orientation):

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  # x orientation 
  session.add_path("nifti.nii", nifti_orientation="x")

`add_bytes`

Adds asset file bytes to an upload session, the function is designed for edge devices, they can capture assets from the camera and upload them to Nexus directly.

Parameters

Name	Type	Description
file_bytes	`bytes`	This file bytes.
filename	`str`	The name of the file and the file extension is required.
nifti_orientation	`str`	The orientation axis of the NIfTI file, if not provided, will save assets for each axis. [`x`, `y`, `z`]

📘
To or update add asset metadata, please use the assets.update() function. The metadata size that can be attached depends on your price plan. Please reference here for more information!

Examples

Add file to an upload session with bytes:

from datature.nexus import Client

with open("path/asset.png", "rb") as f:
  file_bytes = f.read()
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"])

with upload_session as session:
  session.add_bytes(file_bytes, "nifti.nii")

`get_operation_ids`

If you want to control the process of operations manually, you can set the background to True and use this function to get the operation IDs. Then call operation.wait_until_done or operation.get to wait for the operations to finish.

Return

A list of operation IDs. Because of some dependency limits, each operation allows a maximum of 5000 assets. So if the total number of assets goes up over 5000, it will return a list of operation IDs.

["op_057963cb-b945-4fff-9d9e-20adaab82ad5"]

Examples

from datature.nexus import Client
  
project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"], background=True)

with upload_session as session:
  	session.add_path('/path/of/folder')
    
op_ids = upload_session.get_operation_ids()

for id in op_ids:
  operation = project.operations.get(id)

`wait_until_done`

Wait for all operations to be done. This function only works when the background is set to True. It functions the same as operation.wait_until_done.

Examples

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"], background=True)

with upload_session as session:
  session.add_path("image.png")

upload_session.wait_until_done()

Manage the process manually.

from datature.nexus import Client
from alive_progress import alive_bar

project = Client("5aa41e8ba........").get_project("proj_b705a........")
upload_session = project.assets.create_upload_session(groups=["main"], background=True)

batch = ["file_path1", "file_path2", "file_path3"]

with alive_bar(
  len(batch), 
  title='Preparing upload assets',
  title_length=25
) as progress_bar, upload_session as session:
  for file_path in batch:
    session.add_path(file_path)
    progress_bar()

operations = upload_session.get_operation_ids()

with alive_bar(
  len(operations), 
  title='Waiting server processing',
  title_length=25
) as progress_bar:
  for op in operations:
    project.operations.wait_until_done(op)
    progress_bar()

Result:

Preparing upload assets   |████████████████████████████████████████| 3/3 [100%] in 1.5s (2.02/s) 
Waiting server processing |████████████████████████████████████████| 1/1 [100%] in 35.5s (0.03/s)

`add_custom_metadata`

Add custom metadata to a specific asset. For video assets, you must specify the frame number.

🚧
Only single-layered JSON objects are allowed to be uploaded as metadata. Examples of supported metadata types include strings, integers, floats. and boolean values. Nested lists and dictionaries are currently not supported.

Parameters

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.
custom_metadata	`dict`	A dictionary of custom metadata to add to the asset. Supported value types are string, int, float, and bool.
frame	`int`	Required frame number for video assets. Optional for image assets.

Return

A msgspec struct containing the added custom metadata with the following structure:

📘
The id field in the AssetParent class is the unique ID of the specific custom metadata field. This can be used in delete_custom_metadata() to delete the custom metadata field.

AssetCustomMetadata(
  parent=AssetParent(
    asset_id="asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
    frame=None,
    id="custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681",
  )
  custom_metadata={"captureAt": "2021-03-10T09:00:00Z"}
)

Examples

Add metadata to an image

from datature.nexus import Client

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

project.assets.add_custom_metadata(
  "asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
  {"captureAt": "2021-03-10T09:00:00Z"}
)

Add metadata to a specific frame of a video

from datature.nexus import Client

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

project.assets.add_custom_metadata(
    "asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
    {"event": "motion_detected"},
    frame=15
)

`get_custom_metadata`

Retrieve custom metadata for a specific asset, including frame-level metadata if the specified asset is a video.

Parameters

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.

Return

A msgspec struct containing the custom metadata of the asset with the following structure:

📘
The id field in the AssetParent class is the unique ID of the specific custom metadata field. This can be used in delete_custom_metadata() to delete the custom metadata field.

AssetCustomMetadatas(
  custom_metadatas=[
    AssetCustomMetadata(
      parent=AssetParent(
        asset_id="asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
        frame=None,
        id="custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681",
      )
      custom_metadata={"captureAt": "2021-03-10T09:00:00Z"}
    ),
    ...
  ]
)

Examples

Get image metadata

from datature.nexus import Client

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

project.assets.get_custom_metadata("image.jpg")

Get video metadata

from datature.nexus import Client

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

project.assets.get_custom_metadata("video.mp4")

`delete_custom_metadata`

Delete custom metadata from a specific asset. This method removes a specific custom metadata entry from an asset. The custom_metadata_id can be obtained from the get_custom_metadata() method.

Parameters

Name	Type	Description
asset_id_or_name	`str`	The ID or file name of the asset as a string.
custom_metadata_id	`str`	The ID of the custom metadata to delete

Return

A dictionary containing the deleted asset ID and the deletion status with the following structure.

DeleteResponse(
  deleted=True,
  id='custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681'
)

Examples

from datature.nexus import Client

project = Client("5aa41e8ba........").get_project("proj_b705a........")
project.assets.delete_custom_metadata(
  "asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
  "custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681",
)

`add_custom_metadata_batch`

Add custom metadata to multiple assets in a single operation.

This method allows you to add custom metadata to multiple assets or frames in a single batch operation, which is more efficient than individual calls. Each item in the batch should specify the target asset (by ID or filename) and a frame number for video assets.

Parameters

Name	Type	Description
custom_metadata_batch	`List[Dict]`	A list of dictionaries, where each dictionary contains: "parent": A dictionary with either `asset_id` or `filename`, and `frame` for video assets `custom_metadata`: A dictionary of metadata key-value pairs. Supported value types are string, int, float, and bool.

Name

Type

Description

custom_metadata_batch

List[Dict]

A list of dictionaries, where each dictionary contains:

"parent": A dictionary with either asset_id or filename, and frame for video assets
custom_metadata: A dictionary of metadata key-value pairs. Supported value types are string, int, float, and bool.

Return

A msgspec struct containing the batch operation response with the following structure:

AssetCustomMetadataBatch(
  custom_metadatas=[
    AssetCustomMetadata(
      parent=AssetParent(
        asset_id="asset_6aea3395-9a72-4bb5-9ee0-19248c903c56",
        frame=None,
        id="custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681",
      )
      custom_metadata={"captureAt": "2021-03-10T09:00:00Z"}
    ),
    ...
  ],
  errors=[]
)

Examples

from datature.nexus import Client

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

# Batch add metadata to multiple assets
batch_data = [
    {
        "parent": {"asset_id": "asset_123", "frame": 5},
        "custom_metadata": {"event": "motion", "confidence": 0.95}
    },
    {
        "parent": {"filename": "image.jpg"},
        "custom_metadata": {"location": "camera_1", "timestamp": "2021-03-10T09:00:00Z"}
    }
]

project.assets.add_custom_metadata_batch(batch_data)

`delete_custom_metadata_batch`

Delete custom metadata from multiple assets in a single operation.

This method allows you to delete multiple custom metadata entries across different assets in a single batch operation. The list of custom_metadata_ids can be obtained from the get_custom_metadata() method for each asset.

Parameters

Name	Type	Description
custom_metadata_ids	`List[str]`	A list of IDs of the custom metadata to delete

Return

A msgspec struct containing the batch deletion response of errors. If the list is empty (indicating all operations are successful), returns an empty response.

DeleteCustomMetadataBatchResponse(
  errors=[]
)

Examples

from datature.nexus import Client

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

# Delete multiple custom metadata entries
metadata_ids = [
    "custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:97a83640-f56d-440c-9095-362de2d12681",
    "custommeta_customMetadata#assetParent:59d4e65e05e7360235526f75698ef3e0:a0d7813c-47c5-4da0-a6e7-4b73f5539cf5",
]
project.assets.delete_custom_metadata_batch(metadata_ids)

`list_groups`

Retrieve asset statistics of a specific asset group.

Parameters

Name	Type	Description
groups	`List[str]`	A string array of asset group names.

Return

A list of msgspec struct of the categorized asset statistics with the following structure:

[
    AssetGroup(
        group='dataset',
        statistic=AssetGroupStatistic(
            total_assets=1,
            annotated_assets=0,
            reviewed_assets=0,
            to_fixed_assets=0,
            completed_assets=0
        )
    ),
    AssetGroup(
        group='main',
        statistic=AssetGroupStatistic(
            total_assets=503,
            annotated_assets=0,
            reviewed_assets=0,
            to_fixed_assets=0,
            completed_assets=0
        )
    )
]

Examples

Retrieving asset statistics from all groups:

from datature.nexus import Client

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

Retrieving asset statistics from groups test and main:

from datature.nexus import Client

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

project.assets.list_groups(["dataset", "main"])