avoid autosplit channel axis for plain tiff with no channel metadata. Add tests too

Author: pr4deepr

plugin/napari_lattice/fields.py

@@ -88,6 +88,25 @@ class BackgroundSource(StrEnum):
     SecondLast = "Second Last"
     Custom = "Custom"
 
+def dimension_order_options(ndims: Optional[int]) -> List[str]:
+    """
+    Dimension-order choices offered for an image stack of the given dimensionality,
+    including the "Get from Metadata" option. Kept as a separate function so 
+    we can test interaction between the reader -> GUI without a Qt widget: For example, a
+    single-channel stack that the reader keeps 5D must offer the TCZYX/CTZYX orders.
+    """
+    default = ["Get from Metadata"]
+    if ndims is None:
+        return default
+    elif ndims == 3:
+        return ["ZYX"] + default
+    elif ndims == 4:
+        return ["TZYX", "CZYX"] + default
+    elif ndims == 5:
+        return ["TCZYX", "CTZYX"] + default
+    else:
+        raise Exception("Only 3-5 dimensional arrays are supported")
+
 def enable_field(field: MagicField, enabled: bool = True) -> None:
     """
     Enable the widget associated with a field
@@ -226,18 +245,8 @@ def _get_dimension_options(self, _) -> List[str]:
         """
         Returns the list of dimension order options that might be possible for the current image stack
         """
-        default = ["Get from Metadata"]
         ndims = max([len(layer.data.shape) for layer in self.img_layer.value], default=None)
-        if ndims is None:
-            return default
-        elif ndims == 3:
-            return ["ZYX"] + default
-        elif ndims == 4:
-            return ["TZYX", "CZYX"] + default
-        elif ndims == 5:
-            return ["TCZYX", "CTZYX"] + default
-        else:
-            raise Exception("Only 3-5 dimensional arrays are supported")
+        return dimension_order_options(ndims)
 
     # --- Input / interpretation ---
     img_layer = field(List[Image], widget_type='Select').with_options(

plugin/napari_lattice/reader.py

@@ -28,6 +28,27 @@
     from bioio import ImageLike
     from xarray import DataArray
 
+import re
+# bioio can invent placeholder channel names: "Channel:<image>:<channel>"
+# (e.g. "Channel:0:0") for files that with no channel metadata, such 
+# as plain TIFFs. The TCZYX order is  guessed from the array shape.
+# `test_reader` pins thisformat so a future bioio rename surfaces as a test failure instead of silently
+# re-enabling channel splitting. Genuine acquisitions have descriptive names ("LLS1").
+_AUTO_CHANNEL_NAME = re.compile(r"^Channel:\d+:\d+$")
+
+def _has_real_channel_metadata(image: BioImage) -> bool:
+    """
+    Whether the image's channel axis is trustworthy enough to split a napari layer on.
+
+    We trust it only when the channel names are descriptive, rather than bioio's
+    "Channel:i:j" placeholders. This is best-effort: it cannot recognise a real channel
+    axis that simply has no names, but it covers every observed file format.
+    """
+    names = image.channel_names
+    if not names:
+        return False
+    return not all(_AUTO_CHANNEL_NAME.match(str(name)) for name in names)
+
 class NapariImageParams(TypedDict):
     data: DataArray
     physical_pixel_sizes: DefinedPixelSizes
@@ -249,19 +270,36 @@ def bioio_reader(path: str | list[str]) -> List[Tuple[Any, dict, str]]:
             getattr(pixel_sizes, dim, 1.0) or 1.0 for dim in image.dims.order
         ]
 
-        # Set the channel axis
-        if "C" in image.dims.order:
-            c_idx = image.dims.order.index("C")
+        # Set the channel axis.
+        # Only split the layer into one image per channel when the channel axis is
+        # genuine: it must have more than one channel AND come with real channel
+        # metadata. bioio pads plain TIFFs out to a guessed TCZYX order (size-1 C, or a
+        # frame axis mislabelled as "C"), so splitting on that guess would collapse a
+        # single-channel stack to a lower dimensionality or carve a frame axis into
+        # spurious channels - in both cases hiding the TCZYX/CTZYX dimension-order
+        # options the user needs to correct the interpretation downstream.
+        c_idx = image.dims.order.index("C") if "C" in image.dims.order else None
+        channel_size = image.dims.shape[c_idx] if c_idx is not None else 1
+        split_channels = (
+            c_idx is not None and channel_size > 1 and _has_real_channel_metadata(image)
+        )
+        if split_channels:
             add_kwargs["channel_axis"] = c_idx
             #remove channel idx from scale
             scale.pop(c_idx)
             dim_order.pop(c_idx)
-            if image.channel_names:
-                if len(scenes) > 1 and scene is not None:
-                    add_kwargs["name"] = [f"{scene} - {ch}" for ch in image.channel_names]
-                else:
-                    add_kwargs["name"] = image.channel_names
+            if len(scenes) > 1 and scene is not None:
+                add_kwargs["name"] = [f"{scene} - {ch}" for ch in image.channel_names]
+            else:
+                add_kwargs["name"] = image.channel_names
         else:
+            if c_idx is not None and channel_size > 1:
+                logger.info(
+                    f"Not splitting the guessed channel axis of '{os.path.basename(path)}' "
+                    f"(size {channel_size}) into separate layers, because the file has no "
+                    f"genuine channel metadata. If this axis is not really the channel "
+                    f"dimension, set the dimension order manually in the Deskew tab."
+                )
             if len(scenes) > 1 and scene is not None:
                 add_kwargs["name"] = f"{os.path.splitext(os.path.basename(path))[0]} - {scene}"
             else:

plugin/tests/test_reader.py

@@ -0,0 +1,71 @@
+"""
+Tests for napari_lattice.reader's channel-axis splitting decision and the reader -> GUI
+dimension-order contract.
+
+bioio fabricates a full ``TCZYX`` order for plain TIFFs (padding missing axes with
+size-1 and auto-naming channels ``Channel:i:j``). The reader must only split a layer
+along its channel axis when that axis is genuine; otherwise single-channel stacks
+collapse in dimensionality and frame axes that bioio mislabelled "C" get carved into
+spurious channels - which is what hides the TCZYX/CTZYX dimension-order options the user
+needs to correct the interpretation.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+import tifffile
+from bioio import BioImage
+from importlib_resources import as_file
+
+from lls_core.sample import resources
+from napari_lattice.fields import dimension_order_options
+from napari_lattice.reader import _AUTO_CHANNEL_NAME, bioio_reader
+
+
+def _plain_tiff(tmp_path, shape) -> str:
+    p = tmp_path / "plain.tif"
+    tifffile.imwrite(str(p), np.zeros(shape, dtype=np.uint16))
+    return str(p)
+
+
+@pytest.mark.parametrize("on_disk", [
+    pytest.param((5, 1, 30, 16, 16), id="single_channel"),       # bioio -> TCZYX, C=1
+    pytest.param((4, 30, 16, 16), id="frames_mislabelled_C"),    # bioio -> TCZYX, C=4
+    pytest.param((3, 2, 30, 16, 16), id="multichannel_no_meta"), # placeholder names
+])
+def test_plain_tiff_is_not_split(tmp_path, on_disk):
+    # No genuine channel metadata -> keep the layer whole so the GUI can offer the
+    # full TCZYX/CTZYX dimension-order options for the user to correct.
+    layers = bioio_reader(_plain_tiff(tmp_path, on_disk))
+    assert len(layers) == 1
+    _data, add_kwargs, _ = layers[0]
+    assert "channel_axis" not in add_kwargs
+
+
+def test_genuine_multichannel_is_split():
+    # A real acquisition (a format-specific reader with descriptive channel names) is
+    # still split into one layer per channel for convenient per-channel viewing.
+    with as_file(resources / "LLS7_t1_ch3.czi") as p:
+        image = BioImage(str(p))
+        layers = bioio_reader(str(p))
+    _data, add_kwargs, _ = layers[0]
+    assert add_kwargs["channel_axis"] == image.dims.order.index("C")
+    assert add_kwargs["name"] == list(image.channel_names)
+    # The channel axis is dropped from the per-channel dimension metadata.
+    assert "C" not in add_kwargs["metadata"]["dimensions"]
+
+
+def test_single_channel_tiff_yields_5d_dimension_options(tmp_path):
+    # The reader -> GUI contract: a single-channel stack stays 5D, and the dimension
+    # dropdown must then offer the 5D orders so the user can set/confirm the order.
+    data, _add_kwargs, _ = bioio_reader(_plain_tiff(tmp_path, (5, 1, 30, 16, 16)))[0]
+    options = dimension_order_options(len(data.shape))
+    assert "TCZYX" in options and "CTZYX" in options
+
+
+def test_bioio_placeholder_channel_name_format_unchanged(tmp_path):
+    # Canary: our split decision relies on recognising bioio's placeholder channel
+    # names for plain TIFFs. If a bioio upgrade changes this format, fail loudly here
+    # rather than silently reverting to splitting every plain TIFF.
+    names = BioImage(_plain_tiff(tmp_path, (3, 2, 30, 16, 16))).channel_names
+    assert names and all(_AUTO_CHANNEL_NAME.match(str(n)) for n in names), names