Merge pull request #77 from sameeul/v236

V236 - update docs and bioformats version

README.md

@@ -8,7 +8,7 @@
 ![Bower](https://img.shields.io/bower/l/MI)
 
 This tool is a simplified but powerful interface to
-[Bioformats](https://www.openmicroscopy.org/bio-formats/)
+[Bio-Formats](https://www.openmicroscopy.org/bio-formats/)
 using jpype for direct access to the library. This tool is designed with
 scalable image analysis in mind, with a simple interface to treat any image
 like a memory mapped array.
@@ -32,10 +32,10 @@ Docker containers with all necessary components are available (see
 ### Setting up Java
 
 **Note:** `bfio` can be used without Java, but only the `python` and `zarr`
-backends will be usable. Only files in tiled OME Tiff or OME Zarr format can be
+backends will be usable. This means only files in tiled OME Tiff or OME Zarr format can be
 read/written.
 
-In order to use the `Java` backend, it is necessary to first install the JDK and Maven.
+In order to use the `bioformats` backend, it is necessary to first install the JDK and Maven.
 The `bfio` package is generally tested with
 [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html),
 but JDK 11 and later also appear to work.
@@ -83,11 +83,6 @@ Sameeul B Samee (sameeul.samee@axleinfo.com)
 This project is licensed under the [MIT License](LICENSE)
 Creative Commons License - see the [LICENSE](LICENSE) file for details.
 
-**NOTE**
-
-Bioformats is licensed under GPL, and as a consequence so is the `bioformats_jar`
-package. These packages and libraries are installed when using the `bfio[bioformats]` option.
-
 ## Acknowledgments
 
 - Parts of this code were written/modified from existing code found in

docker/base/Dockerfile

@@ -1,7 +1,8 @@
 FROM ubuntu:jammy
 
 # Polus platform file extension
-ENV POLUS_EXT=".ome.tif"
+ENV POLUS_IMG_EXT=".ome.tif"
+ENV POLUS_TAB_EXT=".csv"
 
 # Container log level
 ENV POLUS_LOG="INFO"
@@ -17,7 +18,7 @@ RUN mkdir ${EXEC_DIR} && \
 # Install Python
 RUN apt update && \
     apt install software-properties-common -y && \
-    apt install curl maven openjdk-8-jre -y && \
+    apt install curl git maven openjdk-8-jre -y && \
     curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && \
     python3 get-pip.py && \
     apt autoremove -y && \

docker/imagej/Dockerfile

@@ -8,7 +8,7 @@ COPY . /bfio_src
 RUN apt update && \
     apt install software-properties-common -y && \
     add-apt-repository ppa:deadsnakes/ppa && \
-    apt install python3.9 python3.9-distutils curl -y && \
+    apt install python3.9 python3.9-distutils curl git -y && \
     curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && \
     python3.9 get-pip.py && \
     apt autoremove -y && \
@@ -26,7 +26,8 @@ RUN pip3 install cython --no-cache-dir && \
     pip3 install pyimagej==1.4.1 --no-cache-dir
 
 # Polus platform file extension
-ENV POLUS_EXT=".ome.tif"
+ENV POLUS_IMG_EXT=".ome.tif"
+ENV POLUS_TAB_EXT=".csv"
 
 # Container log level
 ENV POLUS_LOG="INFO"
@@ -38,12 +39,21 @@ ENV DATA_DIR="/data"
 RUN mkdir ${EXEC_DIR} && \
     mkdir ${DATA_DIR}
 
-# create polusai user, gid and uid are used to conform with cwl runner
-RUN groupadd -g 1000 polusai && \
-    useradd -u 1000 --no-log-init -r -m -g polusai polusai && \
+# create a non-root user named polusai
+RUN groupadd polusai && \
+    useradd --no-log-init -r -m -g polusai polusai && \
     usermod -aG sudo polusai
-    
+
 ENV HOME=/home/polusai
+RUN chmod -R o+rx ${HOME}
+# NOTE: By default, CWL adds --user=... to the docker run commands.
+# https://github.com/common-workflow-language/cwltool/blob/7b8f174828e3c07b3067e4f88568124f7c878d2d/cwltool/docker.py#L362-L366
+# Since we do not control the userid and/or groupid on the
+# host machine(s) where this docker image will be executed,
+# we must make HOME readable and executable for all users! Otherwise:
+# /usr/bin/python3: Error while finding module specification for 'polus.plugins...'
+# (ModuleNotFoundError: No module named 'polus')
+
 RUN chown -R polusai ${EXEC_DIR} && \
     chown -R polusai ${DATA_DIR} && \
     chmod -R u+rwx ${EXEC_DIR} && \

docker/tensorflow/Dockerfile

@@ -4,12 +4,13 @@ FROM tensorflow/tensorflow:2.13.0-gpu
 # Install Java and Maven
 RUN apt update && \
     apt install software-properties-common -y && \
-    apt install maven openjdk-8-jre -y && \
+    apt install git maven openjdk-8-jre -y && \
     apt autoremove -y && \
     rm -rf /var/lib/apt/lists/*
 
 # Polus platform file extension
-ENV POLUS_EXT=".ome.tif"
+ENV POLUS_IMG_EXT=".ome.tif"
+ENV POLUS_TAB_EXT=".csv"
 
 # Container log level
 ENV POLUS_LOG="INFO"
@@ -30,12 +31,21 @@ COPY . /bfio_src
 RUN pip3 install /bfio_src --no-cache-dir && \
     rm -rf /bfio_src
 
-# create polusai user, gid and uid are used to conform with cwl runner
-RUN groupadd -g 1000 polusai && \
-    useradd -u 1000 --no-log-init -r -m -g polusai polusai && \
+# create a non-root user named polusai
+RUN groupadd polusai && \
+    useradd --no-log-init -r -m -g polusai polusai && \
     usermod -aG sudo polusai
-    
+
 ENV HOME=/home/polusai
+RUN chmod -R o+rx ${HOME}
+# NOTE: By default, CWL adds --user=... to the docker run commands.
+# https://github.com/common-workflow-language/cwltool/blob/7b8f174828e3c07b3067e4f88568124f7c878d2d/cwltool/docker.py#L362-L366
+# Since we do not control the userid and/or groupid on the
+# host machine(s) where this docker image will be executed,
+# we must make HOME readable and executable for all users! Otherwise:
+# /usr/bin/python3: Error while finding module specification for 'polus.plugins...'
+# (ModuleNotFoundError: No module named 'polus')
+
 RUN chown -R polusai ${EXEC_DIR} && \
     chown -R polusai ${DATA_DIR} && \
     chmod -R u+rwx ${EXEC_DIR} && \

docs/source/Examples/Converter.rst

@@ -10,24 +10,25 @@ The bfio package is designed to make it easy to process arbitrarily sized images
 in a fast, scalable way. The two core classes, :doc:`/Reference/BioReader` and
 :doc:`/Reference/BioWriter`, can use one of three different backends depending
 on the file type that will be read. Usually, the proper backend will be selected
-when opening a file, but periodically it will not select the proper backend so
-it is useful to mention them here:
+when opening a file. For cases where bfio fails to select the proper backend, the 
+``backend`` parameter can be passed to the constructor. The following backends
+are available in ``bfio``.
 
 1. ``backend="python"`` can only be used to read/write OME tiled tiff images.
    Tiled tiff is the preferred file format for reading/writing arbitrarily sized
    images.
 2. ``backend="bioformats"`` can be used to read any
-   `any format supported by Bioformats <https://docs.openmicroscopy.org/bio-formats/6.1.0/supported-formats.html>`_.
+   `any format supported by Bio-Formats <https://docs.openmicroscopy.org/bio-formats/7.2.0/supported-formats.html>`_.
    The BioWriter with java backend will only save images as OME tiled tiff.
 3. ``backend="zarr"`` can be used to read/write a subset of Zarr files following
-   the `OME Zarr spec. <https://ngff.openmicroscopy.org/latest/>`_.
+   the `OME Zarr spec <https://ngff.openmicroscopy.org/latest/>`_.
 
 The advantage to using the ``python`` and ``zarr`` backends are speed and
 scalability at the expense of a rigid file structure, while the ``bioformats`` backend
 provides broad access to a wide array of file types but is considerably slower.
 
 In this example, the basic usage of two core classes are demonstrated by
-creating a "universal" converter from any Bioformats supported file format to
+creating a "universal" converter from any Bio-Formats supported file format to
 OME tiled tiff.
 
 ---------------
@@ -38,19 +39,18 @@ Getting Started
 Install Dependencies
 ~~~~~~~~~~~~~~~~~~~~
 
-To run this example, a few dependencies are required. First, ensure Java is
-installed. Then install ``bfio`` using:
+To run this example, Java and Maven are required. See the :doc:`/Installation` instruction for details on how to install them. Then install ``bfio`` using:
 
-``pip install bfio['bioformats']``
+``pip install bfio``
 
 .. note::
 
-    JPype and Bioformats require Java 8 or later. ``bfio`` has been tested
+    JPype and Bio-Formats require Java 8 or later. ``bfio`` has been tested
     using Java 8.
 
 .. note::
 
-    Bioformats is licensed under GPL. If you plan to package ``bfio`` using this option,
+    Bio-Formats is licensed under GPL. If you plan to package ``bfio`` using this option,
     make sure to consider the licensing ramifications.
 
 ~~~~~~~~~~~~~~~~~~~~~
@@ -83,29 +83,21 @@ Reading Images with the BioReader
 
 The first step in loading an image with the BioReader is to initialize a
 BioReader object. The BioReader tries to predict what backend to use based on
-the file extension, and it will throw an error if it predicts incorrectly. In
-this case, the test file downloaded from the WIPP repository is not in OME tiled
-tiff format even though it has the ``.ome.tif`` extension, meaning it will try
-to use the Python backend:
+the file extension, and it will throw an error if it predicts incorrectly. 
 
 .. code-block:: python
 
     from bfio import BioReader
 
     br = BioReader(PATH / FILENAME)
 
-The output should be something like this::
 
-    TypeError: img_r001_c001.ome.tif is not a tiled tiff. The python backend of
-    the BioReader only supports OME tiled tiffs. Use the bioformats backend to load
-    this image.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Manually Specifying a Backend
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Following the error message above, we need to use the ``bioformats`` backend. To do
-this, just use the keyword argument ``backend=bioformats`` when initializing the
+The user can also manually specify a backend. To use ``bioformats`` backend, just use the keyword argument ``backend=bioformats`` when initializing the
 BioReader.
 
 .. code-block:: python
@@ -119,8 +111,8 @@ BioReader.
 
     br.close()
 
-Behind the scenes, what happens is that JPype starts Java and loads the
-Bioformats jar. If Java is not installed, the above code will raise an error.
+Behind the scenes, what happens is that ``scyjava`` starts Java and loads the
+Bio-Formats jar. If Java is not installed, the above code will raise an error.
 
 .. Note::
 

docs/source/Installation.rst

@@ -1,39 +1,29 @@
 Install
 =======
 
-The ``bfio`` package can be installed with a variety of options designed in
-consideration of containerization.
-
-Base Package
-------------
-
-The base package can only read/write tiled, OME TIFF images. It can be installed using:
+The ``bfio`` package and the core dependencies (``numpy``, ``tifffile``, ``imagecodecs``, ``scyjava``) can
+be installed using pip:
 
 ``pip install bfio``
 
-To install all reading and writing options, install with all dependencies:
 
-``pip install bfio[all]``
+A conda distribution is also available in the conda-forge channel. To install it in conda environment, use this:
 
-NOTE: See the Java and Bioformats note about licensing considerations when installing
-using the ``bfio[all]`` option.
+``conda install bfio -c conda-forge``
 
-Java and Bioformats
+Java and Bio-Formats
 -------------------
+``bfio`` can be used without Java, but only the ``python`` and ``zarr``
+backends will be usable. This means only files in tiled OME Tiff or OME Zarr format can be
+read/written.
 
-To use Bioformats, it is necessary to install Java 8 or later. Once Java is
-installed, ``bfio`` can be installed with support for Java using:
-
-pip install bfio['bioformats']
-
-NOTE: The ``bioformats_jar`` package and BioFormats are licensed under GPL, while ``bfio``
-is licensed under MIT. This may have consequences when packaging any software that uses
-``bfio`` as a dependency when this option is used.
+In order to use the ``bioformats`` backend, it is necessary to first install the JDK and Maven.
+The ``bfio`` package is generally tested with
+`JDK 8 <https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html>`_,
+but JDK 11 and later also appear to work.
+Here are some info on installing Maven on various OS (`Windows <https://phoenixnap.com/kb/install-maven-windows>`_ | `Linux <https://www.digitalocean.com/community/tutorials/install-maven-linux-ubuntu>`_ | `Mac <https://www.digitalocean.com/community/tutorials/install-maven-mac-os>`_).
 
-Zarr
-----
 
-To use the zarr backend, you need to have Zarr already installed, or you can
-install it when installing bfio using:
 
-pip install bfio['zarr']
+NOTE: ``Bio-Formats`` is licensed under GPL, while ``bfio`` is licensed under MIT. This may have consequences when packaging any software that uses
+``bfio`` as a dependency. During the first invocation of ``bfio``, ``scyjava`` will try to download ``Bio-Formats`` package from the Maven repository. The current version of ``bfio`` uses ``Bio-Formats`` v7.2.0 .

docs/source/index.rst

@@ -4,9 +4,8 @@ BioFormats Input/Output (bfio) Utility
 
 The ``bfio`` utility is an easy to use, image input/output utility optimized to
 scalably read and write OME TIFF and OME Zarr images as well as all formats supported by
-`Bioformats <https://www.openmicroscopy.org/bio-formats/>`_
-. Reading of data makes direct usage of BioFormats (when using the ``bioformats`` install
-option) using JPype, giving ``bfio`` the ability to read any of the 150+ formats
+`Bio-Formats <https://www.openmicroscopy.org/bio-formats/>`_
+. Reading of data makes direct usage of BioFormats using ``scyjava``, giving ``bfio`` the ability to read any of the 150+ formats
 supported by BioFormats.
 
 For file outputs, only two file formats are supported: tiled OME TIFF, and OME

pyproject.toml

@@ -28,7 +28,7 @@ dependencies = [
     "tifffile>=2022.8.12"
 ]
 
-description = "Simple reading and writing classes for tiled tiffs using Bioformats."
+description = "Simple reading and writing classes for tiled tiffs using Bio-Formats."
 readme = "README.md"
 license = {file = "LICENSE"}
 

src/bfio/backends.py

@@ -1346,7 +1346,7 @@ def __del__(self):
     class JavaWriter(bfio.base_classes.AbstractWriter):
         logger = logging.getLogger("bfio.backends.JavaWriter")
 
-        # For Bioformats, the first tile has to be written before any other tile
+        # For Bio-Formats, the first tile has to be written before any other tile
         first_tile = False
 
         _classes_loaded = False

src/bfio/base_classes.py

@@ -523,7 +523,7 @@ def dtype(self, dtype):
         assert not self._read_only, self._READ_ONLY_MESSAGE.format("dtype")
         if dtype in [numpy.uint64, numpy.int64]:
             self.logger.warning(
-                f"{dtype} is not supported by Bioformats, saving as numpy.float64."
+                f"{dtype} is not supported by Bio-Formats, saving as numpy.float64."
             )
             dtype = numpy.float64
         assert dtype in self._DTYPE.values(), "Invalid data type."
@@ -576,10 +576,10 @@ def bpp(self, bytes_per_pixel: int):
     def metadata(self) -> ome_types.model.OME:
         """Get the metadata for the image.
 
-        This function calls the Bioformats metadata parser, which extracts
+        This function calls the Bio-Formats metadata parser, which extracts
         metadata from an image. This returns a reference to an OMEXML class,
         which is a convenient handler for the complex xml metadata created by
-        Bioformats.
+        Bio-Formats.
 
         Most basic metadata information have their own BioReader methods, such
         as image dimensions(i.e. x, y, etc). However, in some cases it may be