feature/aics-series

README.md

@@ -19,10 +19,6 @@ A Python library for reading and writing image data with specific support for ha
     * `TIFF`
     * Any additional format supported by `imageio`
 
-### Disclaimer:
-This package is under heavy revision in preparation for version 3.0.0 release. The quick start below is representative
-of how to interact with the package under 3.0.0 and not under the current stable release.
-
 ## Quick Start
 ```python
 from aicsimageio import AICSImage, imread
@@ -58,14 +54,38 @@ im.metadata  # returns whichever metadata parser best suits the file format
 
 # Subsets or transposes of the image data can be requested:
 im.get_image_data(out_orientation="ZYX")  # returns a 3d data block containing only the ZYX dimensions
-
 ```
 
 ## Notes
 * Image data numpy arrays are always returned as six dimensional in dimension order `STCZYX`
 or `Scene`, `Time`, `Channel`, `Z`, `Y`, and `X`.
 * Each file format may use a different metadata parser it is dependent on the reader's implementation.
 
+## Experimental
+We include an experimental series reader which can force multiple images to act like a single `numpy.ndarray`.
+Image dimension consistency is checked during reading of any image required to complete a slice operation.
+All images must have consistent shape and whichever dimension is chosen to be used as the series dimension must be of
+size one (1) for each image in the series.
+
+```python
+from aicsimageio import AICSSeries
+
+# Combine a series of images and make them act like a single numpy ndarray
+series = AICSSeries(
+    [
+        "img1.tiff",
+        "img2.tiff",
+        "img3.tiff",
+        "img4.tiff"
+    ],
+    series_dim="T"
+)
+
+# Get data out
+series[0, :, :, :, :, :]  # returns a 5D ndarray of TCZYX
+series[:, 3, 3, :, :, :]  # returns a 4D ndarray of SZYX
+```
+
 ## Installation
 **Stable Release:** `pip install aicsimageio`<br>
 **Development Head:** `pip install git+https://github.com/AllenCellModeling/aicsimageio.git`

aicsimageio/__init__.py

@@ -1,5 +1,6 @@
 from .aics_image import AICSImage  # noqa: F401
 from .aics_image import imread  # noqa: F401
+from .aics_series import AICSSeries  # noqa: F401
 
 # Do not edit this string manually, always use bumpversion
 # Details in CONTRIBUTING.md

aicsimageio/aics_image.py

@@ -1,16 +1,19 @@
 import logging
-import typing
-from typing import Optional, Type
+from typing import Optional, Type, Union
 
 import numpy as np
 
 from . import constants, transforms, types
-from .exceptions import InvalidDimensionOrderingError, UnsupportedFileFormatError
-from .readers import CziReader, DefaultReader, NdArrayReader, OmeTiffReader, TiffReader
+from .exceptions import (InvalidDimensionOrderingError,
+                         UnsupportedFileFormatError)
+from .readers import (CziReader, DefaultReader, NdArrayReader, OmeTiffReader,
+                      TiffReader)
 from .readers.reader import Reader
 
 log = logging.getLogger(__name__)
 
+###############################################################################
+
 
 class AICSImage:
     """
@@ -85,7 +88,7 @@ class AICSImage:
 
     def __init__(
         self,
-        data: typing.Union[types.FileLike, np.ndarray],
+        data: Union[types.FileLike, np.ndarray],
         known_dims: Optional[str] = None,
         **kwargs,
     ):
@@ -155,7 +158,7 @@ def data(self):
             )
         return self._data
 
-    def size(self, dims: str = "STCZYX"):
+    def size(self, dims: str = constants.DEFAULT_DIMENSION_ORDER):
         """
         Parameters
         ----------
@@ -166,7 +169,7 @@ def size(self, dims: str = "STCZYX"):
         Returns a tuple with the requested dimensions filled in
         """
         dims = dims.upper()
-        if not (all(d in "STCZYX" for d in dims)):
+        if not (all(d in constants.DEFAULT_DIMENSION_ORDER for d in dims)):
             raise InvalidDimensionOrderingError(f"Invalid dimensions requested: {dims}")
         if not (all(d in self.dims for d in dims)):
             raise InvalidDimensionOrderingError(f"Invalid dimensions requested: {dims}")