datamint 2.3.3__py3-none-any.whl → 2.9.0__py3-none-any.whl

datamint/entities/annotations/image_segmentation.py

@@ -0,0 +1,252 @@
+"""Image segmentation annotation entity module for DataMint API.
+
+This module defines the ImageSegmentation class for representing 2D segmentation
+annotations in medical images.
+"""
+
+from .annotation import Annotation
+from datamint.api.dto import AnnotationType
+import numpy as np
+from PIL import Image
+from pydantic import PrivateAttr
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ImageSegmentation(Annotation):
+    """
+    Image-level (2D) segmentation annotation entity.
+    
+    Represents a 2D segmentation mask for a single 2d image.
+    Supports both binary segmentation (single class) and multi-class 
+    semantic segmentation.
+    
+    This class provides factory methods to create annotations from numpy 
+    arrays or PIL Images, which can then be uploaded via AnnotationsApi.
+    
+    Example:
+        >>> # From binary mask
+        >>> mask = np.zeros((256, 256), dtype=np.uint8)
+        >>> mask[100:150, 100:150] = 1  # lesion region
+        >>> img_seg = ImageSegmentation.from_mask(
+        ...     mask=mask,
+        ...     name='lesion'
+        ... )
+        >>> 
+        >>> # Upload via API
+        >>> api.annotations.upload_segmentations(
+        ...     resource='resource_id',
+        ...     file_path=img_seg.mask,
+        ...     name=img_seg.name
+        ... )
+    """
+
+    _mask: np.ndarray | Image.Image | None = PrivateAttr(default=None)
+    _class_name: str | None = PrivateAttr(default=None)
+
+    def __init__(self,
+                 name: str | None = None,
+                 mask: np.ndarray | Image.Image | None = None,
+                 **kwargs):
+        """
+        Initialize an ImageSegmentation annotation.
+        
+        Args:
+            name: The name/label for this segmentation class
+            mask: Optional 2D numpy array or PIL Image containing the segmentation mask
+            **kwargs: Additional fields passed to parent Annotation class
+        """
+        super().__init__(
+            identifier=name or "",
+            scope='image',
+            annotation_type=AnnotationType.SEGMENTATION,
+            **kwargs
+        )
+        
+        self._mask = mask
+        self._class_name = name
+
+    @classmethod
+    def from_mask(cls,
+                  mask: np.ndarray | Image.Image,
+                  name: str,
+                  **kwargs) -> 'ImageSegmentation':
+        """
+        Create ImageSegmentation from a binary or class mask.
+        
+        Args:
+            mask: 2D numpy array (H x W) with integer labels or binary values,
+                or a PIL Image
+            name: The name/label for this segmentation
+            **kwargs: Additional annotation fields (imported_from, model_id, etc.)
+        
+        Returns:
+            ImageSegmentation instance ready for upload
+        
+        Raises:
+            ValueError: If mask shape is invalid or data types are incorrect
+        
+        Example:
+            >>> mask = np.zeros((512, 512), dtype=np.uint8)
+            >>> mask[200:300, 200:300] = 255  # binary mask
+            >>> img_seg = ImageSegmentation.from_mask(
+            ...     mask=mask,
+            ...     name='tumor',
+            ... )
+        """
+        # Convert PIL Image to numpy if needed
+        if isinstance(mask, Image.Image):
+            mask_array = np.array(mask)
+        else:
+            mask_array = mask
+        
+        # Validate mask array
+        mask_array = cls._validate_mask_array(mask_array)
+        
+        instance = cls(
+            name=name,
+            mask=mask_array,
+            **kwargs
+        )
+        
+        return instance
+
+    @staticmethod
+    def _validate_mask_array(arr: np.ndarray) -> np.ndarray:
+        """
+        Validate mask array shape and dtype.
+        
+        Args:
+            arr: Input array to validate
+        
+        Returns:
+            Validated array (possibly with dtype conversion)
+        
+        Raises:
+            ValueError: If array is invalid
+        """
+        if not isinstance(arr, np.ndarray):
+            raise ValueError(f"Expected numpy array, got {type(arr)}")
+        
+        # Check dimensionality - should be 2D (H x W)
+        if arr.ndim != 2:
+            raise ValueError(
+                f"Mask must be 2D (H x W), got shape {arr.shape}"
+            )
+        
+        # Check dtype - convert floats to int if they're effectively integers
+        if np.issubdtype(arr.dtype, np.floating):
+            if not np.allclose(arr, arr.astype(int)):
+                raise ValueError(
+                    "Mask array contains non-integer float values"
+                )
+            arr = arr.astype(np.uint8)
+        elif not np.issubdtype(arr.dtype, np.integer):
+            raise ValueError(
+                f"Mask must have integer dtype, got {arr.dtype}"
+            )
+        
+        # Check for negative values
+        if np.any(arr < 0):
+            raise ValueError("Mask array contains negative values")
+        
+        return arr
+
+    @property
+    def mask(self) -> np.ndarray | None:
+        """
+        Get the stored segmentation mask.
+        
+        Returns:
+            2D numpy array or None if not stored
+        """
+        return self._mask
+
+    @property
+    def mask_shape(self) -> tuple[int, int] | None:
+        """
+        Get the shape of the stored mask.
+        
+        Returns:
+            Shape tuple (H, W) or None if no mask stored
+        """
+        if self._mask is None:
+            return None
+        
+        if isinstance(self._mask, Image.Image):
+            return (self._mask.height, self._mask.width)
+        
+        return self._mask.shape
+
+    @property
+    def class_name(self) -> str | None:
+        """
+        Get the class name for this segmentation.
+        
+        Returns:
+            Class name string or None
+        """
+        return self._class_name
+
+    @property
+    def name(self) -> str | None:
+        """
+        Alias for class_name.
+        
+        Returns:
+            Class name string or None
+        """
+        return self._class_name
+
+    def to_pil_image(self) -> Image.Image | None:
+        """
+        Convert the mask to a PIL Image.
+        
+        Returns:
+            PIL Image or None if no mask stored
+        """
+        if self._mask is None:
+            return None
+        
+        if isinstance(self._mask, Image.Image):
+            return self._mask
+        
+        return Image.fromarray(self._mask)
+
+    def get_binary_mask(self, threshold: int = 0) -> np.ndarray | None:
+        """
+        Get a binary version of the mask.
+        
+        Args:
+            threshold: Values above this threshold are set to 1
+        
+        Returns:
+            Binary numpy array (0s and 1s) or None if no mask stored
+        """
+        if self._mask is None:
+            return None
+        
+        if isinstance(self._mask, Image.Image):
+            mask_array = np.array(self._mask)
+        else:
+            mask_array = self._mask
+        
+        return (mask_array > threshold).astype(np.uint8)
+
+    def get_area(self) -> int | None:
+        """
+        Get the area (number of positive pixels) of the mask.
+        
+        Returns:
+            Number of non-zero pixels or None if no mask stored
+        """
+        if self._mask is None:
+            return None
+        
+        if isinstance(self._mask, Image.Image):
+            mask_array = np.array(self._mask)
+        else:
+            mask_array = self._mask
+        
+        return int(np.count_nonzero(mask_array))

datamint/entities/annotations/volume_segmentation.py

@@ -0,0 +1,273 @@
+"""Volume segmentation annotation entity module for DataMint API.
+
+This module defines the VolumeSegmentation class for representing 3D segmentation
+annotations in medical imaging volumes.
+"""
+
+from .annotation import Annotation
+from datamint.api.dto import AnnotationType
+import numpy as np
+from nibabel.nifti1 import Nifti1Image
+from pydantic import PrivateAttr
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VolumeSegmentation(Annotation):
+    """
+    Volume-level segmentation annotation entity.
+    
+    Represents a 3D 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
+        ... )
+    """
+
+    raw_data: bytes | None = None
+
+    _segmentation_data: np.ndarray | Nifti1Image = PrivateAttr()
+    _class_map: dict[int, str] = PrivateAttr()
+
+    
+    def __init__(self,
+                 **kwargs):
+        """
+        Initialize a VolumeSegmentation annotation.
+        
+        Args:
+            **kwargs: Additional fields passed to parent Annotation class
+        """
+        kwargs['scope'] = 'image'
+        kwargs['annotation_type'] = AnnotationType.SEGMENTATION
+        
+        super().__init__(
+            identifier="",
+            **kwargs
+        )
+        
+    @classmethod
+    def from_semantic_segmentation(cls,
+                                   segmentation: np.ndarray | Nifti1Image,
+                                   class_map: dict[int, str] | str,
+                                   **kwargs) -> 'VolumeSegmentation':
+        """
+        Create VolumeSegmentation from semantic segmentation data.
+        
+        Semantic segmentation: each voxel has a single integer label 
+        corresponding to its class.
+        
+        Args:
+            segmentation: 3D numpy array (H x W x D) or Nifti1Image with 
+                integer labels representing classes
+            class_map: 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.)
+        
+        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'``
+            ... )
+        """
+        # Step 1: Convert Nifti1Image to numpy if needed
+        if isinstance(segmentation, Nifti1Image):
+            seg_array = segmentation.get_fdata().astype(np.int32)
+        else:
+            seg_array = segmentation
+        
+        # Step 2: Validate segmentation array
+        seg_array = cls._validate_segmentation_array(seg_array)
+        
+        # Step 3: Standardize class_map to dict[int, str]
+        standardized_class_map = cls._standardize_class_map(class_map, seg_array)
+        
+        instance = cls(**kwargs)
+        
+        instance._segmentation_data = segmentation
+        instance._class_map = standardized_class_map
+        
+        return instance
+
+    @staticmethod
+    def _validate_segmentation_array(arr: np.ndarray) -> np.ndarray:
+        """
+        Validate segmentation array shape and dtype.
+        
+        Args:
+            arr: Input array to validate
+        
+        Returns:
+            Validated array (possibly with dtype conversion)
+        
+        Raises:
+            ValueError: If array is invalid
+        """
+        if not isinstance(arr, np.ndarray):
+            raise ValueError(f"Expected numpy array, got {type(arr)}")
+        
+        # Check dimensionality
+        if arr.ndim != 3:
+            raise ValueError(
+                f"Segmentation must be 3D (H x W x D), got shape {arr.shape}"
+            )
+        
+        # Check dtype
+        if not np.issubdtype(arr.dtype, np.integer):
+            # Try to convert to int
+            if np.issubdtype(arr.dtype, np.floating):
+                # Check if values are effectively integers
+                if not np.allclose(arr, arr.astype(int)):
+                    raise ValueError(
+                        "Segmentation array contains non-integer float values"
+                    )
+                arr = arr.astype(np.int32)
+            else:
+                raise ValueError(
+                    f"Segmentation must have integer dtype, got {arr.dtype}"
+                )
+        
+        # Check for negative values
+        if np.any(arr < 0):
+            raise ValueError("Segmentation array contains negative values")
+        
+        return arr
+
+    @staticmethod
+    def _standardize_class_map(
+        class_map: dict[int, str] | str,
+        segmentation: np.ndarray
+    ) -> dict[int, str]:
+        """
+        Convert class_map to standard dict[int, str] format.
+        
+        Args:
+            class_map: Either a dict or a single class name for binary seg
+            segmentation: The segmentation array to infer labels from
+        
+        Returns:
+            Standardized dictionary mapping labels to class names
+        
+        Raises:
+            ValueError: If class_map format is invalid
+        """
+        if isinstance(class_map, str):
+            # Binary segmentation: assume label 1 = class_map, 0 = background
+            unique_labels = np.unique(segmentation)
+            unique_labels = unique_labels[unique_labels > 0]  # Exclude 0
+            
+            if len(unique_labels) != 1:
+                raise ValueError(
+                    f"Single class name provided but segmentation has "
+                    f"{len(unique_labels)} non-zero labels: {unique_labels.tolist()}"
+                )
+            
+            return {int(unique_labels[0]): class_map}
+        
+        elif isinstance(class_map, dict):
+            # Validate all keys are integers, all values are strings
+            standardized = {}
+            for k, v in class_map.items():
+                if not isinstance(k, (int, np.integer)):
+                    raise ValueError(f"class_map key must be integer, got {type(k)}")
+                if not isinstance(v, str):
+                    raise ValueError(f"class_map value must be string, got {type(v)}")
+                standardized[int(k)] = v
+            
+            return standardized
+        
+        else:
+            raise ValueError(
+                f"class_map must be dict[int, str] or str, got {type(class_map)}"
+            )
+
+
+
+    @property
+    def volume_shape(self) -> 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
+        """
+        if self._segmentation_data is None:
+            return None
+        
+        if isinstance(self._segmentation_data, Nifti1Image):
+            shape = self._segmentation_data.shape
+            return (shape[0], shape[1], shape[2])
+        else:
+            return self._segmentation_data.shape
+
+    @property
+    def class_names(self) -> list[str] | None:
+        """
+        Get list of class names from stored class_map.
+        
+        Returns:
+            List of class names or None if no class_map stored
+        """
+        if self._class_map is None:
+            return None
+        return sorted(self._class_map.values())
+
+    @property
+    def num_classes(self) -> int | None:
+        """
+        Get number of classes in this segmentation.
+        
+        Returns:
+            Number of classes or None if no class_map stored
+        """
+        if self._class_map is None:
+            return None
+        return len(self._class_map)
+
+    @property
+    def class_map(self) -> dict[int, str]:
+        """
+        Get the stored class map.
+        
+        Returns:
+            Dictionary mapping labels to class names, or None
+        """
+        return self._class_map
+
+    @property
+    def segmentation_data(self) -> np.ndarray | Nifti1Image:
+        """
+        Get the stored segmentation data.
+        
+        Returns:
+            Segmentation array/image or None if not stored
+        """
+        return self._segmentation_data
+

datamint/entities/base_entity.py

@@ -31,13 +31,24 @@ class BaseEntity(BaseModel):
     are created through API endpoints.
     """
 
-    model_config = ConfigDict(extra='allow', arbitrary_types_allowed=True)  # Allow extra fields and arbitrary types
+    model_config = ConfigDict(extra='allow',
+                              arbitrary_types_allowed=True,  # Allow extra fields and arbitrary types
+                              ser_json_bytes='base64',
+                              val_json_bytes='base64')
 
     _api: 'EntityBaseApi[Self] | EntityBaseApi' = PrivateAttr()
 
+    def __init__(self, **data):
+        super().__init__(**data)
+        # check attributes for MISSING_FIELD and delete them
+        for field_name in self.__pydantic_fields__.keys():
+            if hasattr(self, field_name) and getattr(self, field_name) == MISSING_FIELD:
+                delattr(self, field_name)
+
     def asdict(self) -> dict[str, Any]:
         """Convert the entity to a dictionary, including unknown fields."""
-        return self.model_dump(warnings='none')
+        d = self.model_dump(warnings='none')
+        return {k: v for k, v in d.items() if v != MISSING_FIELD}
 
     def asjson(self) -> str:
         """Convert the entity to a JSON string, including unknown fields."""
@@ -59,10 +70,13 @@ class BaseEntity(BaseModel):
             if have_to_log:
                 _LOGGER.warning(f"Unknown fields {list(self.__pydantic_extra__.keys())} found in {class_name}")
 
-    @staticmethod
-    def is_attr_missing(value: Any) -> bool:
+    def is_attr_missing(self, attr_name: str) -> bool:
         """Check if a value is the MISSING_FIELD sentinel."""
-        return value == MISSING_FIELD
+        if attr_name not in self.__pydantic_fields__.keys():
+            raise AttributeError(f"Attribute '{attr_name}' not found in entity of type '{self.__class__.__name__}'")
+        if not hasattr(self, attr_name):
+            return True
+        return getattr(self, attr_name) == MISSING_FIELD  # deprecated
 
     def _refresh(self) -> Self:
         """Refresh the entity data from the server.
@@ -88,5 +102,85 @@ class BaseEntity(BaseModel):
         Args:
             attr_name: Name of the attribute to check and ensure
         """
-        if self.is_attr_missing(getattr(self, attr_name)):
+        if attr_name not in self.__pydantic_fields__.keys():
+            raise AttributeError(f"Attribute '{attr_name}' not found in entity of type '{self.__class__.__name__}'")
+
+        if self.is_attr_missing(attr_name):
             self._refresh()
+
+    def has_missing_attrs(self) -> bool:
+        """Check if the entity has any attributes that are MISSING_FIELD.
+
+        Returns:
+            True if any attribute is MISSING_FIELD, False otherwise
+        """
+        return any(self.is_attr_missing(attr_name) for attr_name in self.__pydantic_fields__.keys())
+
+    def _fetch_and_cache_file_data(
+        self,
+        cache_manager: 'Any',  # CacheManager[bytes]
+        data_key: str,
+        version_info: dict[str, Any],
+        download_callback: 'Any',  # Callable[[str | None], bytes]
+        save_path: str | None = None,
+        use_cache: bool = False,
+    ) -> bytes:
+        """Shared logic for fetching and caching file data.
+
+        This method handles the caching strategy for both Resource and Annotation entities.
+
+        Args:
+            cache_manager: The CacheManager instance to use
+            data_key: Key identifying the type of data (e.g., 'image_data', 'annotation_data')
+            version_info: Version information for cache validation
+            download_callback: Function to call to download the file, takes save_path as parameter
+            save_path: Optional path to save the file locally
+            use_cache: If True, uses cached data when available
+
+        Returns:
+            File data as bytes
+        """
+        from pathlib import Path
+
+        # Try to get from cache
+        img_data = None
+        
+        if use_cache:
+            img_data = cache_manager.get(self.id, data_key, version_info)
+            if img_data is not None:
+                _LOGGER.debug(f"Using cached data for {self.__class__.__name__} {self.id}")
+
+        if img_data is None:
+            # Cache miss - fetch from server
+            if use_cache and save_path:
+                # Download directly to save_path, register location in cache metadata
+                _LOGGER.debug(f"Downloading to save_path: {save_path}")
+                Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+                
+                img_data = download_callback(save_path)
+                
+                # Register save_path in cache metadata (no file duplication)
+                cache_manager.register_file_location(
+                    self.id, data_key, save_path, version_info
+                )
+            elif use_cache:
+                # No save_path - download to cache directory
+                cache_path = cache_manager.get_expected_path(self.id, data_key)
+                _LOGGER.debug(f"Downloading to cache: {cache_path}")
+                
+                img_data = download_callback(str(cache_path))
+                
+                # Register in cache metadata
+                cache_manager.set(self.id, data_key, img_data, version_info)
+            else:
+                # No caching - direct download to save_path (or just return bytes)
+                _LOGGER.debug(f"Fetching data from server for {self.__class__.__name__} {self.id}")
+                img_data = download_callback(save_path)
+        elif save_path:
+            # Cached data found, but user wants to save to a specific path
+            _LOGGER.debug(f"Saving cached data to specified path: {save_path}")
+            Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(save_path, 'wb') as f:
+                f.write(img_data)
+
+        return img_data