micro-reader 0.1.0__tar.gz → 0.2.1__tar.gz

{micro_reader-0.1.0 → micro_reader-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: micro-reader
-Version: 0.1.0
+Version: 0.2.1
 Summary: Low-level, memory-bounded pixel reading for microscopy formats: read exactly the rectangle you ask for.
 Project-URL: Homepage, https://github.com/bugraoezdemir/micro-reader
 Project-URL: Source, https://github.com/bugraoezdemir/micro-reader

{micro_reader-0.1.0 → micro_reader-0.2.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "micro-reader"
-version = "0.1.0"
+version = "0.2.1"
 description = "Low-level, memory-bounded pixel reading for microscopy formats: read exactly the rectangle you ask for."
 readme = "README.md"
 requires-python = ">=3.11"

{micro_reader-0.1.0 → micro_reader-0.2.1}/src/micro_reader/__init__.py

@@ -10,9 +10,10 @@ from ._version import __version__
 from ._base import INDEX_NAMES, PLATE_INDICES, SAMPLED_INDICES, File, Image, ReadStats
 from ._metadata import Channel, Metadata, Quantity
 from ._plate import Acquisition, Field, Plate, Well
-from ._errors import (CompanionWarning, CompositeWarning, CorruptFileError, MicroReaderError,
-                      MissingImagesWarning, PlateLayoutWarning, SkewedGridWarning,
-                      UnsupportedFormatError)
+from ._spatial import Axis, Collection, CoordinateSystem, Transformation
+from ._errors import (CompanionWarning, CompositeWarning, CorruptFileError, InvariantError,
+                      MicroReaderError, MissingImagesWarning, PlateLayoutWarning,
+                      SkewedGridWarning, UnsupportedFormatError)
 from ._memory import MemoryLimitError, memory_limit, set_memory_limit
 from ._io import cache_limit, cached_bytes, set_cache_limit
 from ._pool import decode_threads, set_decode_threads
@@ -23,9 +24,11 @@ from .backends.czi import DamagedFileWarning
 __all__ = [
     "open", "group_files", "FileGroup", "Grouping", "File", "Image", "INDEX_NAMES", "PLATE_INDICES", "SAMPLED_INDICES", "ReadStats",
     "BACKENDS", "Metadata", "Channel", "Quantity", "Plate", "Well", "Field", "Acquisition",
+    "Axis", "CoordinateSystem", "Transformation", "Collection",
     "decode_threads", "set_decode_threads", "memory_limit", "set_memory_limit",
     "cache_limit", "set_cache_limit", "cached_bytes",
-    "MicroReaderError", "UnsupportedFormatError", "CorruptFileError", "MemoryLimitError", "DamagedFileWarning",
+    "MicroReaderError", "UnsupportedFormatError", "CorruptFileError", "InvariantError",
+    "MemoryLimitError", "DamagedFileWarning",
     "MissingImagesWarning", "CompanionWarning", "CompositeWarning", "PlateLayoutWarning",
     "SkewedGridWarning", "__version__",
 ]

{micro_reader-0.1.0 → micro_reader-0.2.1}/src/micro_reader/_base.py

@@ -367,6 +367,10 @@ class File:
     backend's own class is an implementation detail."""
 
     backend: str = "base"
+    #: (coordinate_systems, coordinate_transformations) once declared and checked
+    _graph: Optional[tuple] = None
+    #: (the images it was built from, collection) once built (``collection``)
+    _tree: Optional[tuple] = None
 
     def __init__(self, path: str, images: Sequence[Image], plates: Sequence = ()):
         #: the file read: for a composite format its main file (docs/COMPOSITE.md)
@@ -453,6 +457,75 @@ class File:
                 out.append(image)
         return out
 
+    # The spatial model (plan section 3; _spatial.py): the shared coordinate
+    # systems the file's positions are in, the other edges between them, and
+    # the tree of what contains what.  A backend declares the systems from
+    # what opening the file already read; an image names its system beside
+    # its position (``metadata.coordinate_system``).
+
+    def _declare_coordinate_systems(self) -> Sequence:
+        """The shared coordinate systems this file's positions are in (plan
+        4.2), declared from what opening the file already read -- the
+        indices, the plates, the file's own header -- never from an image's
+        ``metadata`` (no ``_read_metadata``: ``coordinate_systems`` must stay
+        as cheap as opening).  Backends override it; the default declares
+        none.  ``(CoordinateSystem(system_id("stage")),)`` is the usual
+        answer; one per well (``system_id("well", well.name)``, 4.9) or per
+        series (``system_id("stage", f"s{n}")``, 4.15) where the plan says so;
+        ``axes=None`` (the writer fills them, 3.12).  Called once, on the first
+        access of ``coordinate_systems``; the result is checked (I1)."""
+        return ()
+
+    def _declare_coordinate_transformations(self) -> Sequence:
+        """The edges of the graph other than positions (plan 3.3): only
+        BigDataViewer has some (affine views and registrations, 9.16).  Each a
+        ``Transformation`` between declared systems and image keys (I5); the
+        same rules as ``_declare_coordinate_systems``."""
+        return ()
+
+    def _declared(self) -> tuple:
+        if self._graph is None:
+            from ._spatial import check_declared_systems, check_edges, image_key
+            systems = check_declared_systems(self._declare_coordinate_systems(), where=self.path)
+            edges = self._declare_coordinate_transformations()
+            keys = {image_key(image) for image in self.images} if edges else ()
+            self._graph = (systems, check_edges(edges, systems, keys, where=self.path))
+        return self._graph
+
+    @property
+    def coordinate_systems(self) -> tuple:
+        """The shared coordinate systems the backend declares for this file
+        (a tuple of ``CoordinateSystem``, plan 3.3, 4.2): the systems its
+        images' positions are in, named by ``metadata.coordinate_system``.
+        Empty for a backend that declares none.  Declared when first read,
+        without reading any image's metadata."""
+        return self._declared()[0]
+
+    @property
+    def coordinate_transformations(self) -> tuple:
+        """The edges of the file's transformation graph other than positions
+        (a tuple of ``Transformation``, plan 3.3): empty for every backend
+        but BigDataViewer, whose affine views and registrations are edges
+        from an image into ``global`` and ``global-registered`` (9.16)."""
+        return self._declared()[1]
+
+    @property
+    def collection(self):
+        """The tree of what contains what (a ``Collection``, plan 3.1, 3.17):
+        a root named after the file's stem holding plate > well > field, or
+        series, each holding its full-resolution images.  A field or series
+        of one image collapses into it; tiles and the orthogonal indices
+        (view, illumination, ...) make no collection.  The leaves are the
+        objects of ``images`` (after ``open(axes=...)`` too), and the tree
+        is built from the indices and ``plates`` alone: no metadata is read.
+        Built on first access, again when ``images`` has changed
+        (``_spatial.file_collection``)."""
+        images = tuple(self.images)
+        if self._tree is None or self._tree[0] != images:     # identity: Image has no __eq__
+            from ._spatial import file_collection
+            self._tree = (images, file_collection(self))
+        return self._tree[1]
+
     def _member_files(self) -> set:
         """The other files this file's images are read from -- a file set's
         members -- for ``group_files``.  Empty for a file that reads only itself."""

{micro_reader-0.1.0 → micro_reader-0.2.1}/src/micro_reader/_errors.py

@@ -14,6 +14,14 @@ class CorruptFileError(MicroReaderError):
     """The file is recognised but inconsistent, e.g. truncated."""
 
 
+class InvariantError(MicroReaderError):
+    """The spatial model's invariants (plan 3.22) do not hold for a file: a
+    coordinate system id that is not one micro-reader makes or not unique
+    (I1), a position in a system the file does not declare or an estimated
+    one (I2), a position and a coordinate system given without each other
+    (I3), or an edge whose end is neither (I5).  A backend bug."""
+
+
 class OpenInstead(Exception):
     """Internal, not an error: a backend found that *path* is a member of a set
     and that the set's metadata file (``.path``) is what opens it (``open``'s
@@ -37,8 +45,9 @@ class CompositeWarning(UserWarning):
 
 class CompanionWarning(UserWarning):
     """An OME companion set's metadata came from somewhere other than the file
-    opened, or a member path had to be resolved differently than written
-    (docs/COMPANION.md)."""
+    opened, a member path had to be resolved differently than written, or the
+    companion's bytes had to be read in another encoding than its XML
+    declares (docs/COMPANION.md)."""
 
 
 class SkewedGridWarning(UserWarning):

{micro_reader-0.1.0 → micro_reader-0.2.1}/src/micro_reader/_metadata.py

@@ -146,6 +146,10 @@ class Metadata:
     is absent / None."""
     pixel_sizes: dict = field(default_factory=dict)       # axis -> Quantity (x y z t)
     position: dict = field(default_factory=dict)          # axis -> Quantity
+    #: the id of the shared coordinate system ``position`` is in: one of
+    #: ``File.coordinate_systems`` (nominal, ``estimated=False``), set exactly
+    #: when the position is not empty (plan I3); None for an unplaced image
+    coordinate_system: Optional[str] = None
     channels: tuple = ()                                   # Channel per index of c
     #: this image's value of its indices that have one (D5): {"emission":
     #: Quantity(510.0, "nanometer"), "lifetime": Quantity(2.5, "nanosecond")}
@@ -156,6 +160,17 @@ class Metadata:
     #: a ``position``: axis -> Quantity (Bugra, 2026-10-19; MetaMorph)
     stage_position: dict = field(default_factory=dict)
 
+    def __post_init__(self):
+        if self.coordinate_system is not None and not self.position:
+            raise ValueError(f"Metadata: coordinate_system={self.coordinate_system!r} with an "
+                             "empty position: an image is placed exactly when it has both "
+                             "(plan I3); give the position, or coordinate_system=None")
+
+    def unplaced(self) -> "Metadata":
+        """This metadata without a position: ``position`` empty and
+        ``coordinate_system`` None, the rest kept."""
+        return replace(self, position={}, coordinate_system=None)
+
     def scaled(self, factors: dict) -> "Metadata":
         """This metadata for a resolution level whose pixels are *factors*
         (axis -> float) times larger than level 0's."""

{micro_reader-0.1.0 → micro_reader-0.2.1}/src/micro_reader/_plate.py

@@ -57,6 +57,27 @@ def layout(rows: int, columns: int, wells, where: str) -> tuple:
     return tuple(row_label(r) for r in range(rows)), tuple(str(c + 1) for c in range(columns))
 
 
+def well_system(plates, plate: int, well: int) -> str:
+    """The id of the coordinate system of well *well* of plate *plate*
+    (indices into *plates* and its ``wells``), for backends whose positions
+    are relative to the well's centre (plan 4.9; ids 3.23): ``well-B2``, or
+    ``well-p1-B2`` when *plates* holds several (``p`` + the plate index)."""
+    from ._spatial import system_id
+    name = plates[plate].wells[well].name
+    return system_id("well", *((f"p{plate}", name) if len(plates) > 1 else (name,)))
+
+
+def well_systems(plates) -> tuple:
+    """One ``CoordinateSystem`` per well with images of *plates*, plate by
+    plate in well order (``well_system``'s ids; names "well B2", or "plate 1
+    well B2" with several plates): what a backend of plan 4.9 declares."""
+    from ._spatial import CoordinateSystem
+    several = len(plates) > 1
+    return tuple(CoordinateSystem(well_system(plates, p, w),
+                                  f"{f'plate {p} ' if several else ''}well {well.name}")
+                 for p, plate in enumerate(plates) for w, well in enumerate(plate.wells))
+
+
 @dataclass(frozen=True, eq=False)
 class Field:
     """One field of a well: its field index and its images (full resolution,