datamint 1.9.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

datamint/dataset/dataset.py

@@ -7,7 +7,7 @@ import numpy as np
 import logging
 from PIL import Image
 import albumentations
-from datamint.dataset.annotation import Annotation
+from datamint.entities.annotation import Annotation
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -155,7 +155,7 @@ class DatamintDataset(DatamintBaseDataset):
             # FIXME: avoid enforcing resizing the mask
             seg = (Image.open(segfilepath)
                    .convert('L')
-                   .resize((w, h), Image.NEAREST)
+                   .resize((w, h), Image.Resampling.NEAREST)
                    )
             seg = np.array(seg)
 

datamint/entities/__init__.py

@@ -0,0 +1,20 @@
+"""DataMint entities package."""
+
+from .annotation import Annotation
+from .base_entity import BaseEntity
+from .channel import Channel, ChannelResourceData
+from .project import Project
+from .resource import Resource
+from .user import User  # new export
+from .datasetinfo import DatasetInfo
+
+__all__ = [
+    'Annotation',
+    'BaseEntity',
+    'Channel',
+    'ChannelResourceData',
+    'Project',
+    'Resource',
+    "User",
+    'DatasetInfo',
+]

datamint/entities/annotation.py

@@ -0,0 +1,178 @@
+# filepath: datamint/entities/annotation.py
+"""Annotation entity module for DataMint API.
+
+This module defines the Annotation model used to represent annotation
+records returned by the DataMint API.
+"""
+
+from typing import Any
+import logging
+from .base_entity import BaseEntity, MISSING_FIELD
+from pydantic import Field
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+# Map API field names to class attributes
+_FIELD_MAPPING = {
+    'type': 'annotation_type',
+    'name': 'identifier',
+    'added_by': 'created_by',
+    'index': 'frame_index',
+}
+
+
+class Annotation(BaseEntity):
+    """Pydantic Model representing a DataMint annotation.
+
+    Attributes:
+        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, masks) 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.
+    """
+
+    id: str
+    identifier: str
+    scope: str
+    frame_index: int | None
+    annotation_type: str
+    text_value: str | None
+    numeric_value: float | int | None
+    units: str | None
+    geometry: list | dict | None
+    created_at: str  # ISO timestamp string
+    created_by: str
+    annotation_worklist_id: str | None
+    status: str
+    approved_at: str | None  # ISO timestamp string
+    approved_by: str | None
+    resource_id: str
+    associated_file: str | None
+    deleted: bool
+    deleted_at: str | None  # ISO timestamp string
+    deleted_by: str | None
+    created_by_model: str | None
+    set_name: str | None
+    resource_filename: str | None
+    resource_modality: str | None
+    annotation_worklist_name: str | None
+    user_info: dict | None
+    values: list | None = MISSING_FIELD
+    file: str | None = None  # Add file field for segmentations
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> 'Annotation':
+        """Create an Annotation instance from a dictionary.
+
+        Args:
+            data: Dictionary containing annotation data from API
+
+        Returns:
+            Annotation instance
+        """
+        # Convert field names and filter valid fields
+        converted_data = {}
+        for key, value in data.items():
+            # Map field names if needed
+            mapped_key = _FIELD_MAPPING.get(key, key)
+            converted_data[mapped_key] = value
+
+        if 'scope' not in converted_data:
+            converted_data['scope'] = 'image' if converted_data.get('frame_index') is None else 'frame'
+
+        if converted_data['annotation_type'] in ['segmentation']:
+            if converted_data.get('file') is None:
+                raise ValueError(f"Segmentation annotations must have an associated file. {data}")
+
+        # Create instance with only valid fields
+        valid_fields = {f for f in cls.model_fields.keys()}
+        filtered_data = {k: v for k, v in converted_data.items() if k in valid_fields}
+
+        return cls(**filtered_data)
+
+    @property
+    def type(self) -> str:
+        """Alias for :attr:`annotation_type`."""
+        return self.annotation_type
+
+    @property
+    def name(self) -> str:
+        """Get the annotation name (alias for identifier)."""
+        return self.identifier
+
+    @property
+    def index(self) -> int | None:
+        """Get the frame index (alias for frame_index)."""
+        return self.frame_index
+
+    @property
+    def value(self) -> str | None:
+        """Get the annotation value (for category annotations)."""
+        return self.text_value
+
+    @property
+    def added_by(self) -> str:
+        """Get the creator email (alias for created_by)."""
+        return self.created_by
+
+    def is_segmentation(self) -> bool:
+        """Check if this is a segmentation annotation."""
+        return self.annotation_type == 'segmentation'
+
+    def is_label(self) -> bool:
+        """Check if this is a label annotation."""
+        return self.annotation_type == 'label'
+
+    def is_category(self) -> bool:
+        """Check if this is a category annotation."""
+        return self.annotation_type == 'category'
+
+    def is_frame_scoped(self) -> bool:
+        """Check if this annotation is frame-scoped."""
+        return self.scope == 'frame'
+
+    def is_image_scoped(self) -> bool:
+        """Check if this annotation is image-scoped."""
+        return self.scope == 'image'
+
+    def get_created_datetime(self) -> datetime | None:
+        """
+        Get the creation datetime as a datetime object.
+
+        Returns:
+            datetime object or None if created_at is not set
+        """
+        if isinstance(self.created_at, datetime):
+            return self.created_at
+
+        if self.created_at:
+            try:
+                return datetime.fromisoformat(self.created_at.replace('Z', '+00:00'))
+            except ValueError:
+                logger.warning(f"Could not parse created_at datetime: {self.created_at}")
+        return None

datamint/entities/base_entity.py

@@ -0,0 +1,51 @@
+import logging
+import sys
+from typing import Any
+from pydantic import ConfigDict, BaseModel
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+_LOGGER = logging.getLogger(__name__)
+
+MISSING_FIELD = 'MISSING_FIELD'  # Used when a field is sometimes missing for one endpoint but not on another endpoint
+
+# Track logged warnings to avoid duplicates
+_LOGGED_WARNINGS: set[tuple[str, str]] = set()
+
+
+class BaseEntity(BaseModel):
+    """
+    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.
+    """
+
+    model_config = ConfigDict(extra='allow')  # Allow extra fields not defined in the model
+
+    def asdict(self) -> dict[str, Any]:
+        """Convert the entity to a dictionary, including unknown fields."""
+        return self.model_dump(warnings='none')
+
+    def asjson(self) -> str:
+        """Convert the entity to a JSON string, including unknown fields."""
+        return self.model_dump_json(warnings='none')
+
+    def model_post_init(self, __context: Any) -> None:
+        """Handle unknown fields by logging a warning once per class/field combination in debug mode."""
+        if self.__pydantic_extra__ and _LOGGER.isEnabledFor(logging.DEBUG):
+            class_name = self.__class__.__name__
+            
+            have_to_log = False
+            for key in self.__pydantic_extra__.keys():
+                warning_key = (class_name, key)
+                
+                if warning_key not in _LOGGED_WARNINGS:
+                    _LOGGED_WARNINGS.add(warning_key)
+                    have_to_log = True
+            
+            if have_to_log:
+                _LOGGER.warning(f"Unknown fields {list(self.__pydantic_extra__.keys())} found in {class_name}")

datamint/entities/channel.py

@@ -0,0 +1,46 @@
+from pydantic import ConfigDict, BaseModel
+from datetime import datetime
+from datamint.entities.base_entity import BaseEntity
+
+
+class ChannelResourceData(BaseModel):
+    """Represents resource data within a channel.
+    
+    Attributes:
+        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.
+    """
+    model_config = ConfigDict(extra='allow')
+
+    created_by: str
+    customer_id: str
+    resource_id: str
+    resource_file_name: str
+    resource_mimetype: str
+
+
+class Channel(BaseEntity):
+    """Represents a channel containing multiple resources.
+    
+    A channel is a collection of resources grouped together,
+    typically for batch processing or organization purposes.
+    
+    Attributes:
+        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
+    resource_data: list[ChannelResourceData]
+    deleted: bool = False
+    created_at: str | None = None
+    updated_at: str | None = None
+
+    def get_resource_ids(self) -> list[str]:
+        """Get list of all resource IDs in this channel."""
+        return [resource.resource_id for resource in self.resource_data] if self.resource_data else []

datamint/entities/datasetinfo.py

@@ -0,0 +1,22 @@
+"""Project entity module for DataMint API."""
+
+from datetime import datetime
+import logging
+from .base_entity import BaseEntity, MISSING_FIELD
+
+logger = logging.getLogger(__name__)
+
+
+class DatasetInfo(BaseEntity):
+    """Pydantic Model representing a DataMint dataset.
+    """
+
+    id: str
+    name: str
+    created_at: str  # ISO timestamp string
+    created_by: str
+    description: str
+    customer_id: str
+    updated_at: str | None
+    total_resource: int
+    resource_ids: list[str]

datamint/entities/project.py

@@ -0,0 +1,64 @@
+"""Project entity module for DataMint API."""
+
+from datetime import datetime
+import logging
+from .base_entity import BaseEntity, MISSING_FIELD
+
+logger = logging.getLogger(__name__)
+
+
+class Project(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.
+
+    Attributes:
+        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
+        viewable_ai_segs: Optional configuration for viewable AI segments
+        editable_ai_segs: Optional configuration for editable AI segments
+        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
+    """
+    id: str
+    name: str
+    created_at: str  # ISO timestamp string
+    created_by: str
+    dataset_id: str
+    worklist_id: str
+    archived: bool
+    resource_count: int
+    annotated_resource_count: int
+    description: str | None
+    ai_model_id: str | None
+    viewable_ai_segs: list | None
+    editable_ai_segs: list | None
+    closed_resources_count: int = MISSING_FIELD
+    resources_to_annotate_count: int = MISSING_FIELD
+    most_recent_experiment: str | None = MISSING_FIELD  # ISO timestamp string
+    annotators: list[dict] = MISSING_FIELD
+    customer_id: str | None = MISSING_FIELD
+    archived_on: str | None = MISSING_FIELD
+    archived_by: str | None = MISSING_FIELD
+    is_active_learning: bool = MISSING_FIELD
+    two_up_display: bool = MISSING_FIELD
+    require_review: bool = MISSING_FIELD
+
+    @property
+    def url(self) -> str:
+        """Get the URL to access this project in the DataMint web application."""
+        base_url = "https://app.datamint.io/projects/edit"
+        return f"{base_url}/{self.id}"

datamint/entities/resource.py

@@ -0,0 +1,130 @@
+"""Resource entity module for DataMint API."""
+
+from datetime import datetime
+from typing import Optional, Any
+import logging
+from .base_entity import BaseEntity, MISSING_FIELD
+from pydantic import Field
+
+logger = logging.getLogger(__name__)
+
+class Resource(BaseEntity):
+    """Represents a DataMint resource with all its properties and metadata.
+    
+    This class models a resource entity from the DataMint API, containing
+    information about uploaded files, their metadata, and associated projects.
+    
+    Attributes:
+        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
+    """
+    id: str
+    resource_uri: str
+    storage: str
+    location: str
+    upload_channel: str
+    filename: str
+    modality: str
+    mimetype: str
+    size: int
+    upload_mechanism: str
+    customer_id: str
+    status: str
+    created_at: str
+    created_by: str
+    published: bool
+    deleted: bool
+    source_filepath: str | None
+    metadata: dict
+    projects: list[dict] = MISSING_FIELD
+    published_on: str | None
+    published_by: str | None
+    tags: list[str] | None = None
+    publish_transforms: Optional[Any] = None
+    deleted_at: Optional[str] = None
+    deleted_by: Optional[str] = None
+    instance_uid: Optional[str] = None
+    series_uid: Optional[str] = None
+    study_uid: Optional[str] = None
+    patient_id: Optional[str] = None
+    segmentations: Optional[Any] = None  # TODO: Define proper type when spec available
+    measurements: Optional[Any] = None  # TODO: Define proper type when spec available
+    categories: Optional[Any] = None  # TODO: Define proper type when spec available
+    user_info: Optional[dict] = None
+
+    @property
+    def size_mb(self) -> float:
+        """Get file size in megabytes.
+        
+        Returns:
+            File size in MB rounded to 2 decimal places
+        """
+        return round(self.size / (1024 * 1024), 2)
+    
+    def is_dicom(self) -> bool:
+        """Check if the resource is a DICOM file.
+        
+        Returns:
+            True if the resource is a DICOM file, False otherwise
+        """
+        return self.mimetype == 'application/dicom' or self.storage == 'DicomResource'
+    
+    def get_project_names(self) -> list[str]:
+        """Get list of project names this resource belongs to.
+        
+        Returns:
+            List of project names
+        """
+        return [proj['name'] for proj in self.projects]
+    
+    def __str__(self) -> str:
+        """String representation of the resource.
+        
+        Returns:
+            Human-readable string describing the resource
+        """
+        return f"Resource(id='{self.id}', filename='{self.filename}', size={self.size_mb}MB)"
+    
+    def __repr__(self) -> str:
+        """Detailed string representation of the resource.
+        
+        Returns:
+            Detailed string representation for debugging
+        """
+        return (
+            f"Resource(id='{self.id}', filename='{self.filename}', "
+            f"modality='{self.modality}', status='{self.status}', "
+            f"published={self.published})"
+        )

datamint/entities/user.py

@@ -0,0 +1,21 @@
+from .base_entity import BaseEntity
+
+class User(BaseEntity):
+    """User entity model.
+
+    Attributes:
+        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.
+    """
+    email: str
+    firstname: str | None
+    lastname: str | None
+    roles: list[str]
+    customer_id: str
+    created_at: str
+
+    # Potential improvement: convert created_at to datetime for easier comparisons.

datamint/examples/example_projects.py

@@ -1,75 +1,72 @@
 import requests
 import io
-from datamint import APIHandler
+from datamint import Api
 import logging
 from PIL import Image
 import numpy as np
+from datamint.entities import Project, Resource
+from pydicom.data import get_testdata_file
 
 _LOGGER = logging.getLogger(__name__)
 
 
-def _download_pydicom_test_file(filename: str) -> io.BytesIO:
-    """Download a pydicom test file from GitHub and return its content as a BytesIO object."""
-    url = f'https://raw.githubusercontent.com/pydicom/pydicom/master/tests/data/{filename}'
-    response = requests.get(url)
-    response.raise_for_status()
-    content = io.BytesIO(response.content)
-    content.name = filename
-    return content
-
-
 class ProjectMR:
     @staticmethod
-    def upload_resource_emri_small(api: APIHandler = None) -> str:
+    def upload_resource_emri_small(api: Api | None = None) -> Resource:
         if api is None:
-            api = APIHandler()
+            api = Api()
 
-        searched_res = api.get_resources(status='published', tags=['example'], filename='emri_small.dcm')
+        searched_res = api.resources.get_list(status='published',
+                                              tags=['example'],
+                                              filename='emri_small.dcm')
         for res in searched_res:
             _LOGGER.info('Resource already exists.')
-            return res['id']
+            return res
 
-        dcm_content = _download_pydicom_test_file('emri_small.dcm')
+        dcm_path = get_testdata_file("emri_small.dcm",
+                                     read=False)
 
-        _LOGGER.info(f'Uploading resource {dcm_content.name}...')
-        return api.upload_resources(dcm_content,
-                                    anonymize=True,
-                                    publish=True,
-                                    tags=['example'])
+        _LOGGER.info('Uploading resource emri_small.dcm...')
+        resid = api.resources.upload_resource(dcm_path,
+                                              anonymize=False,
+                                              publish=True,
+                                              tags=['example'])
+        return api.resources.get_by_id(resid)
 
     @staticmethod
-    def _upload_annotations(api: APIHandler,
-                            resid: str,
-                            proj) -> None:
+    def _upload_annotations(api: Api,
+                            res: Resource,
+                            proj: Project) -> None:
         _LOGGER.info('Uploading annotations...')
-        proj_id = proj['id']
-        proj_info = api.get_project_by_id(proj_id)
         segurl = 'https://github.com/user-attachments/assets/8c5d7dfe-1b5a-497d-b76e-fe790f09bb90'
         resp = requests.get(segurl, stream=True)
         resp.raise_for_status()
         img = Image.open(io.BytesIO(resp.content)).convert('L')
-        api.upload_segmentations(resid, np.array(img),
-                                 name='object1', frame_index=1,
-                                 worklist_id=proj_info['worklist_id'])
-        api.set_annotation_status(project_id=proj_id,
-                                  resource_id=resid,
-                                  status='closed')
+        api.annotations.upload_segmentations(res, np.array(img),
+                                             name='object1', frame_index=1,
+                                             worklist_id=proj.worklist_id)
+        api.projects.set_work_status(resource=res,
+                                     project=proj,
+                                     status='closed')
 
     @staticmethod
     def create(project_name: str = 'Example Project MR',
-               with_annotations=True) -> str:
-        api = APIHandler()
+               with_annotations=True) -> Project:
+        api = Api()
+
+        res = ProjectMR.upload_resource_emri_small(api)
+        proj = api.projects.get_by_name(name=project_name)
+        if proj:
+            _LOGGER.warning(f'Project {project_name} already exists. Returning it without modifications...')
+            return proj
 
-        resid = ProjectMR.upload_resource_emri_small(api)
-        proj = api.get_project_by_name(project_name)
-        if 'id' in proj:
-            msg = f'Project {project_name} already exists. Delete it first or choose another name.'
-            raise ValueError(msg)
         _LOGGER.info(f'Creating project {project_name}...')
-        proj = api.create_project(name=project_name,
-                                  description='This is an example project',
-                                  resources_ids=[resid])
+        projid = api.projects.create(name=project_name,
+                                     description='This is an example project',
+                                     resources_ids=[res.id])
+        proj = api.projects.get_by_id(projid)
+
         if with_annotations:
-            ProjectMR._upload_annotations(api, resid, proj)
+            ProjectMR._upload_annotations(api, res, proj)
 
-        return proj['id']
+        return proj