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)

`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.

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 accepts a list of strings which means what group those assets belong to, and the background 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 the Background means?
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_idsto 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.

📘
The metadata size that can be attached depends on your price plan. Please reference here for more information!

`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.

Parameters

Name	Type	Description
file_path	`str`	This file path or folder path should lead to the asset file you are trying to upload.
custom_metadata	`dict`	This metadata dictionary should contain the metadata information you want to preserve or add for use on the Nexus platform.
nifti_orientation	`str`	The orientation axis of the NIfTI file, if not provided, will save assets for each axis. [`x`, `y`, `z`]

🚧
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.

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 assets with custom metadata:

from datature.nexus import Client

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

metadata = {
  "capturedAt": 1698402314,
  "latitude": 1.2796709,
  "longitude": 103.8564199
}
with upload_session as session:
  session.add_path("image.png", custom_metadata=metadata)

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.
custom_metadata	`dict`	This metadata dictionary should contain the metadata information you want to preserve or add for use on the Nexus platform.
nifti_orientation	`str`	The orientation axis of the NIfTI file, if not provided, will save assets for each axis. [`x`, `y`, `z`]

🚧
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.

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)

`list_groups`

Retrieve asset statistics of a specific asset group.

Parameters

Name	Type	Description
groups	`List[str] \| None`	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"])

list

Parameters

Return

Examples

get

Return

Examples

update

Parameters

Return

Example

delete

❗️

Parameters

Return

Example

create_upload_session

Parameters

🚧What the Background means?

Return

Example

UploadSession

📘

add_path

Parameters

🚧

Examples

add_bytes

Parameters

🚧

Examples

get_operation_ids

Return

Examples

wait_until_done

Examples

list_groups

Parameters

Return

Examples

`list`

`get`

`update`

`delete`

`create_upload_session`

🚧
What the Background means?

`add_path`

`add_bytes`

`get_operation_ids`

`wait_until_done`

`list_groups`