patchworks 1.4.0__tar.gz → 1.4.1__tar.gz

{patchworks-1.4.0 → patchworks-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 1.4.0
+Version: 1.4.1
 Summary: Tiled processing of arbitrarily large images with globally consistent labels
 Project-URL: Homepage, https://github.com/imcf/patchworks
 Project-URL: Issues, https://github.com/imcf/patchworks/issues
@@ -143,6 +143,8 @@ pip install "patchworks[all]"       # Everything, incl. the napari viewer
 > `[imaris]` adds native `.ims` support (HDF5, no JVM). Physical pixel
 > calibration is read from the input and written into the OME-ZARR.
 
+<!-- -->
+
 > **`cupy` is never installed automatically**, unlike Cellpose's GPU support
 > (which comes for free via PyTorch's self-contained CUDA wheels). Any
 > `use_gpu=True`/`dilate_gpu: true` option (the `dog` plugin, `dilate_labels`)

{patchworks-1.4.0 → patchworks-1.4.1}/README.md

@@ -53,6 +53,8 @@ pip install "patchworks[all]"       # Everything, incl. the napari viewer
 > `[imaris]` adds native `.ims` support (HDF5, no JVM). Physical pixel
 > calibration is read from the input and written into the OME-ZARR.
 
+<!-- -->
+
 > **`cupy` is never installed automatically**, unlike Cellpose's GPU support
 > (which comes for free via PyTorch's self-contained CUDA wheels). Any
 > `use_gpu=True`/`dilate_gpu: true` option (the `dog` plugin, `dilate_labels`)

{patchworks-1.4.0 → patchworks-1.4.1}/docs/guide/ome_zarr_napari.md

@@ -39,9 +39,10 @@ existed.
 ## Convert any image to OME-ZARR
 
 `to_ome_zarr` accepts a dask/NumPy array, an existing `.zarr` store, an
-**Imaris `.ims`** file, or **any format** readable by
-[bioio](https://github.com/bioio-devs/bioio) (CZI, LIF, ND2, OME-TIFF, …). File
-inputs are read **lazily**.
+**Imaris `.ims`** file, **any format** readable by
+[bioio](https://github.com/bioio-devs/bioio) (CZI, LIF, ND2, OME-TIFF, …), or
+a **folder of single-plane TIFFs** (see below). File inputs are read
+**lazily**.
 
 ```python
 from patchworks.plugins.ome_zarr import to_ome_zarr
@@ -50,6 +51,51 @@ to_ome_zarr("scan.czi", "scan.zarr", n_levels=5)   # via bioio
 to_ome_zarr("scan.ims", "scan.zarr")               # Imaris, native HDF5
 ```
 
+### A folder of single-plane TIFFs
+
+Some acquisitions/stitching tools save **one TIFF per Z/C plane** instead of a
+single multi-page file, e.g.:
+
+```text
+sample_T0_Z000_C0_V0.tif
+sample_T0_Z000_C1_V0.tif
+sample_T0_Z001_C0_V0.tif
+sample_T0_Z001_C1_V0.tif
+...
+```
+
+Pass `sequence_pattern=` and let `source` be a glob over the folder instead of
+one file path. The pattern is a regex whose **named groups** map to axis
+labels — one file per group of indices:
+
+```python
+to_ome_zarr(
+    "sample/*.tif",
+    "sample.zarr",
+    sequence_pattern=r"_T(?P<T>\d+)_Z(?P<Z>\d+)_C(?P<C>\d+)_V\d+",
+    shard=True,  # recommended for large sequences, see Sharding below
+)
+```
+
+You don't need to order the named groups to match how the axes should come
+out: the result is always reordered to patchworks' `c, z, y, x` convention —
+required for `channel=` selection (`load_ome_zarr`/`tile_process` always read
+the channel from axis 0) — and a constant axis like `T0` above (one value, no
+real time series) is dropped automatically, the same way the bioio/Imaris
+readers already drop a singleton time axis.
+
+Each file becomes exactly **one dask chunk**, decoded lazily on access — no
+data is duplicated or eagerly loaded, so this scales to huge (multi-TB)
+sequences (built on `tifffile.TiffSequence`, the same mechanism Cellpose's
+own distributed pipeline uses). Pixel calibration is read automatically from
+the first file's own metadata — see [Pixel calibration](#pixel-calibration)
+below.
+
+Available on the cluster too: the Snakemake `convert` rule reads a
+`sequence_pattern:` key from the config (`input:` then being the glob), so a
+folder-of-TIFFs conversion runs through the same SLURM profile as any other
+input — see [Cluster usage](snakemake.md).
+
 !!! note "Imaris pyramids: rebuild (default) or reuse"
     `.ims` files carry their own resolution pyramid. By default `to_ome_zarr`
     reads only the **full-resolution** level and **builds a fresh NGFF pyramid**
@@ -64,9 +110,11 @@ to_ome_zarr("scan.ims", "scan.zarr")               # Imaris, native HDF5
 ### Pixel calibration
 
 The physical voxel size is read from the input — bioio's `physical_pixel_sizes`,
-the Imaris resolution metadata, or an existing OME-ZARR's scale — and written
-into the NGFF `coordinateTransformations` (in micrometers), so calibration is
-preserved regardless of input. Override or supply it for bare arrays with
+the Imaris resolution metadata, an existing OME-ZARR's scale, or (for a TIFF
+sequence) the first file's own ImageJ metadata (`spacing`/`unit`) or
+`XResolution`/`YResolution` tags — and written into the NGFF
+`coordinateTransformations` (in micrometers), so calibration is preserved
+regardless of input. Override or supply it for bare arrays with
 `pixel_size={"z": 2.0, "y": 0.32, "x": 0.32}`.
 
 ### Won't OOM

{patchworks-1.4.0 → patchworks-1.4.1}/src/patchworks/plugins/ome_zarr.py

@@ -701,15 +701,19 @@ def _open_tiff_sequence(
     sequence_pattern : str
         Regular expression parsing each file name into axis labels and
         indices, e.g. ``r"_T(?P<T>\\d+)_Z(?P<Z>\\d+)_C(?P<C>\\d+)_V\\d+"``.
-        Named groups become axis labels directly; axis order follows the
-        order groups appear in the pattern.
+        Named groups become axis labels directly — the order they appear in
+        the *pattern* (not the filename) doesn't matter, the result is
+        always reordered to patchworks' ``tczyx`` convention and any
+        singleton non-spatial axis (e.g. a constant ``T0``) is dropped, same
+        as the bioio/Imaris readers, so a real channel axis always ends up
+        first (required by :func:`patchworks.load_ome_zarr`).
 
     Returns
     -------
     tuple
         ``(array, axes, pixel_size)`` — a lazy dask array, its axes string
-        (parsed axes + trailing ``"yx"``) and a ``{axis: micrometers}``
-        calibration dict read from the first file.
+        (parsed axes, canonicalised, + trailing ``"yx"``) and a
+        ``{axis: micrometers}`` calibration dict read from the first file.
     """
     try:
         import tifffile
@@ -722,7 +726,33 @@ def _open_tiff_sequence(
 
     ts = tifffile.TiffSequence(pattern, pattern=sequence_pattern)
     arr = da.from_zarr(zarr.open(store=ts.aszarr()))
-    axes = ts.axes.lower() + "yx"
+    full_axes = ts.axes.lower() + "yx"
+
+    # Canonicalise to patchworks' tczyx axis order regardless of the order
+    # sequence_pattern's groups happen to appear in (unrecognised axes sort
+    # last, before y/x).
+    order = sorted(
+        range(len(full_axes)),
+        key=lambda i: (
+            _DEFAULT_ORDER.index(full_axes[i])
+            if full_axes[i] in _DEFAULT_ORDER
+            else len(_DEFAULT_ORDER)
+        ),
+    )
+    arr = arr.transpose(order)
+    ordered_axes = "".join(full_axes[i] for i in order)
+
+    # Drop singleton non-spatial axes (e.g. a constant T), matching
+    # _open_bioio/_open_imaris, so a real channel axis lands at position 0.
+    keep = [
+        i
+        for i, a in enumerate(ordered_axes)
+        if a in _SPATIAL_AXES or arr.shape[i] > 1
+    ]
+    index = tuple(slice(None) if i in keep else 0 for i in range(arr.ndim))
+    arr = arr[index]
+    axes = "".join(ordered_axes[i] for i in keep)
+
     pixel_size = _tiff_pixel_size(ts[0])
     logger.info(
         "tifffile sequence opened %s files as %s %s cal=%s",
@@ -979,8 +1009,11 @@ def to_ome_zarr(
         and indices via named groups, e.g.
         ``r"_T(?P<T>\\d+)_Z(?P<Z>\\d+)_C(?P<C>\\d+)_V\\d+"``. Each file
         becomes exactly one chunk, read lazily on access (no data
-        duplicated) — see :func:`tifffile.TiffSequence`. Axis order follows
-        the order named groups appear in the pattern.
+        duplicated) — see :func:`tifffile.TiffSequence`. The result is
+        always reordered to patchworks' ``czyx`` convention regardless of
+        the order named groups appear in the pattern, and any singleton
+        non-spatial axis (e.g. a constant ``T0``) is dropped, so a real
+        channel axis always ends up first.
     n_levels : int, optional
         Maximum number of pyramid levels including full resolution.
     downscale : int, optional

{patchworks-1.4.0 → patchworks-1.4.1}/tests/test_ome_zarr.py

@@ -80,7 +80,12 @@ def test_non_spatial_axis_not_downsampled(tmp_path):
 
 
 def test_tiff_sequence_conversion(tmp_path):
-    """A folder of single-plane TIFFs is wrapped lazily and converted."""
+    """A folder of single-plane TIFFs is wrapped lazily and converted.
+
+    The filename pattern lists Z before C, but the output must still come
+    out channel-first (patchworks' tczyx convention), since load_ome_zarr /
+    tile_process hard-assume axis 0 is the channel axis.
+    """
     tifffile = pytest.importorskip("tifffile")
     n_z, n_c, size = 3, 2, 8
     for z in range(n_z):
@@ -102,11 +107,43 @@ def test_tiff_sequence_conversion(tmp_path):
     )
 
     result = np.asarray(load_ome_zarr(out, channel=None))
-    assert result.shape == (n_z, n_c, size, size)
+    assert result.shape == (n_c, n_z, size, size)  # channel-first, not z-first
     # each plane's constant value encodes its (z, c) position.
-    assert (result[:, :, 0, 0] == [[z * 10 + c for c in range(n_c)] for z in range(n_z)]).all()
+    assert (
+        result[:, :, 0, 0]
+        == [[z * 10 + c for z in range(n_z)] for c in range(n_c)]
+    ).all()
     assert _level_scale(out, 0) == pytest.approx([1.0, 1.0, 0.5, 0.5])
 
+    # per-channel selection picks the right plane regardless of pattern order.
+    ch1 = np.asarray(load_ome_zarr(out, channel=1))
+    assert ch1.shape == (n_z, size, size)
+    assert (ch1[:, 0, 0] == [z * 10 + 1 for z in range(n_z)]).all()
+
+
+def test_tiff_sequence_drops_singleton_time_axis(tmp_path):
+    """A constant T in the pattern is dropped, keeping channel at axis 0."""
+    tifffile = pytest.importorskip("tifffile")
+    n_z, n_c, size = 2, 3, 8
+    for z in range(n_z):
+        for c in range(n_c):
+            img = np.full((size, size), z * 10 + c, dtype="uint16")
+            tifffile.imwrite(tmp_path / f"sample_T0_Z{z:03d}_C{c}_V0.tif", img)
+
+    out = tmp_path / "out.zarr"
+    to_ome_zarr(
+        str(tmp_path / "*.tif"),
+        out,
+        sequence_pattern=r"_T(?P<T>\d+)_Z(?P<Z>\d+)_C(?P<C>\d+)_V\d+",
+        n_levels=1,
+    )
+
+    result = np.asarray(load_ome_zarr(out, channel=None))
+    assert result.shape == (n_c, n_z, size, size)  # no leftover T axis
+    ch2 = np.asarray(load_ome_zarr(out, channel=2))
+    assert ch2.shape == (n_z, size, size)
+    assert (ch2[:, 0, 0] == [z * 10 + 2 for z in range(n_z)]).all()
+
 
 def test_axes_length_mismatch(tmp_path):
     with pytest.raises(ValueError):

{patchworks-1.4.0 → patchworks-1.4.1}/workflow/scripts/_pw.py

@@ -152,7 +152,9 @@ def build_fn(cfg):
     if dilate:
         from patchworks import dilate_labels
 
-        fn = dilate_labels(fn, iterations=dilate, use_gpu=cfg.get("dilate_gpu", False))
+        fn = dilate_labels(
+            fn, iterations=dilate, use_gpu=cfg.get("dilate_gpu", False)
+        )
 
     return fn