Merge pull request #1409 from MouseLand/guess_3d_chan_0

guess Z dim is 0 instead of argmin of dims

Author: mrariden

cellpose/io.py

@@ -264,14 +264,18 @@ def imread_3D(img_file):
     """
     Read in a 3D image file and convert it to have a channel axis last automatically. Attempts to do this for multi-channel and grayscale images.
 
-    If multichannel image, the channel axis is assumed to be the smallest dimension, and the z axis is the next smallest dimension. 
-    Use `cellpose.io.imread()` to load the full image without selecting the z and channel axes. 
-    
+    For grayscale images (3D array), axis 0 is assumed to be the Z axis (e.g., Z x Y x X).
+    For multichannel images (4D array), the channel axis is assumed to be the smallest dimension,
+    and the Z axis is assumed to be the first remaining axis after the channel axis is removed.
+
+    Use ``cellpose.io.imread()`` to load the full image without automatic axis selection,
+    then specify ``z_axis`` and ``channel_axis`` manually when calling ``model.eval``.
+
     Args:
         img_file (str): The path to the image file.
 
     Returns:
-        img_out (numpy.ndarray): The image data as a NumPy array.
+        img_out (numpy.ndarray): The image data as a NumPy array with channels last, or None if loading fails.
     """
     img = imread(img_file)
 
@@ -281,16 +285,15 @@ def imread_3D(img_file):
     if img.ndim == 3:
         channel_axis = None
         # guess at z axis:
-        z_axis = np.argmin(dimension_lengths)
+        z_axis = 0
 
     elif img.ndim == 4:
         # guess at channel axis:
         channel_axis = np.argmin(dimension_lengths)
-
-        # guess at z axis: 
-        # set channel axis to max so argmin works:
-        dimension_lengths[channel_axis] = max(dimension_lengths)
-        z_axis = np.argmin(dimension_lengths)
+        dimensions = list(range(img.ndim))
+        dimensions.pop(channel_axis)
+        # guess at z axis as the first remaining dimension: 
+        z_axis = dimensions[0]
 
     else: 
         raise ValueError(f'image shape error, 3D image must 3 or 4 dimensional. Number of dimensions: {img.ndim}')

docs/do3d.rst

@@ -25,12 +25,21 @@ then the GUI will automatically run 3D segmentation and display it in the GUI. W
 the command line for progress. It is recommended to use a GPU to speed up processing.
 
 In the CLI/notebook, you need to specify the ``z_axis`` and the ``channel_axis``
-parameters to specify the axis (0-based) of the image which corresponds to the image channels and to the z axis. 
-For example an image with 2 channels of shape (1024,1024,2,105,1) can be 
-specified with ``channel_axis=2`` and ``z_axis=3``. These parameters can be specified using the command line 
-with ``--channel_axis`` or ``--z_axis`` or as inputs to ``model.eval`` for 
+parameters to specify the axis (0-based) of the image which corresponds to the image channels and to the z axis.
+For example an image with 2 channels of shape (1024,1024,2,105,1) can be
+specified with ``channel_axis=2`` and ``z_axis=3``. These parameters can be specified using the command line
+with ``--channel_axis`` or ``--z_axis`` or as inputs to ``model.eval`` for
 the ``CellposeModel`` model.
 
+As a convenience, :func:`cellpose.io.imread_3D` will attempt to load a 3D image and
+automatically guess the axes. For grayscale images (3D array), axis 0 is assumed
+to be the Z axis (e.g., Z x Y x X). For multichannel images (4D array), the
+channel axis is assumed to be the smallest dimension, and the Z axis is assumed to
+be the first remaining axis after the channel axis is identified (e.g., for a
+Z x C x Y x X image, channel axis = 1 and z axis = 0). If your image does not
+follow these conventions, use ``cellpose.io.imread`` and specify ``z_axis`` and
+``channel_axis`` manually.
+
 Volumetric stacks do not always have the same sampling in XY as they do in Z. 
 Therefore you can set an ``anisotropy`` parameter in CLI/notebook to allow for differences in 
 sampling, e.g. set to 2.0 if Z is sampled half as dense as X or Y, and then in the algorithm