Switch AICSImageIO for BioIO

.gitignore

@@ -137,3 +137,4 @@ dmypy.json
 
 # Generated test images
 *.tif
+*.zarr

notebooks/opening_images.ipynb

@@ -7,17 +7,17 @@
    "source": [
     "# Opening images\n",
     "\n",
-    "This notebook will show how to access metadata and pixel values of images with QuBaLab.\n",
+    "This notebook will show you how to access metadata and pixel values of images with QuBaLab.\n",
     "\n",
-    "A few classes and functions of the QuBaLab package will be presented throughout this notebook. To have more details on them, you can go to the documentation on https://qupath.github.io/qubalab/ and type a class/function name in the search bar. You will then see details on parameters functions take.\n",
+    "A few classes and functions of the QuBaLab package will be presented in this notebook. To view more details on them, you can go to the documentation at https://qupath.github.io/qubalab-docs/ and type a class/function name in the search bar. You will then see details on the arguments that functions accept.\n",
     "\n",
-    "QuBaLab uses the `ImageServer` class to open an image and get its metadata and pixel values. `ImageServer` is an abstract class, so it cannot be directly used. Instead, you have to choose an implementation based on the type of image you want to open:\n",
+    "QuBaLab uses the `ImageServer` class to open an image and get its metadata and pixel values. `ImageServer` is an abstract class, so it cannot be directly created. Instead, you have to choose an implementation based on the type of image you want to open:\n",
     "\n",
-    "* If you need to open an RGB pyramidal image, you can use the `OpenSlideServer`. This class internally uses [OpenSlide](https://openslide.org/): it can read all resolutions of a large pyramidal image but is only suitable for RGB images.\n",
-    "* If you need to open any kind of microscopy image, you can use the `AICSImageIoServer`. This class internally uses [AICSImageIO](https://github.com/AllenCellModeling/aicsimageio) which is suited for a lot of formats. However, this library does not properly support pyramids, so you might only get the full resolution image when opening a pyramidal image.\n",
-    "* If your image has an embedded ICC profile, or if you want to apply a custom ICC Profile to an image, you can use the `IccProfileServer`. This takes another `ImageServer` as a parameter and change pixels values. You can find more information about ICC profiles on [this link](http://www.andrewjanowczyk.com/application-of-icc-profiles-to-digital-pathology-images/).\n",
-    "* If you want to represent objects such as annotations or detections on an image, you can use the `LabeledImageServer`. Pixel values are labels corresponding to image features (such as annotations) present on an image. See the *working_with_objects.ipynb* notebook for more information.\n",
-    "* If you want to access an image opened in QuPath, you can use the `QuPathServer`. See the *communicating_with_qupath.ipynb* notebook for more information.\n",
+    "* If you need to open an RGB pyramidal image, you can use an `OpenSlideServer`. This class internally uses [OpenSlide](https://openslide.org/): it can read all resolutions of a large pyramidal image but is only suitable for RGB images.\n",
+    "* If you need to open any kind of microscopy image, you can use an `BioIOServer`. This class internally uses [BioIO](https://github.com/bioio-devs/bioio) which is suited for a lot of formats. However, this library does not properly support pyramids, so you might only get the full resolution image when opening a pyramidal image.\n",
+    "* If your image has an embedded ICC profile, or if you want to apply a custom ICC Profile to an image, you can use an `IccProfileServer`. This takes another `ImageServer` as a parameter and changes pixels values based on the transforms defined in the ICC profile. You can find more information about ICC profiles on [this link](http://www.andrewjanowczyk.com/application-of-icc-profiles-to-digital-pathology-images/).\n",
+    "* If you want to represent objects such as annotations or detections on an image, you can use a `LabeledImageServer`. Pixel values are labels corresponding to image features (such as annotations) present on an image. See the *working_with_objects.ipynb* notebook for more information.\n",
+    "* If you want to access an image opened in QuPath, you can use a `QuPathServer`. See the *communicating_with_qupath.ipynb* notebook for more information.\n",
     "\n",
     "All these `ImageServer` are used in the same way, only their creation differ. This notebook will show how to create and use these servers."
    ]
@@ -27,11 +27,11 @@
    "id": "7fb5756f-d27e-4720-bbcd-f430b7562351",
    "metadata": {},
    "source": [
-    "## ImageServers creation\n",
+    "## ImageServer creation\n",
     "\n",
     "To create an `ImageServer`, you have to use one of the implementations presented above.\n",
     "\n",
-    "This notebook will download several sample images of large size. You can change the line below to define a folder where images will be stored once downloaded (or leave it blank not to use any cache)."
+    "This notebook will download several large sample images. You can change the line below to define a folder where images will be stored once downloaded (or leave it blank not to use any cache)."
    ]
   },
   {
@@ -55,13 +55,14 @@
     "\n",
     "from pathlib import Path\n",
     "import urllib.request\n",
+    "import tempfile\n",
     "\n",
     "if cache_folder != \"\":\n",
     "    Path(cache_folder).mkdir(parents=True, exist_ok=True)\n",
     "\n",
     "def get_image(image_name, image_url):\n",
     "    if cache_folder == \"\":\n",
-    "        filename = None\n",
+    "        filename = tempfile.gettempdir() / Path(image_name)\n",
     "    else:\n",
     "        filename = Path(cache_folder) / image_name\n",
     "    \n",
@@ -117,7 +118,7 @@
    "id": "624f004b-9383-4053-921e-d8d691749b00",
    "metadata": {},
    "source": [
-    "### AICSImageIoServer\n",
+    "### BioIOServer\n",
     "\n",
     "We will use the **Patient_test_1.ome.tiff** image (CC0 license) because it's a relatively small fluorescence image."
    ]
@@ -140,12 +141,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qubalab.images.aicsimageio_server import AICSImageIoServer\n",
+    "from qubalab.images.bioio_server import BioIOServer\n",
     "\n",
     "\n",
     "# Create the ImageServer from the image path. This will read the image metadata but not the pixel values yet.\n",
     "# This function has optional parameters you can find in the documentation\n",
-    "aicsimageio_server = AICSImageIoServer(fluoro_path)"
+    "bioio_server = BioIOServer(fluoro_path)"
    ]
   },
   {
@@ -190,7 +191,7 @@
    "source": [
     "### QuPathServer\n",
     "\n",
-    "A `QuPathServer` allows to read an image opened in QuPath\n",
+    "A `QuPathServer` allows you to read an image opened in QuPath\n",
     "\n",
     "We will not detail the creation of this server here. Take a look at the *communicating_with_qupath.ipynb* notebook for more information. However, all functions presented below are also valid for a `QuPathServer`."
    ]
@@ -200,9 +201,9 @@
    "id": "1e0a79f3-9467-4a52-ad80-82e74721c9cc",
    "metadata": {},
    "source": [
-    "## ImageServers usage\n",
+    "## ImageServer usage\n",
     "\n",
-    "To access metadata and pixel values of an `ImageServer`, you can use the functions presented below.\n",
+    "To access metadata and pixel values from an `ImageServer`, you can use the functions presented below.\n",
     "\n",
     "These functions are available for any implementation of `ImageServer`. We will use the `OpenSlideServer` created above but they are also valid for any other `ImageServer`."
    ]
@@ -214,7 +215,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "server = openslide_server  # you can change it to aicsimageio_server or icc_profile_server"
+    "server = openslide_server  # you can change it to bioio_server or icc_profile_server"
    ]
   },
   {
@@ -224,7 +225,7 @@
    "source": [
     "### Image metadata\n",
     "\n",
-    "Image metadata is access with the `ImageServer.metadata` property."
+    "Image metadata is accessed with the `ImageServer.metadata` property."
    ]
   },
   {

notebooks/working_with_objects.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Working with objects\n",
     "\n",
-    "This notebook will show how to exchange objects (e.g. annotations, detections) between QuPath and Python.\n",
+    "This notebook will show you how to exchange objects (e.g. annotations, detections) between QuPath and Python.\n",
     "\n",
     "As we will communicate with QuPath, it is recommended to go through the *communicating_with_qupath.ipynb* notebook first. Also, as we will work with images, it is recommended to go through the *opening_images.ipynb* notebook first.\n",
     "\n",

qubalab/images/aicsimageio_server.py → qubalab/images/bioio_server.py

@@ -2,7 +2,7 @@
 import dask.array as da
 import math
 from pathlib import Path
-from aicsimageio import AICSImage
+from bioio import BioImage
 from dataclasses import astuple
 from .image_server import ImageServer
 from .metadata.image_metadata import ImageMetadata
@@ -11,31 +11,31 @@
 from .region_2d import Region2D
 
 
-class AICSImageIoServer(ImageServer):
+class BioIOServer(ImageServer):
     """
-    An ImageServer using AICSImageIO (https://github.com/AllenCellModeling/aicsimageio).
+    An ImageServer using BioIO (https://github.com/AllenCellModeling/BioIO).
 
-    What this actually supports will depend upon how AICSImageIO is installed.
+    What this actually supports will depend upon how BioIO is installed.
     For example, it may provide Bio-Formats or CZI support... or it may not.
 
-    Note that the AICSImage library does not currently handle unit attachment, so the pixel unit
+    Note that the BioIo library does not currently handle unit attachment, so the pixel unit
     given by this server will always be 'pixels'.
 
-    Note that the AICSImage library does not properly support pyramids, so you might only get the full
+    Note that the BioIO library does not properly support pyramids, so you might only get the full
     resolution image when opening a pyramidal image.
     """
 
-    def __init__(self, path: str, scene: int = 0, detect_resolutions=True, aics_kwargs: dict[str, any] = {}, **kwargs):
+    def __init__(self, path: str, scene: int = 0, detect_resolutions=True, bioio_kwargs: dict[str, any] = {}, **kwargs):
         """
         :param path: the local path to the image to open
-        :param scene: AICSImageIO divides images into scene. This parameter specifies which scene to consider
+        :param scene: BioIO divides images into scene. This parameter specifies which scene to consider
         :param detect_resolutions: whether to look at all resolutions of the image (instead of just the full resolution)
-        :param aics_kwargs: any specific keyword arguments to pass down to the fsspec created filesystem handled by the AICSImageIO reader
+        :param bioio_kwargs: any specific keyword arguments to pass down to the fsspec created filesystem handled by the BioIO reader
         :param resize_method: the resampling method to use when resizing the image for downsampling. Bicubic by default
         """
         super().__init__(**kwargs)
         self._path = path
-        self._reader = AICSImage(path, dask_tiles=True, **aics_kwargs)
+        self._reader = BioImage(path, **bioio_kwargs)
         self._scene = scene
         self._detect_resolutions = detect_resolutions
 
@@ -73,19 +73,19 @@ def _read_block(self, level: int, region: Region2D) -> np.ndarray:
         return self._reader.get_image_dask_data(axes)[t, z, :, y:y + height, x:x + width].compute()
 
     @staticmethod
-    def _get_shapes(reader: AICSImage, scene: int) -> tuple[ImageShape, ...]:
+    def _get_shapes(reader: BioImage, scene: int) -> tuple[ImageShape, ...]:
         shapes = []
         for scene in reader.scenes[scene:]:
-            shape = AICSImageIoServer._get_scene_shape(reader, scene)
+            shape = BioIOServer._get_scene_shape(reader, scene)
 
-            if len(shapes) == 0 or AICSImageIoServer._is_lower_resolution(shapes[-1], shape):
+            if len(shapes) == 0 or BioIOServer._is_lower_resolution(shapes[-1], shape):
                 shapes.append(shape)
             else:
                 break
         return tuple(shapes)
 
     @staticmethod
-    def _get_scene_shape(reader: AICSImage, scene: int) -> ImageShape:
+    def _get_scene_shape(reader: BioImage, scene: int) -> ImageShape:
         reader.set_scene(scene)
 
         return ImageShape(
@@ -97,12 +97,12 @@ def _get_scene_shape(reader: AICSImage, scene: int) -> ImageShape:
         )
 
     @staticmethod
-    def _get_pixel_calibration(reader: AICSImage, scene: int) -> PixelCalibration:
+    def _get_pixel_calibration(reader: BioImage, scene: int) -> PixelCalibration:
         reader.set_scene(scene)
         sizes = reader.physical_pixel_sizes
 
         if sizes.X or sizes.Y or sizes.Z:
-            # The AICSImage library does not currently handle unit attachment, so the pixel unit is returned
+            # The bioio library does not currently handle unit attachment, so the pixel unit is returned
             return PixelCalibration(
                 PixelLength(sizes.X) if sizes.X is not None else PixelLength(),
                 PixelLength(sizes.Y) if sizes.Y is not None else PixelLength(),
@@ -112,7 +112,7 @@ def _get_pixel_calibration(reader: AICSImage, scene: int) -> PixelCalibration:
             return PixelCalibration()
 
     @staticmethod
-    def _is_rgb(reader: AICSImage, scene: int) -> bool:
+    def _is_rgb(reader: BioImage, scene: int) -> bool:
         reader.set_scene(scene)
         return ('S' in reader.dims.order and reader.dims.S in [3, 4]) or (reader.dtype == np.uint8 and reader.dims.C == 3)
 
@@ -121,7 +121,7 @@ def _is_lower_resolution(base_shape: ImageShape, series_shape: ImageShape) -> bo
         """
         Calculate if the series shape is a lower resolution than the base shape.
 
-        This involves a bit of guesswork, but it's needed for so long as AICSImageIO doesn't properly support pyramids.
+        This involves a bit of guesswork, but it's needed for so long as BioIO doesn't properly support pyramids.
         """
         if base_shape.z == series_shape.z and \
                 base_shape.t == series_shape.t and \

setup.cfg

@@ -18,7 +18,9 @@ packages =
 python_requires = >= 3.10
 install_requires =
     tiffslide ~= 2.4.0
-    aicsimageio >= 4.10.0
+    bioio ~= 1.1.0
+    bioio-ome-zarr ~= 1.0.1
+    bioio-ome-tiff ~= 1.0.1
     dask-image >= 0.6.0
     py4j ~= 0.10.9.7
     geojson ~= 3.1.0