Entities

The datamint.entities module provides the core data structures that represent various objects within the Datamint ecosystem. These entities are built using Pydantic models, ensuring robust data validation, type safety, and seamless serialization/deserialization when interacting with the Datamint API.

In most user code, prefer working with entity instances instead of passing raw IDs between endpoint calls. Project, Resource, and Annotation can usually be passed directly back into API methods, and they expose convenience helpers for common workflows.

Entity-first Workflows

Project objects

from datamint import Api

api = Api()
project = api.projects.get_by_name("Liver Review")

resources = project.fetch_resources()
project.cache_resources(progress_bar=False)

if resources:
   project.set_work_status(resources[0], "annotated")

specs = project.get_annotations_specs()
print([spec.identifier for spec in specs])

Resource objects

resource = api.resources.get_list(project_name="Liver Review")[0]

image = resource.fetch_file_data(auto_convert=True, use_cache=True)
annotations = resource.fetch_annotations(annotation_type="segmentation")

print(resource.filename, len(annotations))

Annotation objects

annotation = resource.fetch_annotations()[0]

annotation_data = annotation.fetch_file_data(use_cache=True)
source_resource = annotation.resource

print(annotation.name, source_resource.filename)

Entity Reference

Base Classes

class datamint.entities.base_entity.BaseEntity(*, id, **data)

Bases: BaseEntityModel

Base class for all entities in the Datamint system.

This class provides common functionality for all entities, such as serialization and deserialization from dictionaries, as well as handling unknown fields gracefully.

The API client is automatically injected by the Api class when entities are created through API endpoints.

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

class datamint.entities.base_entity.BaseEntityModel(*, id, **data)

Bases: BaseModel

Shared lightweight Pydantic base for Datamint entities and DTOs.

asdict()

Convert the entity to a dictionary, including unknown fields.

Return type:: dict[str, Any]

asjson()

Convert the entity to a JSON string, including unknown fields.

Return type:: str

has_missing_attrs()

Check if the entity has any attributes that are MISSING_FIELD.

Return type:: bool
Returns:: True if any attribute is MISSING_FIELD, False otherwise

id: str

is_attr_missing(attr_name)

Check if a value is the MISSING_FIELD sentinel.

Parameters:: attr_name (str)
Return type:: bool

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

Cache manager for storing and retrieving entity-related data locally.

This module provides caching functionality for resource data (images, segmentations, etc.) with automatic validation against server versions to ensure data freshness.

class datamint.entities.cache_manager.CacheManager(entity_type, cache_root=None, enable_memory_cache=False, memory_cache_maxsize=2)

Bases: Generic[T]

Manages local caching of entity data with versioning support.

This class handles storing and retrieving cached data with automatic validation against server versions to ensure data consistency.

The cache uses a directory structure: - cache_root/

resources/ - {resource_id}/

image_data.pkl

metadata.json

annotations/ - {annotation_id}/

segmentation_data.pkl

metadata.json

cache_root: Root directory for cache storage

entity_type: Type of entity being cached (e.g., ‘resources’, ‘annotations’)

Parameters:

entity_type (str)
cache_root (Path | str | None)
enable_memory_cache (bool)
memory_cache_maxsize (int)

class ItemMetadata(**data)

Bases: BaseModel

Parameters:: data (Any)

cached_at: datetime

data_path: str

data_type: str

entity_id: str | None

extra_info: dict | None

mimetype: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

version_hash: str | None

version_info: dict | None

clear_all()

Clear all cached data for this entity type.

Return type:: None

get(entity_id, data_key, version_info=None)

Retrieve cached data for an entity.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str) – Key identifying the type of data
version_info (dict[str, Any] | None) – Optional version information from server to validate cache

Return type:

TypeVar(T) | None

Returns:

Cached data if valid, None if cache miss or invalid

get_cache_info(entity_id)

Get information about cached data for an entity.

Parameters:: entity_id (str) – Unique identifier for the entity
Return type:: dict[str, Any]
Returns:: Dictionary containing cache information

get_expected_path(entity_id, data_key)

Get the expected cache path for an entity (even if not yet cached).

This is useful for downloading directly to the cache location.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str) – Key identifying the type of data

Return type:

Path

Returns:

Path where data will be cached

get_memory(entity_id, data_key, version_info=None)

Parameters:

entity_id (str)
data_key (str)
version_info (dict[str, Any] | None)

Return type:

TypeVar(T) | None

get_path(entity_id, data_key, version_info=None)

Get the path to cached data for an entity if valid.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str) – Key identifying the type of data
version_info (dict[str, Any] | None) – Optional version information from server to validate cache

Return type:

Path | None

Returns:

Path to cached data if valid, None if cache miss or invalid

invalidate(entity_id, data_key=None)

Invalidate cached data for an entity.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str | None) – Optional key for specific data. If None, invalidates all data for entity.

Return type:

None

invalidate_memory(entity_id, data_key=None)

Parameters:

entity_id (str)
data_key (str | None)

Return type:

None

iter_entities_extra_info()

Yield (entity_id, extra_info) for all cached entities that have extra_info.

Yields:: Tuples of (entity_id, extra_info dict) for entities with stored extra_info.

register_file_location(entity_id, data_key, file_path, version_info=None, mimetype='application/octet-stream', data=None)

Register an external file location in cache metadata without copying data.

This allows tracking a file stored at an arbitrary location (e.g., user’s save_path) while keeping version metadata in the cache directory.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str) – Key identifying the type of data
file_path (str | Path) – Path to the external file to register
version_info (dict[str, Any] | None) – Optional version information from server
mimetype (str) – MIME type of the file data
data (TypeVar(T) | None) – Optional data object to populate the in-memory cache immediately.

Return type:

None

save_extra_info(entity_id, extra_info)

Store arbitrary extra metadata alongside the cache entry for an entity.

This is a no-op when no cache entry exists yet for the entity.

Parameters:

entity_id (str) – Unique identifier for the entity
extra_info (dict) – Arbitrary key-value pairs to store (e.g. upload_channel, tags)

Return type:

None

set(entity_id, data_key, data, version_info=None)

Store data in cache for an entity.

Parameters:

entity_id (str) – Unique identifier for the entity
data_key (str) – Key identifying the type of data
data (TypeVar(T)) – Data to cache
version_info (dict[str, Any] | None) – Optional version information from server

Return type:

None

set_memory(entity_id, data_key, data, version_info=None)

Parameters:

entity_id (str)
data_key (str)
data (TypeVar(T))
version_info (dict[str, Any] | None)

Return type:

None

Resource Entities

Resource entity module for DataMint API.

class datamint.entities.resource.LocalResource(local_filepath=None, raw_data=None, convert_to_bytes=False, **kwargs)

Bases: BaseResource

Represents a local resource that hasn’t been uploaded to DataMint API yet.

Parameters:

local_filepath (str | Path | None)
raw_data (bytes | None)
convert_to_bytes (bool)

__repr__()

Detailed string representation of the local resource.

Return type:: str
Returns:: Detailed string representation for debugging

__str__()

String representation of the local resource.

Return type:: str
Returns:: Human-readable string describing the local resource

fetch_file_data(*args, auto_convert=True, save_path=None, use_cache=False, **kwargs)

Overloads:

self, args, auto_convert (Literal[True]), save_path (str | None), use_cache (CacheMode), kwargs → ImagingData
self, args, auto_convert (Literal[False]), save_path (str | None), use_cache (CacheMode), kwargs → bytes

Get the file data for this local resource.

Parameters:

auto_convert (bool) – If True, automatically converts to appropriate format (pydicom.Dataset, PIL Image, etc.)
save_path (str | None) – Optional path to save the file locally
use_cache (bool | Literal['loadonly']) – Ignored for local resources; included for API parity.

Returns:

File data (format depends on auto_convert and file type)

Return type:

bytes | ImagingData

property filepath_cached: Path | None

Get the file path of the local resource data.

Returns:: Path to the local file, or None if only raw data is available.

local_filepath: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

raw_data: bytes | None

class datamint.entities.resource.Resource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: BaseResource

Represents a DataMint resource with all its properties and metadata.

This class models a resource entity from the Dataint API, containing information about uploaded files, their metadata, and associated projects.

id: Unique identifier for the resource

resource_uri: URI path to access the resource file

storage: Storage type (e.g., ‘DicomResource’)

location: Storage location path

upload_channel: Channel used for upload (e.g., ‘tmp’)

filename: Original filename of the resource

modality: Medical imaging modality

mimetype: MIME type of the file

size: File size in bytes

upload_mechanism: Mechanism used for upload (e.g., ‘api’)

customer_id: Customer/organization identifier

status: Current status of the resource

created_at: ISO timestamp when resource was created

created_by: Email of the user who created the resource

published: Whether the resource is published

published_on: ISO timestamp when resource was published

published_by: Email of the user who published the resource

publish_transforms: Optional publication transforms

deleted: Whether the resource is deleted

deleted_at: Optional ISO timestamp when resource was deleted

deleted_by: Optional email of the user who deleted the resource

metadata: Resource metadata with DICOM information

source_filepath: Original source file path

tags: List of tags associated with the resource

instance_uid: DICOM SOP Instance UID (top-level)

series_uid: DICOM Series Instance UID (top-level)

study_uid: DICOM Study Instance UID (top-level)

patient_id: Patient identifier (top-level)

segmentations: Optional segmentation data

measurements: Optional measurement data

categories: Optional category data

labels: List of labels associated with the resource

user_info: Information about the user who created the resource

projects: List of projects this resource belongs to

__repr__()

Detailed string representation of the resource.

Return type:: str
Returns:: Detailed string representation for debugging

customer_id: str

deleted: bool

deleted_at: str | None

deleted_by: str | None

fetch_annotations(annotation_type=None)

Get annotations associated with this resource.

Example

>>> resource = api.resources.get_list(project_name="My Project")[0]
>>> annotations = resource.fetch_annotations(annotation_type="segmentation")
>>> [annotation.name for annotation in annotations]

Parameters:: annotation_type (AnnotationType | str | None)
Return type:: Sequence[Annotation]

fetch_file_data(auto_convert=True, save_path=None, use_cache=False)

Overloads:

self, auto_convert (Literal[True]), save_path (str | None), use_cache (CacheMode) → ImagingData
self, auto_convert (Literal[False]), save_path (str | None), use_cache (CacheMode) → bytes

Get the file data for this resource.

This method automatically caches the file data locally. On subsequent calls, it checks the server for changes and uses cached data if unchanged.

Parameters:

use_cache (bool | Literal['loadonly']) – Cache behavior for this call. Use False to bypass cache entirely, True to read from and save to cache, or "loadonly" to read from cache without saving cache misses.
auto_convert (bool) – If True, automatically converts to appropriate format (pydicom.Dataset, PIL Image, etc.)
save_path (str | None) – Optional path to save the file locally. If use_cache=True, the file is saved to save_path and cache metadata points to that location (no duplication - only one file on disk).

Returns:

File data (format depends on auto_convert and file type)

Return type:

bytes | ImagingData

Example

>>> resource = api.resources.get_list(project_name="My Project")[0]
>>> data = resource.fetch_file_data(use_cache=True)
>>> data = resource.fetch_file_data(use_cache="loadonly")
>>> resource.fetch_file_data(save_path="local_copy")

filename_suffixes: ClassVar[tuple[str, ...]] = ()

property filepath_cached: Path | None

Get the file path of the cached resource data, if available.

Returns:: Path to the cached file data, or None if not cached.

static from_local_file(file_path)

Create a LocalResource instance from a local file path.

Parameters:: file_path (str | Path) – Path to the local file

get_depth()

Return type:: int

get_frame(index)

Get a decoded video frame as a normalized array.

Parameters:: index (int)
Return type:: ndarray

get_frame_resource(index)

Get a proxy object for a specific video frame.

Parameters:: index (int)
Return type:: SlicedVideoResource

get_slice(axis, index)

Get a specific slice of the volume as a SlicedVolumeResource.

Parameters:

axis (Literal['axial', 'sagittal', 'coronal']) – The anatomical plane to slice along (e.g., ‘axial’, ‘coronal’, ‘sagittal’)
index (int) – The index of the slice along the specified axis

Return type:

ndarray

Returns:

A numpy array representing the specified slice

get_slice_resource(axis, index)

Get a proxy object for a specific volume slice.

Parameters:

axis (Literal['axial', 'sagittal', 'coronal'])
index (int)

Return type:

SlicedVolumeResource

instance_uid: str | None

invalidate_cache()

Invalidate cached data for this resource.

Return type:: None

is_cached()

Check if the resource’s file data is already cached locally and valid.

Return type:: bool
Returns:: True if valid cached data exists, False otherwise.

is_dicom()

Check if the resource is a DICOM file.

Return type:: bool
Returns:: True if the resource is a DICOM file, False otherwise

is_image()

Check if the resource is a single-frame image.

Return type:: bool

is_multiframe()

Check if the resource contains multiple frames or slices.

Return type:: bool

is_nifti()

Check if the resource is a NIfTI file.

Return type:: bool
Returns:: True if the resource is a NIfTI file, False otherwise

is_video()

Check if the resource is a video file.

Return type:: bool
Returns:: True if the resource is a video file, False otherwise

is_volume()

Check if the resource is a volumetric resource.

Return type:: bool

iter_frames()

Expand a video into one proxy resource per frame.

Return type:: list[SlicedVideoResource]

iter_slices(axis)

Expand a volume into one proxy resource per slice.

Parameters:: axis (Literal['axial', 'sagittal', 'coronal'])
Return type:: list[SlicedVolumeResource]

property kind: str

classmethod matches_payload(*, storage=None, mimetype=None, filename=None)

Parameters:

storage (str | None)
mimetype (str | None)
filename (str | None)

Return type:

bool

metadata: dict[str, Any]

mimetype_prefixes: ClassVar[tuple[str, ...]] = ()

mimetypes: ClassVar[tuple[str, ...]] = ()

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

patient_id: str | None

published: bool

published_by: str | None

published_on: str | None

resource_kind: ClassVar[str] = 'resource'

resource_priority: ClassVar[int] = 0

resource_uri: str

series_uid: str | None

show()

Open the resource in the default web browser.

Return type:: None

source_filepath: str | None

storage_aliases: ClassVar[tuple[str, ...]] = ()

study_uid: str | None

tags: list[str] | None

upload_channel: str

upload_mechanism: str | None

property url: str: Get the URL to access this resource in the DataMint web application.

user_info: dict[str, str] | str

class datamint.entities.resources.dicom_resource.DICOMResource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: VolumeResource

Represents a DICOM resource or assembled DICOM series.

filename_suffixes: ClassVar[tuple[str, ...]] = ('.dcm',)

mimetypes: ClassVar[tuple[str, ...]] = ('application/dicom',)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_kind: ClassVar[str] = 'dicom'

resource_priority: ClassVar[int] = 50

storage_aliases: ClassVar[tuple[str, ...]] = ('DicomResource', 'DicomResourceHandler')

property uids: dict[str, str]: Return the available DICOM UIDs for this resource.

class datamint.entities.resources.image_resource.ImageResource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: Resource

Represents a single-frame 2D image resource.

get_depth()

Return type:: int

get_dimensions()

Get image dimensions as (width, height).

Return type:: tuple[int | None, int | None]

property height: int | None

mimetype_prefixes: ClassVar[tuple[str, ...]] = ('image/',)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_kind: ClassVar[str] = 'image'

resource_priority: ClassVar[int] = 10

storage_aliases: ClassVar[tuple[str, ...]] = ('ImageResource', 'ImageResourceHandler')

property width: int | None

class datamint.entities.resources.nifti_resource.NiftiResource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: VolumeResource

Represents a NIfTI volume resource.

filename_suffixes: ClassVar[tuple[str, ...]] = ('.nii', '.nii.gz')

property is_compressed: bool: Whether the underlying NIfTI file is gzip-compressed.

mimetypes: ClassVar[tuple[str, ...]] = ('application/nifti',)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_kind: ClassVar[str] = 'nifti'

resource_priority: ClassVar[int] = 50

storage_aliases: ClassVar[tuple[str, ...]] = ('NiftiResource', 'NiftiResourceHandler')

class datamint.entities.resources.video_resource.VideoResource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: Resource

Represents a video resource with per-frame access helpers.

property frame_count: int

get_depth()

Return type:: int

get_dimensions()

Get video frame dimensions as (width, height).

Return type:: tuple[int | None, int | None]

property height: int | None

iter_frames()

Expand a video into one proxy resource per frame.

Return type:: list[SlicedVideoResource]

mimetype_prefixes: ClassVar[tuple[str, ...]] = ('video/',)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_kind: ClassVar[str] = 'video'

resource_priority: ClassVar[int] = 20

storage_aliases: ClassVar[tuple[str, ...]] = ('VideoResource', 'VideoResourceHandler')

property width: int | None

class datamint.entities.resources.volume_resource.VolumeResource(*, id, storage, location, filename, mimetype, size, status, created_at, created_by, modality=None, resource_uri, upload_channel, customer_id, published, deleted, upload_mechanism=None, metadata={}, source_filepath=None, published_on=None, published_by=None, tags=None, deleted_at=None, deleted_by=None, instance_uid=None, series_uid=None, study_uid=None, patient_id=None, user_info='MISSING_FIELD', **data)

Bases: Resource

Represents a volumetric resource, such as a 3D CT or MRI scan.

property frame_count: int

get_depth()

Return type:: int

get_slice(axis, index)

Get a specific slice of the volume as a SlicedVolumeResource.

Parameters:

axis (Literal['axial', 'sagittal', 'coronal']) – The anatomical plane to slice along (e.g., ‘axial’, ‘coronal’, ‘sagittal’)
index (int) – The index of the slice along the specified axis

Return type:

ndarray

Returns:

A numpy array representing the specified slice

get_slice_resource(axis, index)

Get a proxy object for a specific volume slice.

Parameters:

axis (Literal['axial', 'sagittal', 'coronal'])
index (int)

Return type:

SlicedVolumeResource

iter_slices(axis)

Expand a volume into one proxy resource per slice.

Parameters:: axis (Literal['axial', 'sagittal', 'coronal'])
Return type:: list[SlicedVolumeResource]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_kind: ClassVar[str] = 'volume'

resource_priority: ClassVar[int] = 30

storage_aliases: ClassVar[tuple[str, ...]] = ('VolumeResource', 'VolumeResourceHandler')

SlicedVideoResource - Proxy for a single frame of a video Resource.

Analogous to SlicedVolumeResource but simplified for temporal data — videos always slice along the frame (temporal) axis.

class datamint.entities.sliced_video_resource.SlicedVideoResource(parent, frame_index, frame_cache=None)

Bases: SlicedResourceBase

Proxy that presents a single frame of a video Resource.

Wraps a Resource and represents a specific frame by index. Uses gzip-compressed .npy.gz files on disk for caching, with an in-memory LRU cache managed by CacheManager.

Parameters:

parent (Resource) – The original video Resource.
frame_index (int) – The index of the frame in the video.
frame_cache (CacheManager | None) – Shared CacheManager for disk-based frame caching.

fetch_frame_data()

Fetch the frame as a (C, H, W) array.

Return type:: ndarray
Returns:: Frame array with shape (C, H, W).

get_depth()

A single frame has depth 1.

Return type:: int

static slice_over(resource, frame_cache=None)

Expand a video resource into per-frame proxy resources.

Parameters:

resource (Resource) – The video Resource to expand.
frame_cache (CacheManager | None) – Shared cache for decoded frames.

Return type:

list[SlicedVideoResource]

Returns:

List of SlicedVideoResource, one per frame.

Project Entity

Project entity module for DataMint API.

class datamint.entities.project.Project(*, id, name, created_at, created_by, dataset_id, archived, resource_count, description, registered_model='MISSING_FIELD', ai_model_id='MISSING_FIELD', closed_resources_count='MISSING_FIELD', resources_to_annotate_count='MISSING_FIELD', most_recent_experiment='MISSING_FIELD', annotators='MISSING_FIELD', archived_on='MISSING_FIELD', archived_by='MISSING_FIELD', is_active_learning='MISSING_FIELD', two_up_display='MISSING_FIELD', require_review='MISSING_FIELD', **data)

Bases: BaseEntity

Pydantic Model representing a DataMint project.

This class models a project entity from the DataMint API, containing information about the project, its dataset, worklist, AI model, and annotation statistics.

id: Unique identifier for the project

name: Human-readable name of the project

description: Optional description of the project

created_at: ISO timestamp when the project was created

created_by: Email of the user who created the project

dataset_id: ID of the associated dataset

worklist_id: ID of the associated worklist

ai_model_id: Optional ID of the associated AI model

archived: Whether the project is archived

resource_count: Total number of resources in the project

annotated_resource_count: Number of resources that have been annotated

most_recent_experiment: Optional information about the most recent experiment

closed_resources_count: Number of resources marked as closed/completed

resources_to_annotate_count: Number of resources still needing annotation

annotators: List of annotators assigned to this project

ai_model_id: str | None

annotators: list[_ProjectAnnotatorInfo]

archived: bool

archived_by: str | None

archived_on: str | None

cache_resources(progress_bar=True)

Cache all project resources in parallel for faster subsequent access.

This method downloads and caches all resource file data concurrently, skipping resources that are already cached. This dramatically improves performance when working with large projects.

Parameters:: progress_bar (bool) – Whether to show a progress bar. Default is True.
Return type:: None

Example

>>> project = api.projects.get_by_name("My Project")
>>> project.cache_resources(progress_bar=False)
>>> # Now fetch_file_data() will be instantaneous for cached resources
>>> for resource in project.fetch_resources():
...     data = resource.fetch_file_data(use_cache=True)

closed_resources_count: int

created_at: str

created_by: str

dataset_id: str

description: str | None

download_resources_datas(progress_bar=True)

Downloads all project resources in parallel for faster subsequent access.

This method downloads and caches all resource file data concurrently, skipping resources that are already cached. This dramatically improves performance when working with large projects.

Parameters:: progress_bar (bool) – Whether to show a progress bar. Default is True.
Return type:: None

Example

>>> project = api.projects.get_by_name("My Project")
>>> project.download_resources_datas(progress_bar=False)
>>> # Now fetch_file_data() will be instantaneous for cached resources
>>> for resource in project.fetch_resources():
...     data = resource.fetch_file_data(use_cache=True)

fetch_resources()

Fetch resources associated with this project from the API, IMPORTANT: It always fetches fresh data from the server.

Return type:: Sequence[Resource]
Returns:: List of Resource instances associated with the project.

Example

>>> project = api.projects.get_by_name("My Project")
>>> resources = project.fetch_resources()
>>> [resource.filename for resource in resources]

fetch_worklists()

Fetch the worklists associated with this project from the API.

Return type:: Sequence[AnnotationWorklist]

id: str

is_active_learning: bool

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

most_recent_experiment: str | None

name: str

registered_model: Any | None

require_review: bool

resource_count: int

resources_to_annotate_count: int

set_work_status(resource, status)

Set the status of a resource.

Parameters:

resource (Resource) – The resource unique id or a resource object.
status (Literal['opened', 'annotated', 'closed']) – The new status to set.

Return type:

None

Example

>>> project = api.projects.get_by_name("My Project")
>>> resource = project.fetch_resources()[0]
>>> project.set_work_status(resource, "annotated")

show()

Open the project in the default web browser.

Return type:: None

two_up_display: bool

property url: str: Get the URL to access this project in the DataMint web application.

Channel Entity

class datamint.entities.channel.Channel(*, id, channel_name, resource_data, deleted=False, created_at=None, updated_at=None, **data)

Bases: BaseEntity

Represents a channel containing multiple resources.

A channel is a collection of resources grouped together, typically for batch processing or organization purposes.

channel_name: Name identifier for the channel.

resource_data: List of resources contained in this channel.

deleted: Whether the channel has been marked as deleted.

created_at: Timestamp when the channel was created.

updated_at: Timestamp when the channel was last updated.

channel_name: str

created_at: str | None

deleted: bool

get_resource_ids()

Get list of all resource IDs in this channel.

Return type:: list[str]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

resource_data: list[ChannelResourceData]

updated_at: str | None

class datamint.entities.channel.ChannelResourceData(**data)

Bases: BaseModel

Represents resource data within a channel.

created_by: Email of the user who created the resource.

customer_id: UUID of the customer.

resource_id: UUID of the resource.

resource_file_name: Original filename of the resource.

resource_mimetype: MIME type of the resource.

Parameters:: data (Any)

created_by: str

customer_id: str

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resource_file_name: str

resource_id: str

resource_mimetype: str

User Entity

class datamint.entities.user.User(*, id, email, firstname, lastname, roles, customer_id, created_at, **data)

Bases: BaseEntity

User entity model.

email: User email address (unique identifier in most cases).

firstname: First name.

lastname: Last name.

roles: List of role strings assigned to the user.

customer_id: UUID of the owning customer/tenant.

created_at: ISO 8601 timestamp of creation.

created_at: str

customer_id: str

email: str

firstname: str | None

lastname: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

roles: list[str]

Dataset Info Entity

Dataset entity module for DataMint API.

class datamint.entities.datasetinfo.DatasetInfo(*, id, name, created_at, created_by, description, customer_id, updated_at, total_resource, resource_ids, **data)

Bases: BaseEntity

Pydantic Model representing a DataMint dataset.

This class provides access to dataset information and related entities like resources and projects.

created_at: str

created_by: str

customer_id: str

description: str

id: str

invalidate_cache()

Invalidate all cached relationship data.

This forces fresh data fetches on the next access.

Return type:: None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

name: str

resource_ids: list[str]

total_resource: int

updated_at: str | None

Split Entity

class datamint.entities.project_resource_split.ProjectResourceSplit(*, id, split_name, project_id, resource_id, created_at, created_by, deleted_at=None, deleted_by=None, **data)

Bases: BaseEntityModel

Read-only DTO representing a resource-to-split assignment within a project.

created_at: str

created_by: str

deleted_at: str | None

deleted_by: str | None

id: str

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

project_id: str

resource_id: str

split_name: str

Job Entities

class datamint.entities.deployjob.DeployJob(*, id, status, model_name, build_logs='', model_version=None, model_alias=None, image_name=None, image_tag=None, error_message=None, progress_percentage=0, current_step=None, with_gpu=False, recent_logs=None, started_at=None, completed_at=None, **data)

Bases: BaseEntity

build_logs: str

completed_at: str | None

current_step: str | None

error_message: str | None

id: str

image_name: str | None

image_tag: str | None

property is_finished: bool: Whether the job has reached a terminal state.

model_alias: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_name: str

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

model_version: int | None

progress_percentage: int

recent_logs: list[str] | None

started_at: str | None

status: str

wait(*, on_status=None, poll_interval=2.0, timeout=None)

Block until this job reaches a terminal state.

Uses the SSE stream when available, falling back to polling. In-place updates to this object are made on every status change.

Parameters:

on_status (Callable[[DeployJob], None] | None) – Optional callback invoked with an updated DeployJob on every status change.
poll_interval (float) – Seconds between polls in polling-fallback mode.
timeout (float | None) – Maximum seconds to wait. Raises TimeoutError on expiry.

Return type:

DeployJob

with_gpu: bool

class datamint.entities.inferencejob.InferenceJob(*, id, status, model_name, resource_id=None, frame_idx=None, created_at=None, started_at=None, completed_at=None, progress_percentage=0, current_step=None, error_message=None, save_results=True, result_data=None, annotation_ids=None, recent_logs=None, **data)

Bases: BaseEntity

Entity representing an inference job.

annotation_ids: list | None

completed_at: str | None

created_at: str | None

current_step: str | None

error_message: str | None

frame_idx: int | None

id: str

property is_finished: bool: Whether the job has reached a terminal state.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_name: str

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

property predictions: list[list[Annotation]] | None

Returns a list of annotations resulting from this inference job, if available.

Each element of the outer list corresponds to one input resource; the inner list contains the annotations produced for that resource.

Returns:: list[list[Annotation]] (one outer list for each input resource) or None when no predictions are stored in result_data.

progress_percentage: int

recent_logs: list[str] | None

resource_id: str | None

result_data: dict[str, Any] | None

save_results: bool

started_at: str | None

status: str

wait(*, on_status=None, poll_interval=2.0, timeout=None)

Block until this job reaches a terminal state.

Uses the SSE stream when available, falling back to polling. In-place updates to this object are made on every status change.

Parameters:

on_status (Callable[[InferenceJob], None] | None) – Optional callback invoked with an updated InferenceJob on every status change.
poll_interval (float) – Seconds between polls in polling-fallback mode.
timeout (float | None) – Maximum seconds to wait. Raises TimeoutError on expiry.

Return type:

InferenceJob

Annotations Subpackage

The datamint.entities.annotations subpackage contains all annotation-related entity classes. See Annotations Subpackage for detailed documentation.

class datamint.entities.annotations.Annotation(*, id=None, name, scope, annotation_type, confiability=1.0, frame_index=None, text_value=None, numeric_value=None, units=None, geometry=None, created_at=None, created_by=None, annotation_worklist_id=None, imported_from=None, import_author=None, status=None, approved_at=None, approved_by=None, resource_id=None, associated_file=None, deleted=False, deleted_at=None, deleted_by=None, created_by_model=None, is_model=None, model_id=None, set_name=None, resource_filename=None, resource_modality=None, annotation_worklist_name=None, user_info=None, values='MISSING_FIELD', file=None, **data)

Bases: AnnotationBase

Pydantic Model representing a DataMint annotation.

id: Unique identifier for the annotation.

identifier: User-friendly identifier or label for the annotation.

scope: Scope of the annotation (e.g., “frame”, “image”).

frame_index: Index of the frame if scope is frame-based.

annotation_type: Type of annotation (e.g., “segmentation”, “bbox”, “label”).

text_value: Optional text value associated with the annotation.

numeric_value: Optional numeric value associated with the annotation.

units: Optional units for numeric_value.

geometry: Optional geometry payload (e.g., polygons) as a list.

created_at: ISO timestamp for when the annotation was created.

created_by: Email or identifier of the creating user.

annotation_worklist_id: Optional worklist ID associated with the annotation.

status: Lifecycle status of the annotation (e.g., “new”, “approved”).

approved_at: Optional ISO timestamp for approval time.

approved_by: Optional identifier of the approver.

resource_id: ID of the resource this annotation belongs to.

associated_file: Path or identifier of any associated file artifact.

deleted: Whether the annotation is marked as deleted.

deleted_at: Optional ISO timestamp for deletion time.

deleted_by: Optional identifier of the user who deleted the annotation.

created_by_model: Optional identifier of the model that created this annotation.

old_geometry: Optional previous geometry payload for change tracking.

set_name: Optional set name this annotation belongs to.

resource_filename: Optional filename of the resource.

resource_modality: Optional modality of the resource (e.g., CT, MR).

annotation_worklist_name: Optional worklist name associated with the annotation.

user_info: Optional user information with keys like firstname and lastname.

values: Optional extra values payload for flexible schemas.

property added_by: str: Get the creator email (alias for created_by).

annotation_worklist_id: str | None

annotation_worklist_name: str | None

approved_at: str | None

approved_by: str | None

associated_file: str | None

created_at: str | None

created_by: str | None

created_by_model: str | None

deleted: bool

deleted_at: str | None

deleted_by: str | None

fetch_file_data(auto_convert=True, save_path=None, use_cache=False)

Overloads:

self, auto_convert (Literal[True]), save_path (str | None), use_cache (CacheMode) → ImagingData
self, auto_convert (Literal[False]), save_path (str | None), use_cache (CacheMode) → bytes

Get the file data for this annotation.

Parameters:

save_path (str | None) – Optional path to save the file locally. If use_cache=True, the file is saved to save_path and cache metadata points to that location (no duplication - only one file on disk).
auto_convert (bool) – If True, automatically converts to appropriate format
use_cache (bool | Literal['loadonly']) – Cache behavior for this call. Use False to bypass cache entirely, True to read from and save to cache, or "loadonly" to read from cache without saving cache misses.

Returns:

File data (format depends on auto_convert and file type)

Return type:

bytes | ImagingData

Example

>>> annotation = api.annotations.get_list(limit=1)[0]
>>> data = annotation.fetch_file_data(use_cache=True)
>>> data = annotation.fetch_file_data(use_cache="loadonly")
>>> annotation.fetch_file_data(save_path="annotation_file")

file: str | None

frame_index: int | None

classmethod from_dict(data)

Create an Annotation instance from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary containing annotation data from API
Return type:: Annotation
Returns:: Annotation instance

geometry: list | dict | None

get_created_datetime()

Get the creation datetime as a datetime object.

Return type:: datetime | None
Returns:: datetime object or None if created_at is not set

id: str | None

identifier: str

import_author: str | None

imported_from: str | None

property index: int | None: Get the frame index (alias for frame_index).

invalidate_cache()

Invalidate all cached data for this annotation.

Return type:: None

is_cached()

Check if the resource’s file data is already cached locally and valid.

Return type:: bool
Returns:: True if valid cached data exists, False otherwise.

is_frame_scoped()

Check if this annotation is frame-scoped.

Return type:: bool

is_image_scoped()

Check if this annotation is image-scoped.

Return type:: bool

is_model: bool | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_id: str | None

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

numeric_value: float | int | None

property resource: Resource

Lazily load and cache the associated Resource entity.

Example

>>> annotation = api.annotations.get_list(limit=1)[0]
>>> annotation.resource.filename

resource_filename: str | None

resource_id: str | None

resource_modality: str | None

scope: str

set_name: str | None

status: str | None

text_value: str | None

property type: str: Alias for annotation_type.

units: str | None

user_info: dict | None

property value: str | None: Get the annotation value (for category annotations).

values: list | None

class datamint.entities.annotations.AnnotationType(*values)

Bases: StrEnum

ANGLE = 'angle'

AREA = 'area'

CATEGORY = 'category'

CIRCLE = 'circle'

DISTANCE = 'distance'

LABEL = 'label'

LINE = 'line'

POINT = 'point'

REGION = 'region'

SEGMENTATION = 'segmentation'

SQUARE = 'square'

class datamint.entities.annotations.BoxAnnotation(geometry=None, **kwargs)

Bases: BaseGeometryAnnotation

Typed box annotation entity.

Parameters:

geometry (BoxGeometry | dict[str, Any] | None)
kwargs (Any)

classmethod from_points(point1, point2, *, identifier, frame_index=None, metadata=None, coords_system='pixel', **kwargs)

Parameters:

point1 (tuple[int, int] | tuple[float, float, float])
point2 (tuple[int, int] | tuple[float, float, float])
identifier (str)
frame_index (int | None)
metadata (Dataset | Nifti1Image | None)
coords_system (Literal['pixel', 'patient'])
kwargs (Any)

Return type:

BoxAnnotation

geometry: BoxGeometry | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

class datamint.entities.annotations.BoxGeometry(**data)

Bases: Geometry

Parameters:: data (Any)

classmethod from_coordinates(point1, point2, *, coords_system='pixel', slice_plane=None, frame_index=None, metadata=None)

Parameters:

point1 (tuple[int, int] | tuple[float, float, float])
point2 (tuple[int, int] | tuple[float, float, float])
coords_system (Literal['pixel', 'patient'])
slice_plane (Literal['axial', 'sagittal', 'coronal'] | None)
frame_index (int | None)
metadata (Dataset | Nifti1Image | None)

Return type:

BoxGeometry

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property point1: tuple[int | float, int | float, int | float]

property point2: tuple[int | float, int | float, int | float]

points: tuple[tuple[int | float, int | float, int | float], tuple[int | float, int | float, int | float], tuple[int | float, int | float, int | float], tuple[int | float, int | float, int | float]]

type: ClassVar[str] = 'square'

class datamint.entities.annotations.Geometry(**data)

Bases: BaseModel

Base geometry payload for annotation entities.

Parameters:: data (Any)

coordinate_system: Literal['pixel', 'patient']

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_dict()

Return type:: dict[str, Any]

type: ClassVar[str]

viewPlaneNormal: tuple[float, float, float] | None

viewUp: tuple[float, float, float] | None

class datamint.entities.annotations.ImageClassification(name=None, value=None, confiability=1.0, **kwargs)

Bases: Annotation

Parameters:

name (str | None)
value (str | None)
confiability (float)
kwargs (Any)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

class datamint.entities.annotations.ImageSegmentation(segmentation_data=None, **kwargs)

Bases: BaseSegmentationAnnotation

Image-level (2-D) binary segmentation annotation entity.

Represents a binary segmentation mask (foreground / background) for a single image. The stored mask always contains only 0 and 1 values; any non-zero input pixel is normalised to 1.

Parameters:

segmentation_data (ndarray | Image | None) – The mask as a np.ndarray (dtype=uint8), PIL.Image.Image, or nibabel.nifti1.Nifti1Image. Automatically serialised/deserialised on persist/load.
name (str) – The annotation class label (stored in the inherited identifier field).

Example

>>> mask = np.zeros((256, 256), dtype=np.uint8)
>>> mask[100:150, 100:150] = 1  # foreground region
>>> img_seg = ImageSegmentation.from_mask(mask=mask, name='lesion')
>>> img_seg.name
'lesion'

get_area()

Return the number of foreground (non-zero) pixels in the mask.

Return type:: int | None
Returns:: Foreground pixel count or None if no mask is stored.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

to_pil_image()

Convert the mask to a PIL Image.

Return type:: Image | None
Returns:: PIL.Image.Image or None if no mask is stored.

class datamint.entities.annotations.LineAnnotation(geometry=None, **kwargs)

Bases: BaseGeometryAnnotation

Typed line annotation entity.

Parameters:

geometry (LineGeometry | dict[str, Any] | None)
kwargs (Any)

classmethod from_points(point1, point2, *, identifier, frame_index=None, slice_plane=None, metadata=None, coords_system='pixel', **kwargs)

Parameters:

point1 (tuple[int, int] | tuple[float, float, float])
point2 (tuple[int, int] | tuple[float, float, float])
identifier (str)
frame_index (int | None)
slice_plane (Literal['axial', 'sagittal', 'coronal'] | None)
metadata (Dataset | Nifti1Image | None)
coords_system (Literal['pixel', 'patient'])
kwargs (Any)

Return type:

LineAnnotation

geometry: LineGeometry | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

class datamint.entities.annotations.LineGeometry(**data)

Bases: _TwoPointGeometry

Parameters:: data (Any)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: ClassVar[str] = 'line'

class datamint.entities.annotations.VolumeSegmentation(*, id=None, name, scope, annotation_type, confiability=1.0, frame_index=None, text_value=None, numeric_value=None, units=None, geometry=None, created_at=None, created_by=None, annotation_worklist_id=None, imported_from=None, import_author=None, status=None, approved_at=None, approved_by=None, resource_id=None, associated_file=None, deleted=False, deleted_at=None, deleted_by=None, created_by_model=None, is_model=None, model_id=None, set_name=None, resource_filename=None, resource_modality=None, annotation_worklist_name=None, user_info=None, values='MISSING_FIELD', file=None, mask=None, class_map=None, **kwargs)

Bases: BaseSegmentationAnnotation

Volume-level segmentation annotation entity.

Represents a 3-D segmentation mask for medical imaging volumes. Supports both semantic segmentation (class per voxel) and instance segmentation (unique ID per object).

This class provides factory methods to create annotations from numpy arrays or NIfTI images, which can then be uploaded via AnnotationsApi.

Example

>>> # From semantic segmentation
>>> seg_data = np.array([...])  # Shape: (H, W, D)
>>> class_map = {1: 'tumor', 2: 'edema'}
>>> vol_seg = VolumeSegmentation.from_semantic_segmentation(
...     segmentation=seg_data,
...     class_map=class_map
... )
>>>
>>> # Upload via API
>>> api.annotations.upload_segmentations(
...     resource='resource_id',
...     file_path=vol_seg.segmentation_data,
...     name=vol_seg.class_map
... )

class_map: dict[int, str] | None

property class_names: list[str] | None

Get list of class names from stored class_map.

Returns:: List of class names or None if no class_map stored

classmethod from_semantic_segmentation(segmentation, class_map, **kwargs)

Create VolumeSegmentation from semantic segmentation data.

Semantic segmentation: each voxel has a single integer label corresponding to its class.

Parameters:

segmentation (ndarray | Nifti1Image) – 3D numpy array (H x W x D) or NIfTI image with integer labels representing classes
class_map (dict[int, str] | str) – Mapping from label integers to class names, or a single class name for binary segmentation (background=0, class=1)
**kwargs – Additional annotation fields (imported_from, model_id, etc.)

Return type:

VolumeSegmentation

Returns:

VolumeSegmentation instance ready for upload

Raises:

ValueError – If segmentation shape is invalid, class_map is incomplete, or data types are incorrect

Example

>>> seg = np.zeros((256, 256, 128), dtype=np.int32)
>>> seg[100:150, 100:150, 50:75] = 1  # tumor region
>>> vol_seg = VolumeSegmentation.from_semantic_segmentation(
...     segmentation=seg,
...     class_map={1: 'tumor'}, # or just ``class_map='tumor'``
... )

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_name': True, 'ser_json_bytes': 'base64', 'val_json_bytes': 'base64', 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_BaseEntityModel__context)

Handle unknown fields by logging a warning once per class/field combination in debug mode.

Parameters:: _BaseEntityModel__context (Any)
Return type:: None

property num_classes: int | None

Get number of classes in this segmentation.

Returns:: Number of classes or None if no class_map stored

property volume_shape: tuple[int, int, int] | None

Get the shape of the stored segmentation volume.

Returns:: Shape tuple (H, W, D) or None if no data stored

datamint.entities.annotations.annotation_from_dict(data)

Factory: map a raw annotation dict to the appropriate Annotation subclass.

Dispatches on annotation_type:

'segmentation' with a class_map → VolumeSegmentation
'segmentation' without class_map → ImageSegmentation
anything else → Annotation

segmentation_data dicts are automatically deserialised by the Pydantic BeforeValidator defined on BaseSegmentationAnnotation. class_map string keys (produced by JSON serialisation) are coerced to int by Pydantic’s lax validation.

Parameters:: data (dict) – Raw annotation dict as returned by the API.
Return type:: Annotation
Returns:: A concrete Annotation subclass instance.