pyplatypus 0.2.0a1__tar.gz

pyplatypus-0.2.0a1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 Michał Maj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pyplatypus-0.2.0a1/MANIFEST.in

@@ -0,0 +1,11 @@
+# Without this, setuptools picks up tests/test_engine.py and nothing below it: top-level
+# test files are included by default, nested ones are not. Half a suite helps nobody, and
+# these tests carry a lot of the reasoning behind the design, so they all ship.
+graft tests
+include examples/data_science_bowl.yaml
+
+# Datasets, trained weights and run output never belong in a distribution.
+prune examples/data
+prune examples/output
+prune _legacy
+global-exclude __pycache__ *.py[cod] *.pt *.h5 *.hdf5

pyplatypus-0.2.0a1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: pyplatypus
+Version: 0.2.0a1
+Summary: Computer vision for medical imaging: the engine behind the platypus R package.
+Author-email: Michal Maj <michalmaj116@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maju116/pyplatypus
+Project-URL: Repository, https://github.com/maju116/pyplatypus
+Project-URL: Issues, https://github.com/maju116/pyplatypus/issues
+Project-URL: R package, https://github.com/maju116/platypus
+Keywords: computer-vision,segmentation,medical-imaging,u-net,pytorch,deep-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: albumentations>=1.4
+Requires-Dist: torch>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: pascal
+Requires-Dist: torch<2.8,>=2.7; extra == "pascal"
+Dynamic: license-file
+
+<img src="https://raw.githubusercontent.com/maju116/platypus/master/man/figures/hexsticker_platypus.png" align="right" alt="" width="130" />
+
+# pyplatypus
+
+**Computer vision for medical imaging — the engine behind the `platypus` R package.**
+
+> **0.2.0a1 — an alpha.** This replaces the 2022 TensorFlow package with a PyTorch one.
+> The API will still move and the R surface does not exist yet, so pin the exact version
+> if you build on it.
+>
+> Everything on PyPI so far is a pre-release, so `pip install pyplatypus` resolves to this
+> one. `pip install pyplatypus==0.1.0rc2` gets the old TensorFlow package.
+
+## What works today
+
+Semantic segmentation in 2D, end to end:
+
+- **One spec, two ways in.** Build it from arguments or load it from YAML — both produce
+  the same object, so nothing downstream can tell which you used.
+- **Four architectures**: U-Net, U-Net++, Res-U-Net, LinkNet, each composable with
+  separable convolutions, spatial dropout, learned or interpolated upsampling, deep
+  supervision and configurable block width.
+- **Nine losses** (IoU, Dice, CCE, CCE-Dice, Focal, Tversky, Focal-Tversky, Combo,
+  Lovász) and three metrics, all reducing over every axis except batch and channel — so
+  they already work on volumes.
+- **Tiling that goes both ways**: cut a large image into a grid instead of shrinking it,
+  and get a full-size mask back.
+- **Many models from one file**, with a comparison table at the end.
+
+3D, object detection, ensembling and pretrained backbones are deliberately out of scope
+for v0.1. The spec and the model builder already handle volumes; the data pipeline is
+where 3D stops.
+
+## Try it
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+```python
+from pyplatypus import Engine, from_yaml
+
+engine = Engine(from_yaml("examples/data_science_bowl.yaml"))
+engine.fit(verbose=True)
+
+for row in engine.evaluate():
+    print(row)
+
+masks = engine.predict(engine.best_model("dice"), split="test")
+```
+
+`examples/data_science_bowl.yaml` trains a U-Net and a LinkNet on the 2018 Data Science
+Bowl and prints a comparison. On a GTX 1070 that is about 11 seconds per epoch at
+160×160.
+
+## Requirements
+
+Python ≥ 3.10, and torch ≥ 2.7.
+
+**If your GPU is a GTX 10-series (Pascal) or older**, install the `pascal` extra:
+
+```bash
+pip install "pyplatypus[pascal]"
+```
+
+torch 2.8 and later ship CUDA 13 builds, and CUDA 13 dropped the Maxwell, Pascal and
+Volta generations outright - no driver update brings them back. The last torch built
+against CUDA 12 is 2.7.x, which the extra pins. On anything from Turing (RTX 20-series)
+onwards, ignore this.
+
+## Licence
+
+MIT.

pyplatypus-0.2.0a1/README.md

@@ -0,0 +1,75 @@
+<img src="https://raw.githubusercontent.com/maju116/platypus/master/man/figures/hexsticker_platypus.png" align="right" alt="" width="130" />
+
+# pyplatypus
+
+**Computer vision for medical imaging — the engine behind the `platypus` R package.**
+
+> **0.2.0a1 — an alpha.** This replaces the 2022 TensorFlow package with a PyTorch one.
+> The API will still move and the R surface does not exist yet, so pin the exact version
+> if you build on it.
+>
+> Everything on PyPI so far is a pre-release, so `pip install pyplatypus` resolves to this
+> one. `pip install pyplatypus==0.1.0rc2` gets the old TensorFlow package.
+
+## What works today
+
+Semantic segmentation in 2D, end to end:
+
+- **One spec, two ways in.** Build it from arguments or load it from YAML — both produce
+  the same object, so nothing downstream can tell which you used.
+- **Four architectures**: U-Net, U-Net++, Res-U-Net, LinkNet, each composable with
+  separable convolutions, spatial dropout, learned or interpolated upsampling, deep
+  supervision and configurable block width.
+- **Nine losses** (IoU, Dice, CCE, CCE-Dice, Focal, Tversky, Focal-Tversky, Combo,
+  Lovász) and three metrics, all reducing over every axis except batch and channel — so
+  they already work on volumes.
+- **Tiling that goes both ways**: cut a large image into a grid instead of shrinking it,
+  and get a full-size mask back.
+- **Many models from one file**, with a comparison table at the end.
+
+3D, object detection, ensembling and pretrained backbones are deliberately out of scope
+for v0.1. The spec and the model builder already handle volumes; the data pipeline is
+where 3D stops.
+
+## Try it
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+```python
+from pyplatypus import Engine, from_yaml
+
+engine = Engine(from_yaml("examples/data_science_bowl.yaml"))
+engine.fit(verbose=True)
+
+for row in engine.evaluate():
+    print(row)
+
+masks = engine.predict(engine.best_model("dice"), split="test")
+```
+
+`examples/data_science_bowl.yaml` trains a U-Net and a LinkNet on the 2018 Data Science
+Bowl and prints a comparison. On a GTX 1070 that is about 11 seconds per epoch at
+160×160.
+
+## Requirements
+
+Python ≥ 3.10, and torch ≥ 2.7.
+
+**If your GPU is a GTX 10-series (Pascal) or older**, install the `pascal` extra:
+
+```bash
+pip install "pyplatypus[pascal]"
+```
+
+torch 2.8 and later ship CUDA 13 builds, and CUDA 13 dropped the Maxwell, Pascal and
+Volta generations outright - no driver update brings them back. The last torch built
+against CUDA 12 is 2.7.x, which the extra pins. On anything from Turing (RTX 20-series)
+onwards, ignore this.
+
+## Licence
+
+MIT.

pyplatypus-0.2.0a1/examples/data_science_bowl.yaml

@@ -0,0 +1,89 @@
+# 2018 Data Science Bowl: find the nuclei.
+#
+# Two models, one file, one run. This is the whole point of the YAML path - and the
+# identical spec can be built from arguments in R and behave the same way.
+
+data:
+  train_path: examples/data/data_science_bowl/stage1_train
+  validation_path: examples/data/data_science_bowl/stage1_validation
+  test_path: examples/data/data_science_bowl/stage1_test
+  mode: nested_dirs
+  colormap:
+    - [0, 0, 0]          # background
+    - [255, 255, 255]    # nucleus
+  shuffle: true
+
+output_dir: examples/output
+seed: 0
+
+models:
+  - name: unet
+    architecture: u_net
+    input_shape: [160, 160]
+    channels: 3
+    n_class: 2
+    blocks: 4
+    filters: 16
+    dropout: 0.1
+    loss:
+      name: cce_dice
+      cce_weight: 0.5
+    metrics:
+      - name: dice
+        include_background: false    # nuclei are a small part of the picture
+      - name: iou
+        include_background: false
+    optimizer:
+      name: adam
+      learning_rate: 0.001
+    callbacks:
+      - name: early_stopping
+        monitor: val_dice
+        patience: 4
+      - name: model_checkpoint
+        path: examples/output/unet.pt
+        monitor: val_dice
+      - name: csv_logger
+        path: examples/output/unet_history.csv
+      - name: terminate_on_nan
+    augmentation:
+      - name: HorizontalFlip
+        params: {p: 0.5}
+      - name: VerticalFlip
+        params: {p: 0.5}
+      - name: RandomRotate90
+        params: {p: 0.5}
+    epochs: 6
+    batch_size: 8
+
+  - name: linknet
+    architecture: linknet
+    input_shape: [160, 160]
+    channels: 3
+    n_class: 2
+    blocks: 4
+    filters: 16
+    dropout: 0.1
+    loss:
+      name: focal_tversky
+      alpha: 0.7            # weight missed nuclei more than false alarms
+      gamma: 1.3
+    metrics:
+      - name: dice
+        include_background: false
+      - name: iou
+        include_background: false
+    optimizer:
+      name: adamw
+      learning_rate: 0.001
+    callbacks:
+      - name: early_stopping
+        monitor: val_dice
+        patience: 4
+      - name: model_checkpoint
+        path: examples/output/linknet.pt
+        monitor: val_dice
+      - name: csv_logger
+        path: examples/output/linknet_history.csv
+    epochs: 6
+    batch_size: 8

pyplatypus-0.2.0a1/pyplatypus/__init__.py

@@ -0,0 +1,23 @@
+"""pyplatypus - the engine behind the platypus R package.
+
+v0.1: specification, data pipeline, U-shaped models, losses and metrics, training.
+2D segmentation. The spec and the model builder already handle volumes; the data
+pipeline is where 3D stops for now.
+"""
+
+from pyplatypus.engine import Engine
+from pyplatypus.errors import ConfigError, PlatypusError
+from pyplatypus.spec import PlatypusSpec, from_dict, from_yaml, spec_schema, write_schema
+
+__version__ = "0.2.0a1"
+__all__ = [
+    "ConfigError",
+    "Engine",
+    "PlatypusError",
+    "PlatypusSpec",
+    "__version__",
+    "from_dict",
+    "from_yaml",
+    "spec_schema",
+    "write_schema",
+]

pyplatypus-0.2.0a1/pyplatypus/data/__init__.py

@@ -0,0 +1,16 @@
+from pyplatypus.data.augmentation import Augmenter, build_augmenter
+from pyplatypus.data.dataset import SegmentationDataset
+from pyplatypus.data.images import read_image, stitch, tile, to_float
+from pyplatypus.data.masks import (
+    classes_to_onehot,
+    colours_to_classes,
+    onehot_to_colours,
+    unite_masks,
+)
+from pyplatypus.data.paths import Discovery, Sample, discover
+
+__all__ = [
+    "Augmenter", "Discovery", "Sample", "SegmentationDataset", "build_augmenter",
+    "classes_to_onehot", "colours_to_classes", "discover", "onehot_to_colours",
+    "read_image", "stitch", "tile", "to_float", "unite_masks",
+]

pyplatypus-0.2.0a1/pyplatypus/data/augmentation.py

@@ -0,0 +1,77 @@
+"""Augmentation, behind an interface.
+
+PLAN.md rule 4: the spec names transforms, it does not import a library. albumentations
+is the backend; swapping or adding one later must not touch a single spec.
+
+Masks travel through here as class indices, never as one-hot or RGB, so a geometric
+transform moves labels around instead of blending them into colours that match no class.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import numpy as np
+
+from pyplatypus.errors import PlatypusError
+from pyplatypus.spec.components import AugmentationStep
+
+
+class AugmentationError(PlatypusError):
+    kind = "augmentation_error"
+
+
+class Augmenter(Protocol):
+    """Takes an image and its class-index mask, returns both transformed."""
+
+    def __call__(self, image: np.ndarray, mask: np.ndarray | None = None
+                 ) -> tuple[np.ndarray, np.ndarray | None]: ...
+
+
+class AlbumentationsAugmenter:
+    def __init__(self, steps: list[AugmentationStep]):
+        try:
+            import albumentations
+        except ImportError:  # pragma: no cover
+            raise AugmentationError(
+                "augmentation was requested but albumentations is not installed"
+            ) from None
+
+        built = []
+        for step in steps:
+            factory = getattr(albumentations, step.name, None)
+            if factory is None:
+                raise AugmentationError(
+                    f"albumentations {albumentations.__version__} has no transform "
+                    f"'{step.name}'"
+                )
+            try:
+                built.append(factory(**step.params))
+            except TypeError as error:
+                raise AugmentationError(
+                    f"'{step.name}' rejected its parameters {step.params}: {error}"
+                ) from None
+        self._pipeline = albumentations.Compose(built)
+        self.steps = tuple(step.name for step in steps)
+
+    def __call__(self, image: np.ndarray, mask: np.ndarray | None = None
+                 ) -> tuple[np.ndarray, np.ndarray | None]:
+        if mask is None:
+            return self._pipeline(image=image)["image"], None
+        out = self._pipeline(image=image, mask=mask)
+        return out["image"], out["mask"]
+
+
+def build_augmenter(steps: list[AugmentationStep] | None, rank: int = 2
+                    ) -> Augmenter | None:
+    """None when there is nothing to do, which keeps the caller free of special cases."""
+    if not steps:
+        return None
+    if rank != 2:
+        # albumentations 2.x does ship 3D transforms (CenterCrop3D, CubicSymmetry and
+        # friends) through a different call signature, so this is a v0.1 scope line
+        # rather than a missing capability.
+        raise AugmentationError(
+            f"augmentation is implemented for 2D only; this spec is {rank}D"
+        )
+    return AlbumentationsAugmenter(steps)

pyplatypus-0.2.0a1/pyplatypus/data/dataset.py

@@ -0,0 +1,116 @@
+"""One sample in, one training example out.
+
+Numpy only. The torch `Dataset` wrapper is a dozen lines and arrives in step 3; keeping
+it out of here means this layer stays fast to test and usable on its own.
+
+Arrays are channels-last throughout, because that is what albumentations and PIL speak.
+The torch adapter transposes once, at the boundary.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+import numpy as np
+
+from pyplatypus.data.augmentation import Augmenter
+from pyplatypus.data.images import read_image, tile, to_float
+from pyplatypus.data.masks import classes_to_onehot, colours_to_classes, unite_masks
+from pyplatypus.data.paths import Sample
+from pyplatypus.errors import PlatypusError
+from pyplatypus.spec.data import SegmentationData
+from pyplatypus.spec.models import SegmentationModel
+
+
+class DataError(PlatypusError):
+    kind = "data_error"
+
+
+class SegmentationDataset:
+    """Samples on disk, presented as (image, one-hot mask) pairs.
+
+    When the model tiles, one source image becomes several examples, so `len()` is
+    samples x tiles and indexing walks the tiles of a sample before moving on.
+    """
+
+    def __init__(self, samples: tuple[Sample, ...], model: SegmentationModel,
+                 data: SegmentationData, *, augmenter: Augmenter | None = None,
+                 only_images: bool = False, cache_size: int = 8):
+        if model.rank != 2:
+            raise DataError(f"the 2D pipeline cannot serve a {model.rank}D model")
+        self.samples = samples
+        self.model = model
+        self.data = data
+        self.augmenter = augmenter
+        self.only_images = only_images
+        self._cache: OrderedDict[int, tuple[np.ndarray, np.ndarray | None]] = OrderedDict()
+        self._cache_size = max(1, cache_size)
+
+    @property
+    def tiles_per_sample(self) -> int:
+        return self.model.tiles_per_image
+
+    def __len__(self) -> int:
+        return len(self.samples) * self.tiles_per_sample
+
+    def _load(self, index: int) -> tuple[np.ndarray, np.ndarray | None]:
+        """Read one source sample at `load_shape`, cached because every tile asks again."""
+        if index in self._cache:
+            self._cache.move_to_end(index)
+            return self._cache[index]
+
+        sample = self.samples[index]
+        size = self.model.load_shape
+        image = read_image(sample.image, channels=self.model.channels, size=size)
+
+        classes: np.ndarray | None = None
+        if not self.only_images:
+            # Nearest, always: interpolating a mask invents colours that belong to no
+            # class and would quietly become background.
+            masks = [read_image(p, channels=3, size=size, nearest=True) for p in sample.masks]
+            united = unite_masks(masks)
+            classes, _ = colours_to_classes(united, self.data.colormap)
+
+        self._cache[index] = (image, classes)
+        if len(self._cache) > self._cache_size:
+            self._cache.popitem(last=False)
+        return image, classes
+
+    def __getitem__(self, index: int) -> tuple[np.ndarray, np.ndarray | None]:
+        if index < 0:
+            index += len(self)
+        if not 0 <= index < len(self):
+            raise IndexError(f"index {index} is outside 0..{len(self) - 1}")
+
+        sample_index, tile_index = divmod(index, self.tiles_per_sample)
+        image, classes = self._load(sample_index)
+
+        if self.model.splits is not None:
+            image = tile(image, self.model.splits)[tile_index]
+            if classes is not None:
+                classes = tile(classes[..., None], self.model.splits)[tile_index][..., 0]
+
+        if self.augmenter is not None:
+            image, classes = self.augmenter(image, classes)
+
+        image = to_float(image)
+        if classes is None:
+            return image, None
+        return image, classes_to_onehot(classes, self.model.n_class)
+
+    def colormap_coverage(self, limit: int = 20) -> float:
+        """Fraction of mask pixels matching no colour in the colormap.
+
+        A number near 1 means the colormap does not describe this dataset - the single
+        most common way a segmentation run silently trains on nothing.
+        """
+        if self.only_images:
+            raise DataError("there are no masks to check")
+        unmatched = []
+        for index in range(min(limit, len(self.samples))):
+            sample = self.samples[index]
+            masks = [read_image(p, channels=3, size=self.model.load_shape, nearest=True)
+                     for p in sample.masks]
+            _, fraction = colours_to_classes(unite_masks(masks), self.data.colormap)
+            unmatched.append(fraction)
+        return float(np.mean(unmatched))

pyplatypus-0.2.0a1/pyplatypus/data/images.py

@@ -0,0 +1,121 @@
+"""Reading pixels, and cutting them up.
+
+`tile` and `stitch` are inverses, and there is a round-trip test that says so. The old
+package could only tile: an HD image went in as a grid of pieces and the predicted pieces
+were never put back together, which defeated the purpose of tiling it.
+
+Everything is rank-generic. A 2D grid and a 3D patch grid are the same operation.
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from pyplatypus.errors import PlatypusError
+
+# PIL talks in (width, height); every shape in this package is (height, width). Mixing
+# them is the classic silent bug, so the conversion happens in exactly one place.
+_PIL_MODE = {1: "L", 3: "RGB", 4: "RGBA"}
+
+
+class ImageError(PlatypusError):
+    kind = "image_error"
+
+
+def read_image(path: str | Path, *, channels: int = 3,
+               size: tuple[int, ...] | None = None,
+               nearest: bool = False) -> np.ndarray:
+    """Read one image as a channels-last float32 array scaled to 0-1.
+
+    `nearest` must be used for masks: interpolating a mask invents colours that match no
+    class, which then silently become background.
+    """
+    mode = _PIL_MODE.get(channels)
+    if mode is None:
+        raise ImageError(f"channels must be 1, 3 or 4 for ordinary images, got {channels}")
+
+    try:
+        with Image.open(path) as handle:
+            picture = handle.convert(mode)
+            if size is not None:
+                if len(size) != 2:
+                    raise ImageError(
+                        f"2D readers take a (height, width), got {tuple(size)}"
+                    )
+                resample = Image.Resampling.NEAREST if nearest else Image.Resampling.BILINEAR
+                picture = picture.resize((size[1], size[0]), resample=resample)
+            array = np.asarray(picture, dtype=np.uint8)
+    except OSError as error:
+        raise ImageError(f"could not read '{path}': {error}") from None
+
+    if array.ndim == 2:
+        array = array[..., None]
+    return array
+
+
+def to_float(array: np.ndarray) -> np.ndarray:
+    """0-255 integers to 0-1 floats, leaving anything already floating alone."""
+    if np.issubdtype(array.dtype, np.floating):
+        return array.astype(np.float32, copy=False)
+    return array.astype(np.float32) / 255.0
+
+
+def tile(array: np.ndarray, splits: tuple[int, ...]) -> np.ndarray:
+    """Cut a channels-last array into a grid of tiles.
+
+    Returns shape (n_tiles, *tile_shape, channels), in row-major order: for splits (2, 3)
+    the tiles come out as (0,0), (0,1), (0,2), (1,0), (1,1), (1,2). `stitch` relies on
+    that order.
+    """
+    rank = len(splits)
+    spatial = array.shape[:rank]
+    if array.ndim != rank + 1:
+        raise ImageError(
+            f"expected {rank} spatial dimensions plus channels, got shape {array.shape}"
+        )
+    bad = [(size, n) for size, n in zip(spatial, splits, strict=True) if size % n]
+    if bad:
+        raise ImageError(
+            f"cannot cut {spatial} into {splits}: every dimension must divide exactly"
+        )
+
+    tile_shape = tuple(size // n for size, n in zip(spatial, splits, strict=True))
+    channels = array.shape[-1]
+
+    # (s0, t0, s1, t1, ..., C) -> (s0, s1, ..., t0, t1, ..., C)
+    interleaved = []
+    for n, t in zip(splits, tile_shape, strict=True):
+        interleaved.extend((n, t))
+    reshaped = array.reshape(*interleaved, channels)
+    order = [2 * i for i in range(rank)] + [2 * i + 1 for i in range(rank)] + [2 * rank]
+    return reshaped.transpose(order).reshape(math.prod(splits), *tile_shape, channels)
+
+
+def stitch(tiles: np.ndarray, splits: tuple[int, ...]) -> np.ndarray:
+    """Put tiles produced by `tile` back into one array. The inverse of `tile`."""
+    rank = len(splits)
+    expected = math.prod(splits)
+    if tiles.shape[0] != expected:
+        raise ImageError(
+            f"splits {splits} needs {expected} tiles, got {tiles.shape[0]}"
+        )
+    if tiles.ndim != rank + 2:
+        raise ImageError(
+            f"expected tiles shaped (n, {'x'.join('t' * rank)}, channels), "
+            f"got {tiles.shape}"
+        )
+
+    tile_shape = tiles.shape[1:-1]
+    channels = tiles.shape[-1]
+    grouped = tiles.reshape(*splits, *tile_shape, channels)
+    # (s0, s1, ..., t0, t1, ..., C) -> (s0, t0, s1, t1, ..., C)
+    order: list[int] = []
+    for i in range(rank):
+        order.extend((i, rank + i))
+    order.append(2 * rank)
+    full = tuple(n * t for n, t in zip(splits, tile_shape, strict=True))
+    return grouped.transpose(order).reshape(*full, channels)