Merge branch 'MouseLand:main' into qy/update-env

Author: qin-yu

.github/workflows/test_and_deploy.yml

@@ -3,7 +3,7 @@
 
 name: tests
 
-on: 
+on:
   push:
     branches:
       - main
@@ -14,7 +14,7 @@ on:
       - main
   workflow_dispatch:
 
-jobs:          
+jobs:
   test:
     name: ${{ matrix.platform }} py${{ matrix.python-version }}
     runs-on: ${{ matrix.platform }}
@@ -26,10 +26,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -45,21 +47,25 @@ jobs:
 
   deploy:
     # this will run when you have tagged a commit, starting with "v*"
-    # and requires that you have put your twine API key in your 
+    # and requires that you have put your twine API key in your
     # github secrets (see readme for details)
     needs: [test]
     runs-on: ubuntu-latest
     if: contains(github.ref, 'tags')
+
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -U setuptools setuptools_scm wheel twine
+
       - name: Build and publish
         env:
           TWINE_USERNAME: __token__

cellpose/gui/io.py

@@ -139,6 +139,7 @@ def _load_image(parent, filename=None, load_seg=True, load_3D=False):
     except Exception as e:
         print("ERROR: images not compatible")
         print(f"ERROR: {e}")
+        return
 
     if parent.loaded:
         parent.reset()

cellpose/io.py

@@ -47,6 +47,33 @@
 io_logger = logging.getLogger(__name__)
 
 def logger_setup(cp_path=".cellpose", logfile_name="run.log", stdout_file_replacement=None):
+    """Set up logging to a file and stdout (or a file replacement).
+
+    Creates the log directory if it doesn't exist, removes any existing log
+    file, and configures the root logger to write INFO-level and above messages
+    to both a log file and stdout (or a replacement file).
+
+    Parameters
+    ----------
+    cp_path : str, optional
+        Directory name under the user's home directory for log output.
+        Default is ".cellpose".
+    logfile_name : str, optional
+        Name of the log file created inside cp_path. Default is "run.log".
+    stdout_file_replacement : str or None, optional
+        If provided, log output is written to this file path instead of stdout.
+
+    Returns
+    -------
+    logger : logging.Logger
+        Configured logger for this module. Only INFO and above messages are
+        emitted by default. To enable debug output, call
+        ``logger.setLevel(logging.DEBUG)`` on the returned logger.
+
+    Notes
+    -----
+    The log file is deleted and recreated on each call.
+    """
     cp_dir = pathlib.Path.home().joinpath(cp_path)
     cp_dir.mkdir(exist_ok=True)
     log_file = cp_dir.joinpath(logfile_name)
@@ -189,6 +216,28 @@ def imread(filename):
         if not ND2:
             io_logger.critical("ERROR: need to 'pip install nd2' to load in .nd2 file")
             return None
+        else:
+            with nd2.ND2File(filename) as nd2_file:
+                img = nd2_file.asarray()
+                sizes = nd2_file.sizes
+
+            kept_axes = [nd2.AXIS.Y, nd2.AXIS.X, nd2.AXIS.CHANNEL, nd2.AXIS.Z]
+            # For multi-dimensional data (T, P, etc.), take first frame/position
+            # Work backwards through axes to avoid index shifting
+            for i, (ax_name, size) in reversed(list(enumerate(sizes.items()))):
+                # Keep Y, X, C, Z; remove or reduce everything else
+                if ax_name not in kept_axes:
+                    if size > 1:
+                        io_logger.warning(
+                            f"ND2 file has {size} {ax_name} - using first only"
+                        )
+                    # Take first element (works for both size=1 and size>1)
+                    img = np.take(img, 0, axis=i)
+
+            # Result should now be YX, CYX, ZYX, or CZYX depending on original axes
+            # nd2 preserves axis order from sizes dict (usually C, Z, Y, X)
+            return img
+
     elif ext == ".nrrd":
         if not NRRD:
             io_logger.critical(
@@ -230,40 +279,47 @@ def imread_2D(img_file):
         img_out (numpy.ndarray): The 3-channel image data as a NumPy array.
     """
     img = imread(img_file)
+    if img is None:
+        raise ValueError(f"could not read image file {img_file}")
     return transforms.convert_image(img, do_3D=False)
 
 
 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)
+    if img is None:
+        raise ValueError(f"could not read image file {img_file}")
 
     dimension_lengths = list(img.shape)
 
     # grayscale images:
     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}')

cellpose/transforms.py

@@ -612,7 +612,7 @@ def convert_image(x, channel_axis=None, z_axis=None, do_3D=False):
         x_out[..., 0] = x
         x = x_out
         del x_out
-        transforms_logger.info(f'processing grayscale image with {x.shape[0], x.shape[1]} HW')
+        transforms_logger.debug(f'processing grayscale image with {x.shape[0], x.shape[1]} HW')
     elif ndim == 3:
         # assume 2d with channels
         # find dim with smaller size between first and last dims
@@ -629,7 +629,7 @@ def convert_image(x, channel_axis=None, z_axis=None, do_3D=False):
         x_out[..., :num_channels] = x[..., :num_channels]
         x = x_out
         del x_out
-        transforms_logger.info(f'processing image with {x.shape[0], x.shape[1]} HW, and {x.shape[2]} channels')
+        transforms_logger.debug(f'processing image with {x.shape[0], x.shape[1]} HW, and {x.shape[2]} channels')
     elif ndim == 4:
         # assume batch of 2d with channels
 
@@ -642,7 +642,7 @@ def convert_image(x, channel_axis=None, z_axis=None, do_3D=False):
         x_out[..., :num_channels] = x[..., :num_channels]
         x = x_out
         del x_out
-        transforms_logger.info(f'processing image batch with {x.shape[0]} images, {x.shape[1], x.shape[2]} HW, and {x.shape[3]} channels')
+        transforms_logger.debug(f'processing image batch with {x.shape[0]} images, {x.shape[1], x.shape[2]} HW, and {x.shape[3]} channels')
     else:
         # something is wrong: yell
         expected_shapes = "2D (H, W), 3D (H, W, C), or 4D (Z, H, W, C)"

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 

tox.ini

@@ -8,32 +8,44 @@ python =
     3.10: py310
     3.11: py311
 fail_on_no_env = True
-    
+
 [gh-actions:env]
 PLATFORM =
     ubuntu-latest: linux
     macos-latest: macos
     windows-latest: windows
 
 [testenv]
-platform = 
+platform =
     macos: darwin
     linux: linux
     windows: win32
-passenv = 
+passenv =
     CI
     GITHUB_ACTIONS
     DISPLAY,XAUTHORITY
     NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
     PYVISTA_OFF_SCREEN
+    USERNAME
+    USER
+    LOGNAME
+    LNAME
+    TEMP
+    TMP
+    TMPDIR
+    TORCHINDUCTOR_CACHE_DIR
+setenv =
+    windows: TORCHINDUCTOR_CACHE_DIR = {env:TEMP}{/}torchinductor
+    macos:   TORCHINDUCTOR_CACHE_DIR = {env:TMPDIR}{/}torchinductor
+    linux:   TORCHINDUCTOR_CACHE_DIR = {env:TMPDIR:/tmp}{/}torchinductor
 extras = gui
-deps = 
+deps =
     .[gui]
     py
     pytest
     pytest-cov
     pytest-xvfb
 # ignoring contrib tests for now
-commands = 
+commands =
     #linux: apt-get update && apt-get install libgl1
     pytest -vv -rA --color=yes --cov=cellpose --cov-report=xml --ignore=tests/contrib --durations=0