patchworks 0.4.0__tar.gz → 0.6.0__tar.gz

{patchworks-0.4.0 → patchworks-0.6.0}/.github/workflows/docs.yml

@@ -4,6 +4,10 @@ on:
   push:
     branches:
       - main
+  # Rebuild after each release so the version shown in the header refreshes.
+  release:
+    types: [published]
+  workflow_dispatch:
 
 permissions:
   contents: write

{patchworks-0.4.0 → patchworks-0.6.0}/.github/workflows/lint.yml

@@ -15,9 +15,11 @@ jobs:
       - name: ruff check
         uses: astral-sh/ruff-action@v3
         with:
+          version: "0.15.18"
           args: "check"
 
       - name: ruff format --check
         uses: astral-sh/ruff-action@v3
         with:
+          version: "0.15.18"
           args: "format --check"

{patchworks-0.4.0 → patchworks-0.6.0}/.github/workflows/release.yml

@@ -48,3 +48,17 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Rebuild the org-wide pdoc apidocs site so it picks up the new version.
+  apidocs:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger imcf.github.io apidocs rebuild
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          # Fine-grained PAT with "Contents: write" on imcf/imcf.github.io,
+          # stored as the APIDOCS_DISPATCH_TOKEN secret in this repo.
+          token: ${{ secrets.APIDOCS_DISPATCH_TOKEN }}
+          repository: imcf/imcf.github.io
+          event-type: dispatch-event

{patchworks-0.4.0 → patchworks-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -29,6 +29,7 @@ Requires-Dist: bioio-lif; extra == 'all'
 Requires-Dist: bioio-nd2; extra == 'all'
 Requires-Dist: bioio-ome-tiff; extra == 'all'
 Requires-Dist: bioio-tifffile; extra == 'all'
+Requires-Dist: imaris-ims-file-reader; extra == 'all'
 Requires-Dist: nvidia-ml-py; extra == 'all'
 Requires-Dist: psutil; extra == 'all'
 Requires-Dist: scikit-image; extra == 'all'
@@ -54,6 +55,8 @@ Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: gpu
 Requires-Dist: nvidia-ml-py; extra == 'gpu'
+Provides-Extra: imaris
+Requires-Dist: imaris-ims-file-reader; extra == 'imaris'
 Provides-Extra: io
 Requires-Dist: psutil; extra == 'io'
 Requires-Dist: tqdm; extra == 'io'
@@ -71,7 +74,7 @@ Description-Content-Type: text/markdown
 > Tiled processing of arbitrarily large images — any image, any function.
 
 ```
-┌──────┬──────┬──────┐     fn(tile) → labels     ┌──────┬──────┬──────┐
+┌──────┬──────┬──────┐     fn(tile) → labels      ┌──────┬──────┬──────┐
 │ tile │ tile │ tile │  ─────────────────────►    │  1   │  2   │  3   │
 ├──────┼──────┼──────┤                            ├──────┼──────┼──────┤
 │ tile │ tile │ tile │                            │  4   │  5   │  6   │   globally
@@ -98,6 +101,7 @@ Optional extras:
 pip install "patchworks[gpu]"      # GPU VRAM querying (nvidia-ml-py)
 pip install "patchworks[cellpose]" # Cellpose plugin
 pip install "patchworks[bioio]"    # convert any image format to OME-ZARR
+pip install "patchworks[imaris]"   # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"   # interactive napari viewer plugin
 pip install "patchworks[all]"      # Everything (except napari GUI)
 ```
@@ -105,6 +109,8 @@ pip install "patchworks[all]"      # Everything (except napari GUI)
 > `bioio` reads CZI/LIF/ND2/OME-TIFF/… The `[bioio]` extra bundles the common
 > native readers (`bioio-nd2`, `bioio-ome-tiff`, `bioio-czi`, `bioio-tifffile`,
 > `bioio-lif`) plus `bioio-bioformats`, the Bio-Formats catch-all reader (JVM).
+> `[imaris]` adds native `.ims` support (HDF5, no JVM). Physical pixel
+> calibration is read from the input and written into the OME-ZARR.
 
 ---
 
@@ -121,11 +127,15 @@ def my_fn(tile):
     return label(tile > threshold_otsu(tile)).astype("int32")
 
 
-result = tile_process("image.zarr", my_fn, compute=True)
+result = tile_process("image.zarr", my_fn)
 ```
 
-Done. `result` is a NumPy array of integer labels, same spatial shape as the
-input, with globally unique IDs across all tiles.
+Done. `result` is a **lazy dask array** of integer labels (call `.compute()`
+for a NumPy array), same spatial shape as the input, with globally unique IDs
+across all tiles. By default the labels are also written **into the input
+store** at `image.zarr/labels/labels/` as a multi-scale pyramid, so the image
+and its segmentation live in one OME-ZARR. Pass `write_to="labels.zarr"` to
+write a separate store instead.
 
 ---
 
@@ -197,6 +207,26 @@ tile_process("image.zarr", my_custom_fn, tile_shape=(1, 512, 512))
 
 ---
 
+## Convert to OME-ZARR & view in napari
+
+Optional plugins close the loop: convert any image (Imaris `.ims`, CZI, LIF,
+ND2, OME-TIFF, … via bioio) to a pyramidal, **calibrated** OME-ZARR, then view
+the image and its labels in napari.
+
+```python
+from patchworks.plugins.ome_zarr import to_ome_zarr
+from patchworks.plugins.napari import view_in_napari
+
+to_ome_zarr("scan.ims", "scan.zarr")          # lazy, OOM-safe, keeps µm calibration
+view_in_napari("scan.zarr", labels="scan.zarr/labels/labels")
+```
+
+Pyramids downsample **X/Y only** (Z kept full-res) and are built level-by-level
+from disk, so terabyte volumes convert in bounded RAM. See the
+[OME-ZARR & napari guide](https://imcf.one/patchworks/guide/ome_zarr_napari/).
+
+---
+
 ## Common patterns
 
 ### Auto-size tiles from available memory
@@ -282,8 +312,8 @@ merged = merge_tile_labels(
 
 ## How tiling and merging work
 
-See [docs/how-it-works.md](docs/how-it-works.md) for a full explanation.
-Short version:
+See the [Merging labels guide](https://imcf.one/patchworks/guide/merging/) for
+a full explanation. Short version:
 
 1. Image is split into tiles (with optional overlap for boundary context).
 2. Your function is called independently on each tile. Dask handles parallelism
@@ -313,10 +343,15 @@ tiles where the dask-image approach stalls.
 
 ## Documentation
 
-- [Quick Start](docs/quickstart.md)
-- [API Reference](docs/api-reference.md)
-- [How It Works](docs/how-it-works.md)
-- [Examples](docs/examples/)
+Full docs, guides and tutorials: **<https://imcf.one/patchworks/>**
+
+- [Getting Started](https://imcf.one/patchworks/getting_started/)
+- [User Guide](https://imcf.one/patchworks/guide/tiling/) — tiling, merging,
+  empty-tile skipping, GPU/distributed, OME-ZARR & napari, pitfalls
+- [Examples](https://imcf.one/patchworks/examples/cellpose_2d/) — Cellpose,
+  StarDist, custom functions, standalone merge
+- [API Reference](https://imcf.one/patchworks/api/tile_process/) ·
+  [pdoc API](https://imcf.one/apidocs/patchworks/)
 
 ---
 
@@ -329,7 +364,11 @@ Optional:
 - `psutil` — accurate RAM sizing for `tile_shape="auto"`
 - `nvidia-ml-py` — accurate GPU VRAM sizing
 - `tqdm` — progress bars
-- `cellpose` — Cellpose plugin
+- `cellpose` — Cellpose plugin (`patchworks[cellpose]`)
+- `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
+  (`patchworks[bioio]`)
+- `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)
+- `napari` — interactive viewer plugin (`patchworks[napari]`)
 
 ---
 

{patchworks-0.4.0 → patchworks-0.6.0}/README.md

@@ -8,7 +8,7 @@
 > Tiled processing of arbitrarily large images — any image, any function.
 
 ```
-┌──────┬──────┬──────┐     fn(tile) → labels     ┌──────┬──────┬──────┐
+┌──────┬──────┬──────┐     fn(tile) → labels      ┌──────┬──────┬──────┐
 │ tile │ tile │ tile │  ─────────────────────►    │  1   │  2   │  3   │
 ├──────┼──────┼──────┤                            ├──────┼──────┼──────┤
 │ tile │ tile │ tile │                            │  4   │  5   │  6   │   globally
@@ -35,6 +35,7 @@ Optional extras:
 pip install "patchworks[gpu]"      # GPU VRAM querying (nvidia-ml-py)
 pip install "patchworks[cellpose]" # Cellpose plugin
 pip install "patchworks[bioio]"    # convert any image format to OME-ZARR
+pip install "patchworks[imaris]"   # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"   # interactive napari viewer plugin
 pip install "patchworks[all]"      # Everything (except napari GUI)
 ```
@@ -42,6 +43,8 @@ pip install "patchworks[all]"      # Everything (except napari GUI)
 > `bioio` reads CZI/LIF/ND2/OME-TIFF/… The `[bioio]` extra bundles the common
 > native readers (`bioio-nd2`, `bioio-ome-tiff`, `bioio-czi`, `bioio-tifffile`,
 > `bioio-lif`) plus `bioio-bioformats`, the Bio-Formats catch-all reader (JVM).
+> `[imaris]` adds native `.ims` support (HDF5, no JVM). Physical pixel
+> calibration is read from the input and written into the OME-ZARR.
 
 ---
 
@@ -58,11 +61,15 @@ def my_fn(tile):
     return label(tile > threshold_otsu(tile)).astype("int32")
 
 
-result = tile_process("image.zarr", my_fn, compute=True)
+result = tile_process("image.zarr", my_fn)
 ```
 
-Done. `result` is a NumPy array of integer labels, same spatial shape as the
-input, with globally unique IDs across all tiles.
+Done. `result` is a **lazy dask array** of integer labels (call `.compute()`
+for a NumPy array), same spatial shape as the input, with globally unique IDs
+across all tiles. By default the labels are also written **into the input
+store** at `image.zarr/labels/labels/` as a multi-scale pyramid, so the image
+and its segmentation live in one OME-ZARR. Pass `write_to="labels.zarr"` to
+write a separate store instead.
 
 ---
 
@@ -134,6 +141,26 @@ tile_process("image.zarr", my_custom_fn, tile_shape=(1, 512, 512))
 
 ---
 
+## Convert to OME-ZARR & view in napari
+
+Optional plugins close the loop: convert any image (Imaris `.ims`, CZI, LIF,
+ND2, OME-TIFF, … via bioio) to a pyramidal, **calibrated** OME-ZARR, then view
+the image and its labels in napari.
+
+```python
+from patchworks.plugins.ome_zarr import to_ome_zarr
+from patchworks.plugins.napari import view_in_napari
+
+to_ome_zarr("scan.ims", "scan.zarr")          # lazy, OOM-safe, keeps µm calibration
+view_in_napari("scan.zarr", labels="scan.zarr/labels/labels")
+```
+
+Pyramids downsample **X/Y only** (Z kept full-res) and are built level-by-level
+from disk, so terabyte volumes convert in bounded RAM. See the
+[OME-ZARR & napari guide](https://imcf.one/patchworks/guide/ome_zarr_napari/).
+
+---
+
 ## Common patterns
 
 ### Auto-size tiles from available memory
@@ -219,8 +246,8 @@ merged = merge_tile_labels(
 
 ## How tiling and merging work
 
-See [docs/how-it-works.md](docs/how-it-works.md) for a full explanation.
-Short version:
+See the [Merging labels guide](https://imcf.one/patchworks/guide/merging/) for
+a full explanation. Short version:
 
 1. Image is split into tiles (with optional overlap for boundary context).
 2. Your function is called independently on each tile. Dask handles parallelism
@@ -250,10 +277,15 @@ tiles where the dask-image approach stalls.
 
 ## Documentation
 
-- [Quick Start](docs/quickstart.md)
-- [API Reference](docs/api-reference.md)
-- [How It Works](docs/how-it-works.md)
-- [Examples](docs/examples/)
+Full docs, guides and tutorials: **<https://imcf.one/patchworks/>**
+
+- [Getting Started](https://imcf.one/patchworks/getting_started/)
+- [User Guide](https://imcf.one/patchworks/guide/tiling/) — tiling, merging,
+  empty-tile skipping, GPU/distributed, OME-ZARR & napari, pitfalls
+- [Examples](https://imcf.one/patchworks/examples/cellpose_2d/) — Cellpose,
+  StarDist, custom functions, standalone merge
+- [API Reference](https://imcf.one/patchworks/api/tile_process/) ·
+  [pdoc API](https://imcf.one/apidocs/patchworks/)
 
 ---
 
@@ -266,7 +298,11 @@ Optional:
 - `psutil` — accurate RAM sizing for `tile_shape="auto"`
 - `nvidia-ml-py` — accurate GPU VRAM sizing
 - `tqdm` — progress bars
-- `cellpose` — Cellpose plugin
+- `cellpose` — Cellpose plugin (`patchworks[cellpose]`)
+- `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
+  (`patchworks[bioio]`)
+- `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)
+- `napari` — interactive viewer plugin (`patchworks[napari]`)
 
 ---
 

{patchworks-0.4.0 → patchworks-0.6.0}/docs/examples/custom.md

@@ -17,7 +17,7 @@ def threshold_fn(tile: np.ndarray) -> np.ndarray:
     return label(tile > thr).astype("int32")
 
 
-result = tile_process("image.zarr", threshold_fn, compute=True)
+result = tile_process("image.zarr", threshold_fn)
 ```
 
 ## Gaussian + morphological operations
@@ -86,12 +86,12 @@ from patchworks import tile_process
 
 # From any array-like source
 arr = da.from_array(my_numpy_array, chunks=(1, 1024, 1024))
-result = tile_process(arr, my_fn, compute=True)
+result = tile_process(arr, my_fn)
 
 # From tifffile
 import tifffile
 import dask.array as da
 
 arr = da.from_array(tifffile.imread("image.tif", aszarr=True))
-result = tile_process(arr, my_fn, compute=True)
+result = tile_process(arr, my_fn)
 ```

{patchworks-0.4.0 → patchworks-0.6.0}/docs/examples/custom_method.py

@@ -41,8 +41,7 @@ result = tile_process(
     my_fn,
     tile_shape=(1, 512, 512),
     overlap=16,
-    compute=True,
     progress=True,
 )
 
-print(f"Found {result.max()} objects")
+print(f"Found {int(result.max().compute())} objects")

{patchworks-0.4.0 → patchworks-0.6.0}/docs/getting_started.md

@@ -89,9 +89,11 @@ objects spanning tile boundaries are merged into a single label.
     ```python
     from patchworks import tile_process
 
-    result = tile_process("image.zarr", my_fn, compute=True)
+    # returns a lazy dask array; labels are also written into image.zarr by
+    # default (image.zarr/labels/labels/, as a pyramid)
+    result = tile_process("image.zarr", my_fn)
     print(result.shape)  # (z, y, x)
-    print(result.max())  # number of objects found
+    print(int(result.max().compute()))  # number of objects found
     ```
 
 === "From a dask array"
@@ -101,7 +103,7 @@ objects spanning tile boundaries are merged into a single label.
     from patchworks import tile_process
 
     arr = da.from_zarr("image.zarr")
-    result = tile_process(arr, my_fn, compute=True)
+    result = tile_process(arr, my_fn)
     ```
 
 === "Stream to zarr (recommended for large images)"

{patchworks-0.4.0 → patchworks-0.6.0}/docs/guide/ome_zarr_napari.md

@@ -38,19 +38,33 @@ existed.
 
 ## Convert any image to OME-ZARR
 
-`to_ome_zarr` accepts a dask/NumPy array, an existing `.zarr` store, or **any
-file format** readable by [bioio](https://github.com/bioio-devs/bioio) (CZI,
-LIF, ND2, OME-TIFF, …). File inputs are read **lazily** — pixels stream from
-disk and are written level by level through dask, so terabyte images convert in
-bounded RAM.
+`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**.
 
 ```python
 from patchworks.plugins.ome_zarr import to_ome_zarr
 
-# From a proprietary microscope file (lazy, via bioio):
-to_ome_zarr("scan.czi", "scan.zarr", n_levels=5)
+to_ome_zarr("scan.czi", "scan.zarr", n_levels=5)   # via bioio
+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
+`pixel_size={"z": 2.0, "y": 0.32, "x": 0.32}`.
+
+### Won't OOM
+
+Each pyramid level is built by reading the **previous level back from disk**
+and streaming the downsampled result out through dask with bounded chunks. The
+graph never chains level-on-level and no whole plane/volume is held in RAM, so
+terabyte images convert in bounded memory.
+
 !!! note "Install the readers you need"
     `pip install "patchworks[bioio]"` pulls `bioio` plus the `bioio-bioformats`
     catch-all reader (needs a JVM). For speed, add native readers for your

patchworks-0.6.0/docs/guide/performance.md

@@ -0,0 +1,60 @@
+# Performance & memory safety
+
+`tile_process` is built so a run **adapts to whatever machine it lands on** and
+can't run out of RAM/VRAM or freeze the box — without you tuning anything.
+
+## Automatic, machine-aware concurrency
+
+The staging step (running your `fn` once per tile to a temp store) and the
+merge step are sized to the host automatically:
+
+- **GPU** (`use_gpu=True`) → **one tile at a time**, so concurrent evaluations
+  can never exhaust VRAM.
+- **CPU** → as many tiles in flight as fit **80 % of available RAM** (estimated
+  from the tile size), and always **leaving one core free** so the machine
+  stays responsive — it never pins every core.
+
+The RAM figure is read live via `psutil`; without it, a conservative default is
+used instead of guessing high.
+
+## Overriding the worker count
+
+```python
+from patchworks import tile_process
+
+# let patchworks pick (recommended)
+tile_process("scan.zarr", fn)
+
+# or cap it yourself (staging threads + merge processes)
+tile_process("scan.zarr", fn, max_workers=8)
+```
+
+`max_workers` bounds both staging and merging. A running **distributed client**
+manages its own concurrency, so the override is skipped there — configure the
+cluster's memory limits instead.
+
+## Why it won't OOM or freeze
+
+| Resource | Guard |
+|----------|-------|
+| RAM | concurrent tiles × tile size × overhead ≤ 80 % of available RAM |
+| VRAM | GPU path runs one tile at a time |
+| CPU | always leaves at least one core free |
+| Disk I/O | each pyramid/stage level is streamed chunk-by-chunk; no whole volume in memory |
+
+The staging graph itself is kept small — a single fused `map_overlap`
+(halo → `fn` → trim) rather than three separate passes — and there is **no**
+extra read-back of the staged data.
+
+## Getting more speed
+
+- `tile_shape="auto"` sizes tiles to free RAM (or VRAM with `use_gpu=True`).
+- `skip_empty=True` with `estimate_empty_tiles()` skips background tiles.
+- A Dask **distributed** cluster (`make_local_cluster`) parallelises across
+  workers/GPUs; patchworks then defers concurrency to the cluster.
+
+!!! note "What doesn't help here"
+    The merge and relabel steps are already vectorised NumPy + SciPy (C-level)
+    with no per-voxel Python loop, and the pipeline is I/O-bound — so `numba`,
+    `cupy`, `arrow` and `xarray` bring essentially nothing. The real levers are
+    tile size, concurrency (above) and zarr chunking.

{patchworks-0.4.0 → patchworks-0.6.0}/docs/index.md

@@ -53,7 +53,7 @@ def my_fn(tile):
     return label(tile > threshold_otsu(tile)).astype("int32")
 
 
-result = tile_process("image.zarr", my_fn, compute=True)
+result = tile_process("image.zarr", my_fn)
 ```
 
 Any function. Any image.

{patchworks-0.4.0 → patchworks-0.6.0}/mkdocs.yml

@@ -22,9 +22,11 @@ theme:
   - content.code.annotate
   - content.code.copy
   - content.tabs.link
-  - navigation.tabs
+  - navigation.expand
+  - navigation.sections
   - navigation.top
   - navigation.footer
+  - toc.integrate
   - search.highlight
   - search.share
 
@@ -36,6 +38,7 @@ nav:
   - Merging labels: guide/merging.md
   - Empty tile skipping: guide/skip_empty.md
   - GPU & distributed: guide/gpu_distributed.md
+  - Performance & memory: guide/performance.md
   - OME-ZARR & napari: guide/ome_zarr_napari.md
   - Pitfalls: guide/pitfalls.md
 - Examples:

{patchworks-0.4.0 → patchworks-0.6.0}/pyproject.toml

@@ -54,11 +54,13 @@ bioio = [
     "bioio-tifffile",
     "bioio-lif",
 ]
+# imaris reads .ims files natively (HDF5, no JVM) for OME-ZARR conversion.
+imaris = ["imaris-ims-file-reader"]
 # napari enables the interactive viewer plugin (GUI-heavy, kept out of [all]).
 napari = ["napari[all]"]
 dev = ["pytest", "pytest-cov", "scikit-image", "psutil", "tqdm"]
 docs = ["mkdocs-material>=9.0", "mkdocstrings[python]>=0.24"]
-all = ["patchworks[io,gpu,bioio]", "psutil", "tqdm", "scikit-image"]
+all = ["patchworks[io,gpu,bioio,imaris]", "psutil", "tqdm", "scikit-image"]
 
 [project.urls]
 Homepage = "https://github.com/imcf/patchworks"

{patchworks-0.4.0 → patchworks-0.6.0}/src/patchworks/_chunks.py

@@ -57,6 +57,51 @@ def _get_available_memory() -> int:
         return 8 * 1024**3
 
 
+def safe_worker_count(
+    tile_nbytes: int,
+    *,
+    use_gpu: bool = False,
+    fn_overhead: int = 4,
+    ram_fraction: float = 0.8,
+) -> int:
+    """Concurrent tiles that fit the machine without OOM or a CPU freeze.
+
+    Bounds the threaded scheduler by two limits and takes the smaller:
+
+    * **CPU** — leaves at least one core free so the box stays responsive
+      (never pins every core).
+    * **RAM** — at most ``ram_fraction`` of available memory, assuming each
+      in-flight tile needs ``fn_overhead`` copies (halo + output + temporaries).
+
+    On GPU the answer is always 1: one evaluation at a time so concurrent
+    tiles can never exhaust VRAM. Without ``psutil`` it returns a conservative
+    default rather than guessing high.
+
+    Parameters
+    ----------
+    tile_nbytes : int
+        Size of one tile in bytes (``prod(tile_shape) * dtype.itemsize``).
+    use_gpu : bool, optional
+        Whether tiles are processed on the GPU.
+    fn_overhead : int, optional
+        Assumed peak number of tile-sized buffers alive per worker.
+    ram_fraction : float, optional
+        Fraction of available RAM the staging step may use.
+
+    Returns
+    -------
+    int
+        Worker-thread count (always >= 1).
+    """
+    cpu_cap = max(1, (os.cpu_count() or 1) - 1)
+    if use_gpu:
+        return 1
+    avail = _get_available_memory()
+    per_tile = max(1, int(tile_nbytes) * max(1, fn_overhead))
+    mem_cap = max(1, int(avail * ram_fraction) // per_tile)
+    return max(1, min(cpu_cap, mem_cap))
+
+
 def _get_gpu_memory() -> int:
     """Return free GPU VRAM in bytes. Falls back to 8 GiB default."""
     try: