feature/dimension-properties

bioio_base/image_container.py

@@ -10,7 +10,13 @@
 
 from .dimensions import Dimensions
 from .standard_metadata import StandardMetadata
-from .types import ImageLike, PhysicalPixelSizes, Scale, TimeInterval
+from .types import (
+    DimensionProperties,
+    ImageLike,
+    PhysicalPixelSizes,
+    Scale,
+    TimeInterval,
+)
 
 ###############################################################################
 
@@ -126,6 +132,11 @@ def physical_pixel_sizes(self) -> PhysicalPixelSizes:
     def scale(self) -> Scale:
         pass
 
+    @property
+    @abstractmethod
+    def dimension_properties(self) -> DimensionProperties:
+        pass
+
     @property
     @abstractmethod
     def time_interval(self) -> TimeInterval:

bioio_base/reader.py

@@ -24,7 +24,13 @@
     timelapse_interval,
     total_time_duration,
 )
-from .types import PhysicalPixelSizes, Scale, TimeInterval
+from .types import (
+    DimensionProperties,
+    DimensionProperty,
+    PhysicalPixelSizes,
+    Scale,
+    TimeInterval,
+)
 
 ###############################################################################
 
@@ -915,6 +921,43 @@ def scale(self) -> Scale:
             X=self.physical_pixel_sizes.X,
         )
 
+    @property
+    def dimension_properties(self) -> DimensionProperties:
+        """
+        Per-dimension metadata describing semantic meaning and units.
+
+        Units
+        -----
+        The base Reader does *not* assign units. All units are
+        left as None. Reader implementations (e.g. OME-Zarr,
+        BioFormats, TIFF) are responsible for attaching pint.Unit
+        instances via the shared registry `bioio_base.types.ureg`.
+        """
+        s = self.scale
+
+        return DimensionProperties(
+            T=DimensionProperty(
+                type="time" if s.T is not None else None,
+                unit=None,
+            ),
+            C=DimensionProperty(
+                type="channel" if s.C is not None else None,
+                unit=None,
+            ),
+            Z=DimensionProperty(
+                type="space" if s.Z is not None else None,
+                unit=None,
+            ),
+            Y=DimensionProperty(
+                type="space" if s.Y is not None else None,
+                unit=None,
+            ),
+            X=DimensionProperty(
+                type="space" if s.X is not None else None,
+                unit=None,
+            ),
+        )
+
     def get_mosaic_tile_position(
         self, mosaic_tile_index: int, **kwargs: int
     ) -> Tuple[int, int]:

bioio_base/standard_metadata.py

@@ -43,7 +43,7 @@ class StandardMetadata:
     imaged_by: Optional[str]
         The experimentalist who produced this data.
 
-    imaging_date: Optional[str]
+    imaging_datetime: Optional[datetime]
         Date this file was imaged.
 
     objective: Optional[str]

bioio_base/types.py

@@ -3,25 +3,46 @@
 
 from datetime import timedelta
 from pathlib import Path
-from typing import List, NamedTuple, Optional, Union
+from typing import List, NamedTuple, Optional, TypeAlias, Union
 
 import dask.array as da
 import numpy as np
+import pint
 import xarray as xr
+from ome_types.units import ureg as ome_ureg
 
 ###############################################################################
-
 # IO Types
+###############################################################################
+
 PathLike = Union[str, Path]
 ArrayLike = Union[np.ndarray, da.Array]
 MetaArrayLike = Union[ArrayLike, xr.DataArray]
 ImageLike = Union[
-    PathLike, ArrayLike, MetaArrayLike, List[MetaArrayLike], List[PathLike]
+    PathLike,
+    ArrayLike,
+    MetaArrayLike,
+    List[MetaArrayLike],
+    List[PathLike],
 ]
 
+# Public type aliases for units
+UnitRegistry: TypeAlias = pint.UnitRegistry
+Unit: TypeAlias = pint.Unit
 
+# Canonical global registry for BioIO, shared with OME-types
+ureg: UnitRegistry = ome_ureg
+
+###############################################################################
 # Image Utility Types
+###############################################################################
+
+
 class PhysicalPixelSizes(NamedTuple):
+    """
+    Physical pixel sizes along the Z, Y, and X axes.
+    """
+
     Z: Optional[float]
     Y: Optional[float]
     X: Optional[float]
@@ -31,8 +52,45 @@ class PhysicalPixelSizes(NamedTuple):
 
 
 class Scale(NamedTuple):
+    """
+    Per-dimension scale factors for T, C, Z, Y, X.
+    """
+
     T: Optional[float]
     C: Optional[float]
     Z: Optional[float]
     Y: Optional[float]
     X: Optional[float]
+
+
+class DimensionProperty(NamedTuple):
+    """
+    Per-dimension metadata descriptor.
+
+    Parameters
+    ----------
+    type:
+        Semantic meaning of the dimension (e.g. "space", "time", "channel").
+        This module does not enforce a fixed vocabulary.
+
+    unit:
+        A `pint.Unit` from the shared OME/BioIO unit registry (`ureg`),
+        or None if the dimension unknown.
+    """
+
+    type: Optional[str]
+    unit: Optional[Unit]
+
+
+class DimensionProperties(NamedTuple):
+    """
+    Container for dimension properties for all supported dims.
+
+    These align with the standard bioio dimension order (T, C, Z, Y, X).
+    """
+
+    T: DimensionProperty
+    C: DimensionProperty
+    Z: DimensionProperty
+    Y: DimensionProperty
+    X: DimensionProperty

pyproject.toml

@@ -32,8 +32,10 @@ dependencies = [
   "dask[array,distributed]>=2021.4.1,!=2022.5.1",
   "fsspec>=2021.4.0,!=2022.7.0",
   "numpy>=1.21.0",
-  "ome-types>=0.2",
+  "ome-types[pint]>=0.2",
+  "pint", # for typing units
   "xarray>=2022.6.0",
+
 ]
 
 [project.urls]