Dataset Classes

The datamint.dataset module provides specialised PyTorch-compatible dataset classes for different medical imaging modalities. Import them directly:

from datamint.dataset import ImageDataset, VolumeDataset, VideoDataset

Base Classes

DatamintBaseDataset - Abstract base class for all Datamint datasets.

Provides the PyTorch Dataset interface with transform support and annotation filtering, while delegating data management to DatamintProjectManager.

class datamint.dataset.base.DatamintBaseDataset(project=None, resources=None, auto_update=True, api_key=None, server_url=None, return_metainfo=True, return_segmentations=True, return_as_semantic_segmentation=False, semantic_seg_merge_strategy=None, alb_transform=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, allow_external_annotations=False, image_labels_merge_strategy=None, image_categories_merge_strategy=None)

Bases: ABC, Dataset

Abstract base class for Datamint datasets.

This class provides the PyTorch Dataset interface with: - Transform hooks (albumentations) - Annotation filtering - Data loading utilities

Subclasses must implement _get_raw_item() to define how data is loaded.

Parameters:

  • project (str | Project | None) – Project name, Project object, or None. Mutually exclusive with resources.

  • resources (Sequence[Resource] | None) – List of Resource objects/IDs, or None. Mutually exclusive with project.

  • auto_update (bool) – If True, sync with server on init.

  • api_key (str | None) – API key for authentication.

  • server_url (str | None) – Datamint server URL.

  • all_annotations – If True, include unpublished annotations.

  • return_metainfo (bool) – If True, include metadata in output.

  • return_segmentations (bool) – If True, process and return segmentations.

  • return_as_semantic_segmentation (bool) – If True, convert to semantic format.

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None) – Strategy for merging multi-annotator segs.

  • alb_transform (Callable | BaseCompose | None) – Albumentations transform.

  • include_unannotated (bool) – If True, include resources without annotations.

  • include_annotators (list[str] | None) – Whitelist of annotators.

  • exclude_annotators (list[str] | None) – Blacklist of annotators.

  • include_segmentation_names (list[str] | None) – Whitelist of segmentation labels.

  • exclude_segmentation_names (list[str] | None) – Blacklist of segmentation labels.

  • include_image_label_names (list[str] | None) – Whitelist of image labels.

  • exclude_image_label_names (list[str] | None) – Blacklist of image labels.

  • include_frame_label_names (list[str] | None) – Whitelist of frame labels.

  • exclude_frame_label_names (list[str] | None) – Blacklist of frame labels.

  • allow_external_annotations (bool) – If True, allow and automatically include annotation labels that are not part of the project’s official schema (e.g., labels from other projects or legacy annotations). If False, these annotations will be filtered out.

  • image_labels_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • image_categories_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

__add__(other)

Concatenate datasets.

Parameters:

other (DatamintBaseDataset)

Return type:

ConcatDataset

__getitem__(index)

Get item with full processing.

Parameters:

index (int)

Return type:

dict[str, Any]

__iter__()

Iterate over dataset.

Return type:

Iterator[dict[str, Any]]

__len__()

Dataset length.

Return type:

int

abstractmethod apply_alb_transform(img, segmentations)

Apply albumentations transform to image and masks.

Return type:

dict[str, Any]

Returns:

Dict with transformed ‘image’ and ‘segmentations’ (dict).

It is recommended that ‘image’ has shape (C, depth, H, W) and each segmentation of ‘segmentations’ has shape (num_instances, depth, H, W), so that common downstream processing can be applied. If not, please override _process_segmentations() accordingly.

Parameters:

  • img (ndarray)

  • segmentations (dict[str, ndarray])

build_mlflow_dataset()

Create a DatamintMLflowDataset for this dataset.

Parameters:

split – The split name (e.g. 'train', 'val', 'test').

Return type:

DatamintMLflowDataset

filter(*, tags=None, filename_pattern=None, has_annotations=None, annotation_names=None, custom_fn=None)

Return a new dataset containing only resources that match all specified criteria.

This method is chainable — the returned dataset supports the same interface, so you can write:

filtered = dataset.filter(tags=['busi']).filter(has_annotations=True)

or combine with split():

parts = dataset.filter(tags=['ultrasound']).split(train=0.8, test=0.2)
Parameters:

  • tags (list[str] | None) – Keep resources whose tags contain any of the given values.

  • filename_pattern (str | None) – Keep resources whose filename matches this pattern (interpreted as fnmatch.fnmatch() glob).

  • has_annotations (bool | None) – If True, keep only resources with at least one annotation. If False, keep only those without annotations.

  • annotation_names (list[str] | None) – Keep resources that have at least one annotation whose identifier is in this list.

  • custom_fn (Callable[[Resource, Sequence[Annotation]], bool] | None) – Arbitrary predicate receiving (resource, annotations) and returning True to keep the resource.

Return type:

DatamintBaseDataset

Returns:

A new DatamintBaseDataset containing only the matching resources.

Raises:

ValueError – If no filter criteria are specified.

property frame_labels_set: list[str]

Frame-level label names.

get_collate_fn()

Get collate function for DataLoader.

Return type:

Callable[[list[dict]], dict]

get_dataloader(*args, **kwargs)

Get DataLoader with proper collate function.

Return type:

DataLoader

property image_categories_set: list[tuple[str, str]]

Image-level classification category names/values.

property image_labels_set: list[str]

Image-level label names.

property segmentation_labels_set: list[str]

Segmentation label names.

set_transform(alb_transform=None)

Set transforms after initialization.

Parameters:

alb_transform (BaseCompose | None)

Return type:

None

split(*, seed=None, use_server_splits=None, **splits)

Split the dataset into multiple named subsets.

The mode is selected automatically when use_server_splits is not given:

  • If ratio kwargs are provided (e.g. train=0.7), local splitting is used (equivalent to use_server_splits=False).

  • If no ratio kwargs are provided, server-side split:* tags on resources are used (equivalent to use_server_splits=True).

Examples:

# Local split — ratios infer use_server_splits=False
parts = dataset.split(train=0.7, val=0.15, test=0.15, seed=42)
train_ds = parts['train']

# Server-side split — no ratios, infers use_server_splits=True
parts = dataset.split()

# Explicit override
parts = dataset.split(use_server_splits=True)
Parameters:

  • seed (int | None) – Random seed for reproducible local splitting.

  • use_server_splits (bool | None) – If True, read split:* tags from each resource instead of performing a random split. If None (default), inferred from whether ratio kwargs are provided.

  • **splits (float) – Named split ratios (e.g. train=0.7, test=0.3). Must sum to 1.0 (±0.01 tolerance). Must be empty when use_server_splits is True.

Return type:

dict[str, DatamintBaseDataset]

Returns:

Dictionary mapping split names to new dataset instances.

Raises:

ValueError – If ratios are invalid or arguments conflict.

subset(indices)

Create a dataset subset by slicing resources and annotations.

Parameters:

indices (list[int])

Return type:

DatamintBaseDataset

exception datamint.dataset.base.DatamintDatasetException

Bases: DatamintException

Exception raised for dataset errors.

MultiFrameDataset - Abstract base for datasets with multiple frames per resource.

Shared logic for VolumeDataset (3D medical volumes) and VideoDataset (temporal video sequences). Both handle data with shape (C, N, H, W) where N is the number of frames/slices.

class datamint.dataset.multiframe_dataset.MultiFrameDataset(project=None, resources=None, auto_update=True, api_key=None, server_url=None, return_metainfo=True, return_segmentations=True, return_as_semantic_segmentation=False, semantic_seg_merge_strategy=None, alb_transform=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, allow_external_annotations=False, image_labels_merge_strategy=None, image_categories_merge_strategy=None)

Bases: DatamintBaseDataset

Abstract base for multi-frame datasets.

Handles loading and augmenting data with shape (C, N, H, W) where N is the number of frames (temporal for video) or slices (spatial for volumes).

Subclasses add modality-specific features: - VolumeDataset: anatomical slicing via .slice() - VideoDataset: frame-by-frame iteration via .frame_by_frame()

Parameters:

  • project (str | Project | None)

  • resources (Sequence[Resource] | None)

  • auto_update (bool)

  • api_key (str | None)

  • server_url (str | None)

  • return_metainfo (bool)

  • return_segmentations (bool)

  • return_as_semantic_segmentation (bool)

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • alb_transform (Callable | BaseCompose | None)

  • include_unannotated (bool)

  • include_annotators (list[str] | None)

  • exclude_annotators (list[str] | None)

  • include_segmentation_names (list[str] | None)

  • exclude_segmentation_names (list[str] | None)

  • include_image_label_names (list[str] | None)

  • exclude_image_label_names (list[str] | None)

  • include_frame_label_names (list[str] | None)

  • exclude_frame_label_names (list[str] | None)

  • allow_external_annotations (bool)

  • image_labels_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • image_categories_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

apply_alb_transform(img, segmentations)

Apply albumentations transform to 4D image and masks.

Parameters:

  • img (ndarray) – Image array of shape (C, depth, H, W).

  • segmentations (dict[str, ndarray]) – Dict of author -> mask arrays of shape (#instances, depth, H, W).

Return type:

dict[str, Any]

Returns:

Dict with transformed 'image' and 'segmentations'.

Specialised Datasets

ImageDataset - Dataset for 2D images.

Handles standard 2D medical images like X-rays, pathology patches, single-frame DICOM, PNG, JPEG, etc.

class datamint.dataset.image_dataset.ImageDataset(project=None, resources=None, auto_update=True, api_key=None, server_url=None, return_metainfo=True, return_segmentations=True, return_as_semantic_segmentation=False, semantic_seg_merge_strategy=None, alb_transform=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, allow_external_annotations=False, image_labels_merge_strategy=None, image_categories_merge_strategy=None)

Bases: VolumeDataset

Dataset for 2D medical images.

Parameters:

  • project (str | Project | None)

  • resources (Sequence[Resource] | None)

  • auto_update (bool)

  • api_key (str | None)

  • server_url (str | None)

  • return_metainfo (bool)

  • return_segmentations (bool)

  • return_as_semantic_segmentation (bool)

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • alb_transform (Callable | BaseCompose | None)

  • include_unannotated (bool)

  • include_annotators (list[str] | None)

  • exclude_annotators (list[str] | None)

  • include_segmentation_names (list[str] | None)

  • exclude_segmentation_names (list[str] | None)

  • include_image_label_names (list[str] | None)

  • exclude_image_label_names (list[str] | None)

  • include_frame_label_names (list[str] | None)

  • exclude_frame_label_names (list[str] | None)

  • allow_external_annotations (bool)

  • image_labels_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • image_categories_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

apply_alb_transform(img, segmentations)

Apply albumentations transform to 4D image and masks.

Parameters:

  • img (ndarray) – Image array of shape (C, depth, H, W).

  • segmentations (dict[str, ndarray]) – Dict of author -> mask arrays of shape (#instances, depth, H, W).

Return type:

dict[str, Any]

Returns:

Dict with transformed 'image' and 'segmentations'.

VolumeDataset - Dataset for 3D medical volumes.

Handles NIfTI volumes, DICOM series, and other 3D medical imaging data with support for different slice orientations and affine preservation.

class datamint.dataset.volume_dataset.VolumeDataset(project=None, resources=None, auto_update=True, api_key=None, server_url=None, return_metainfo=True, return_segmentations=True, return_as_semantic_segmentation=False, semantic_seg_merge_strategy=None, alb_transform=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, allow_external_annotations=False, image_labels_merge_strategy=None, image_categories_merge_strategy=None)

Bases: MultiFrameDataset

Dataset for 3D medical volumes.

Handles NIfTI (3D/4D), DICOM series, and other volumetric data. Inherits multi-frame loading and augmentation from MultiFrameDataset.

Parameters:

  • project (str | Project | None)

  • resources (Sequence[Resource] | None)

  • auto_update (bool)

  • api_key (str | None)

  • server_url (str | None)

  • return_metainfo (bool)

  • return_segmentations (bool)

  • return_as_semantic_segmentation (bool)

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • alb_transform (Callable | BaseCompose | None)

  • include_unannotated (bool)

  • include_annotators (list[str] | None)

  • exclude_annotators (list[str] | None)

  • include_segmentation_names (list[str] | None)

  • exclude_segmentation_names (list[str] | None)

  • include_image_label_names (list[str] | None)

  • exclude_image_label_names (list[str] | None)

  • include_frame_label_names (list[str] | None)

  • exclude_frame_label_names (list[str] | None)

  • allow_external_annotations (bool)

  • image_labels_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • image_categories_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

slice(axis='axial')

Create a 2D dataset by slicing this volume along an axis.

Each 3D volume is expanded into multiple 2D slices, one per depth index along the given axis. The returned dataset yields 2D items with shape (C, H, W) instead of (C, D, H, W).

Parsed volumes are cached to disk as gzip-compressed .npy.gz files. A shared in-memory LRU cache also keeps recently used full volumes to avoid repeated decompression when iterating neighboring slices.

Parameters:

axis (str | int) – Slice orientation. One of 'axial' (depth), 'coronal' (height), 'sagittal' (width), or an integer axis index (0–2).

Return type:

SlicedVolumeDataset

Returns:

A SlicedVolumeDataset that iterates over individual 2D slices.

Example:

vol_ds = VolumeDataset(project='my_ct_project')
sliced = vol_ds.slice(axis='axial')
print(len(sliced))  # total number of axial slices across all volumes
item = sliced[0]
print(item['image'].shape)  # (C, H, W)

VideoDataset - Dataset for video medical data.

Handles video files (MP4, AVI, etc.) and multi-frame DICOM data from modalities like ultrasound (US), angiography (XA), and fluoroscopy (RF).

class datamint.dataset.video_dataset.VideoDataset(project=None, resources=None, auto_update=True, api_key=None, server_url=None, return_metainfo=True, return_segmentations=True, return_as_semantic_segmentation=False, semantic_seg_merge_strategy=None, alb_transform=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, allow_external_annotations=False, image_labels_merge_strategy=None, image_categories_merge_strategy=None)

Bases: MultiFrameDataset

Dataset for video medical data.

Each item is a full video with shape (C, N, H, W) where N is the number of frames. Inherits multi-frame loading and augmentation from MultiFrameDataset.

Supports video files (MP4, AVI, MOV) and multi-frame DICOM from temporal modalities (ultrasound, angiography, fluoroscopy).

Example:

ds = VideoDataset(project='my_ultrasound_project')
item = ds[0]
print(item['image'].shape)  # (C, N, H, W)

# Iterate frame-by-frame
frame_ds = ds.frame_by_frame()
print(frame_ds[0]['image'].shape)  # (C, H, W)
Parameters:

  • project (str | Project | None)

  • resources (Sequence[Resource] | None)

  • auto_update (bool)

  • api_key (str | None)

  • server_url (str | None)

  • return_metainfo (bool)

  • return_segmentations (bool)

  • return_as_semantic_segmentation (bool)

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • alb_transform (Callable | BaseCompose | None)

  • include_unannotated (bool)

  • include_annotators (list[str] | None)

  • exclude_annotators (list[str] | None)

  • include_segmentation_names (list[str] | None)

  • exclude_segmentation_names (list[str] | None)

  • include_image_label_names (list[str] | None)

  • exclude_image_label_names (list[str] | None)

  • include_frame_label_names (list[str] | None)

  • exclude_frame_label_names (list[str] | None)

  • allow_external_annotations (bool)

  • image_labels_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

  • image_categories_merge_strategy (Literal['union', 'intersection', 'mode'] | None)

frame_by_frame()

Create a 2D dataset iterating over individual video frames.

Each video is expanded into N individual frames. The returned dataset yields 2D items with shape (C, H, W) instead of (C, N, H, W).

Parsed frames are cached to disk as gzip-compressed .npy.gz files.

Return type:

SlicedVideoDataset

Returns:

A SlicedVideoDataset that iterates over individual frames.

Example:

vid_ds = VideoDataset(project='my_ultrasound_project')
frame_ds = vid_ds.frame_by_frame()
print(len(frame_ds))  # total number of frames across all videos
item = frame_ds[0]
print(item['image'].shape)  # (C, H, W)

Sliced Datasets

SlicedVolumeDataset - 2D dataset created by slicing a VolumeDataset along an axis.

Provides a way to iterate over individual 2D slices from 3D volume data, enabling training of 2D models on volumetric medical imaging data.

class datamint.dataset.sliced_dataset.SlicedVolumeDataset(*args, slice_axis='axial', **kwargs)

Bases: DatamintBaseDataset

2D dataset created by slicing a VolumeDataset along an axis.

Each item corresponds to a single 2D slice from a 3D volume. The __getitem__ returns arrays with shape (C, H, W) for images and (num_instances, H, W) or (num_labels+1, H, W) for segmentations.

Can be instantiated directly with all the same parameters as DatamintBaseDataset plus slice_axis, or created from an already-loaded dataset via the from_dataset() factory classmethod (which avoids additional server calls).

Parameters:

  • project – Project name, Project object, or None. Mutually exclusive with resources.

  • resources – List of Resource objects, or None. Mutually exclusive with project.

  • slice_axis (Literal['axial', 'sagittal', 'coronal'] | int) – Slice orientation. One of 'axial' (depth), 'coronal' (height), 'sagittal' (width), or an integer axis index (0–2).

:param See DatamintBaseDataset for all remaining parameters.:

__getitem__(index)

Get a 2D slice item with full processing.

Returns dict with: - ‘image’: np.ndarray or Tensor of shape (C, H, W). - ‘segmentations’ (if enabled): segmentation masks with depth dimension removed. - ‘image_labels’: dict of annotator -> label tensor.

Parameters:

index (int)

Return type:

dict[str, Any]

apply_alb_transform(img, segmentations)

Apply 2D albumentations transform to a single-slice image and masks.

Uses the same approach as ImageDataset: treats the data as 2D.

Parameters:

  • img (ndarray) – Image array of shape (C, 1, H, W) or (C, H, W).

  • segmentations (dict[str, ndarray]) – Dict of author -> mask arrays of shape (#instances, 1, H, W) or (#instances, H, W).

Return type:

dict[str, Any]

Returns:

Dict with transformed ‘image’ and ‘segmentations’.

classmethod from_dataset(parent_dataset, slice_axis='axial')

Create a SlicedVolumeDataset from an existing dataset without additional server calls.

Copies all configuration, label mappings, and already-loaded resources from parent_dataset, then expands them into per-slice proxy resources. Use this factory when you already have a loaded dataset and want to obtain 2D slices without triggering new API requests.

Parameters:

  • parent_dataset (DatamintBaseDataset) – The source DatamintBaseDataset (e.g. VolumeDataset) providing resources, annotations, and configuration.

  • slice_axis (Literal['axial', 'sagittal', 'coronal'] | int) – Slice orientation. One of 'axial' (depth), 'coronal' (height), 'sagittal' (width), or an integer axis index (0–2).

Return type:

SlicedVolumeDataset

Returns:

A new SlicedVolumeDataset instance.

SlicedVideoDataset - 2D dataset created by iterating over frames of a VideoDataset.

Provides a way to iterate over individual 2D frames from video data, enabling training of 2D models on temporal medical imaging data.

class datamint.dataset.sliced_video_dataset.SlicedVideoDataset(*args, **kwargs)

Bases: DatamintBaseDataset

2D dataset created by iterating over frames of a video.

Each item corresponds to a single frame from a video. The __getitem__ returns arrays with shape (C, H, W) for images and (num_instances, H, W) or (num_labels+1, H, W) for segmentations.

Can be instantiated directly with all the same parameters as DatamintBaseDataset, or created from an already-loaded dataset via the from_dataset() factory classmethod (which avoids additional server calls).

__getitem__(index)

Get a single frame item with full processing.

Returns dict with: - 'image': np.ndarray or Tensor of shape (C, H, W). - 'segmentations' (if enabled): segmentation masks of shape (num_instances, H, W) or (num_labels+1, H, W). - 'image_labels': dict of annotator -> label tensor.

Parameters:

index (int)

Return type:

dict[str, Any]

apply_alb_transform(img, segmentations)

Apply 2D albumentations transform to a single frame and masks.

Parameters:

  • img (ndarray) – Image array of shape (C, H, W).

  • segmentations (dict[str, ndarray]) – Dict of author -> mask arrays of shape (#instances, 1, H, W) or (#instances, H, W).

Return type:

dict[str, Any]

Returns:

Dict with transformed 'image' and 'segmentations'.

classmethod from_dataset(parent_dataset)

Create a SlicedVideoDataset from an existing dataset without additional server calls.

Copies all configuration, label mappings, and already-loaded resources from parent_dataset, then expands them into per-frame proxy resources.

Parameters:

parent_dataset (DatamintBaseDataset) – The source dataset (e.g. VideoDataset).

Return type:

SlicedVideoDataset

Returns:

A new SlicedVideoDataset instance.

Legacy Classes (Deprecated)

Deprecated since version The: classes below are kept for backwards compatibility and may be removed in a future release. Use ImageDataset or VolumeDataset instead.

class datamint.dataset.dataset.DatamintDataset(project_name, root=None, auto_update=True, api_key=None, server_url=None, return_dicom=False, return_metainfo=True, return_frame_by_frame=False, return_annotations=True, return_segmentations=True, return_as_semantic_segmentation=False, image_transform=None, mask_transform=None, alb_transform=None, semantic_seg_merge_strategy=None, include_unannotated=True, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None, all_annotations=False)

Bases: DatamintBaseDataset

This Dataset class extends the DatamintBaseDataset class to be easily used with PyTorch. In addition to that, it has functionality to better process annotations and segmentations.

Note

Import using from datamint import Dataset.

Parameters:

  • root (str | None) – Root directory of dataset where data already exists or will be downloaded.

  • project_name (str) – Name of the project to download.

  • auto_update (bool) – If True, the dataset will be checked for updates and downloaded if necessary.

  • api_key (str | None) – API key to access the Datamint API. If not provided, it will look for the environment variable ‘DATAMINT_API_KEY’. Not necessary if you don’t want to download/update the dataset.

  • return_dicom (bool) – If True, the DICOM object will be returned, if the image is a DICOM file.

  • return_metainfo (bool) – If True, the metainfo of the image will be returned.

  • return_annotations (bool) – If True, the annotations of the image will be returned.

  • return_frame_by_frame (bool) – If True, each frame of a video/DICOM/3d-image will be returned separately.

  • include_unannotated (bool) – If True, images without annotations will be included. If False, images without annotations will be discarded.

  • all_annotations (bool) – If True, all annotations will be downloaded, including the ones that are not set as closed/done.

  • server_url (str | None) – URL of the Datamint server. If not provided, it will use the default server.

  • return_segmentations (bool) – If True (default), the segmentations of the image will be returned in the ‘segmentations’ key.

  • return_as_semantic_segmentation (bool) – If True, the segmentations will be returned as semantic segmentation.

  • image_transform (Callable[[Tensor], Any] | None) – A function to transform the image.

  • mask_transform (Callable[[Tensor], Any] | None) – A function to transform the mask.

  • semantic_seg_merge_strategy (Literal['union', 'intersection', 'mode'] | None) – If not None, the segmentations will be merged using this strategy. Possible values are ‘union’, ‘intersection’, ‘mode’.

  • include_annotators (list[str] | None) – List of annotators to include. If None, all annotators will be included. See parameter exclude_annotators.

  • exclude_annotators (list[str] | None) – List of annotators to exclude. If None, no annotators will be excluded. See parameter include_annotators.

  • include_segmentation_names (list[str] | None) – List of segmentation names to include. If None, all segmentations will be included.

  • exclude_segmentation_names (list[str] | None) – List of segmentation names to exclude. If None, no segmentations will be excluded.

  • include_image_label_names (list[str] | None) – List of image label names to include. If None, all image labels will be included.

  • exclude_image_label_names (list[str] | None) – List of image label names to exclude. If None, no image labels will be excluded.

  • include_frame_label_names (list[str] | None) – List of frame label names to include. If None, all frame labels will be included.

  • exclude_frame_label_names (list[str] | None) – List of frame label names to exclude. If None, no frame labels will be excluded.

  • all_annotations – If True, all annotations will be downloaded, including the ones that are not set as closed/done.

  • alb_transform (BasicTransform | None)

__getitem__(index)

Get the item at the given index.

Parameters:

index (int) – Index of the item to return.

Returns:

A dictionary with the following keys:

  • ’image’ (Tensor): Tensor of shape (C, H, W) or (N, C, H, W), depending on self.return_frame_by_frame. If self.return_as_semantic_segmentation is True, the image is a tensor of shape (N, L, H, W) or (L, H, W), where L is the number of segmentation labels + 1 (background): L=len(self.segmentation_labels_set)+1.

  • ’metainfo’ (dict): Dictionary with metadata information.

  • ’segmentations’ (dict[str, list[Tensor]] or dict[str,Tensor] or Tensor): Segmentation masks, depending on the configuration of parameters self.return_segmentations, self.return_as_semantic_segmentation, self.return_frame_by_frame, self.semantic_seg_merge_strategy.

  • ’seg_labels’ (dict[str, list[Tensor]] or Tensor): Segmentation labels with the same length as segmentations.

  • ’frame_labels’ (dict[str, Tensor]): Frame-level labels.

  • ’image_labels’ (dict[str, Tensor]): Image-level labels.

Return type:

dict[str, Any]

class datamint.dataset.base_dataset.DatamintBaseDataset(project_name, root=None, auto_update=True, api_key=None, server_url=None, return_dicom=False, return_metainfo=True, return_annotations=True, return_frame_by_frame=False, include_unannotated=True, all_annotations=False, include_annotators=None, exclude_annotators=None, include_segmentation_names=None, exclude_segmentation_names=None, include_image_label_names=None, exclude_image_label_names=None, include_frame_label_names=None, exclude_frame_label_names=None)

Class to download and load datasets from the Datamint API.

Parameters:

  • project_name (str) – Name of the project to download.

  • root (str | None) – Root directory of dataset where data already exists or will be downloaded.

  • auto_update (bool) – If True, the dataset will be checked for updates and downloaded if necessary.

  • api_key (str | None) – API key to access the Datamint API. If not provided, it will look for the environment variable ‘DATAMINT_API_KEY’. Not necessary if you don’t want to download/update the dataset.

  • return_dicom (bool) – If True, the DICOM object will be returned, if the image is a DICOM file.

  • return_metainfo (bool) – If True, the metainfo of the image will be returned.

  • return_annotations (bool) – If True, the annotations of the image will be returned.

  • return_frame_by_frame (bool) – If True, each frame of a video/DICOM/3d-image will be returned separately.

  • include_unannotated (bool) – If True, images without annotations will be included.

  • all_annotations (bool) – If True, all annotations will be downloaded, including the ones that are not set as closed/done.

  • server_url (str | None) – URL of the Datamint server. If not provided, it will use the default server.

  • include_annotators (list[str] | None) – List of annotators to include. If None, all annotators will be included.

  • exclude_annotators (list[str] | None) – List of annotators to exclude. If None, no annotators will be excluded.

  • include_segmentation_names (list[str] | None) – List of segmentation names to include. If None, all segmentations will be included.

  • exclude_segmentation_names (list[str] | None) – List of segmentation names to exclude. If None, no segmentations will be excluded.

  • include_image_label_names (list[str] | None) – List of image label names to include. If None, all image labels will be included.

  • exclude_image_label_names (list[str] | None) – List of image label names to exclude. If None, no image labels will be excluded.

  • include_frame_label_names (list[str] | None) – List of frame label names to include. If None, all frame labels will be included.

  • exclude_frame_label_names (list[str] | None) – List of frame label names to exclude. If None, no frame labels will be excluded.

__add__(other)

Concatenate datasets.

__getitem__(index)

Get item at index.

Parameters:

index (int) – Index

Return type:

dict[str, Tensor | FileDataset | dict | list]

Returns:

A dictionary containing ‘image’, ‘metainfo’ and ‘annotations’ keys.

__iter__()

Iterate over dataset items.

__len__()

Return dataset length.

Return type:

int

__repr__()

String representation of the dataset.

Return type:

str

property frame_categories_set: list[tuple[str, str]]

Returns the set of categories in the dataset (multi-class tasks).

property frame_labels_set: list[str]

Returns the set of independent labels in the dataset (multi-label tasks).

get_annotations(index, type='all', scope='all')

Returns the annotations of the image at the given index.

Parameters:

  • index (int) – Index of the image.

  • type (Literal['label', 'category', 'segmentation', 'all']) – The type of the annotations. Can be ‘label’, ‘category’, ‘segmentation’ or ‘all’.

  • scope (Literal['frame', 'image', 'all']) – The scope of the annotations. Can be ‘frame’, ‘image’ or ‘all’.

Return type:

list[Annotation]

Returns:

The annotations of the image.

get_collate_fn()

Get collate function for DataLoader.

Return type:

Callable

get_dataloader(*args, **kwargs)

Returns a DataLoader for the dataset with proper collate function.

Parameters:

  • *args – Positional arguments for the DataLoader.

  • **kwargs – Keyword arguments for the DataLoader.

Return type:

DataLoader

Returns:

DataLoader instance with custom collate function.

get_framelabel_distribution(normalize=False)

Returns the distribution of frame labels in the dataset.

Parameters:

normalize (bool)

Return type:

dict[str, float]

get_info()

Get project information from API.

Return type:

dict

get_resources_ids()

Get list of resource IDs.

Return type:

list[str]

get_segmentationlabel_distribution(normalize=False)

Returns the distribution of segmentation labels in the dataset.

Parameters:

normalize (bool)

Return type:

dict[str, float]

property image_categories_set: list[tuple[str, str]]

Returns the set of categories in the dataset (multi-class tasks).

property image_labels_set: list[str]

Returns the set of independent labels in the dataset (multi-label tasks).

static read_number_of_frames(filepath)

Read the number of frames in a file.

Parameters:

filepath (str)

Return type:

int

property segmentation_labels_set: list[str]

Returns the set of segmentation labels in the dataset.

subset(indices)

Create a subset of the dataset.

Parameters:

indices (list[int]) – List of indices to include in the subset.

Return type:

DatamintBaseDataset

Returns:

Self with updated subset indices.

exception datamint.dataset.base_dataset.DatamintDatasetException