bioimage-py 0.1.0__tar.gz

bioimage_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 computational-cell-analytics
+
+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.

bioimage_py-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: bioimage_py
+Version: 0.1.0
+Summary: Efficient, parallel, and distributed implementation of image analysis and segmentation functionality.
+Author-email: Constantin Pape <constantin.pape@cs.uni-goettingen.de>
+License: MIT License
+        
+        Copyright (c) 2026 computational-cell-analytics
+        
+        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.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-image>=0.20
+Requires-Dist: cloudpickle
+Requires-Dist: tqdm
+Requires-Dist: threadpoolctl
+Requires-Dist: bioimage-cpp
+Provides-Extra: io
+Requires-Dist: zarr>=3; extra == "io"
+Requires-Dist: z5py; extra == "io"
+Provides-Extra: hdf5
+Requires-Dist: h5py; extra == "hdf5"
+Provides-Extra: mrc
+Requires-Dist: mrcfile; extra == "mrc"
+Provides-Extra: nifti
+Requires-Dist: nibabel; extra == "nifti"
+Provides-Extra: imagestack
+Requires-Dist: imageio; extra == "imagestack"
+Requires-Dist: tifffile; extra == "imagestack"
+Provides-Extra: msr
+Requires-Dist: msr-reader; extra == "msr"
+Provides-Extra: cloudvolume
+Requires-Dist: cloud-volume; extra == "cloudvolume"
+Provides-Extra: webknossos
+Requires-Dist: webknossos; extra == "webknossos"
+Provides-Extra: io-all
+Requires-Dist: zarr>=3; extra == "io-all"
+Requires-Dist: z5py; extra == "io-all"
+Requires-Dist: h5py; extra == "io-all"
+Requires-Dist: mrcfile; extra == "io-all"
+Requires-Dist: nibabel; extra == "io-all"
+Requires-Dist: imageio; extra == "io-all"
+Requires-Dist: tifffile; extra == "io-all"
+Requires-Dist: cloud-volume; extra == "io-all"
+Requires-Dist: webknossos; extra == "io-all"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: zarr>=3; extra == "test"
+Requires-Dist: scikit-image; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Requires-Dist: openpyxl; extra == "test"
+Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pyflakes; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: pdoc; extra == "docs"
+Dynamic: license-file
+
+# bioimage-py
+
+Efficient, parallel, and distributed implementation of image analysis and segmentation functionality.
+
+```bash
+python -m pip install -e .
+```
+
+See the [documentation](https://computational-cell-analytics.github.io/bioimage-py/) 
+for [installation](https://computational-cell-analytics.github.io/bioimage-py/bioimage_py.html#installation) 
+and [usage examples](https://computational-cell-analytics.github.io/bioimage-py/bioimage_py.html#usage).

bioimage_py-0.1.0/README.md

@@ -0,0 +1,11 @@
+# bioimage-py
+
+Efficient, parallel, and distributed implementation of image analysis and segmentation functionality.
+
+```bash
+python -m pip install -e .
+```
+
+See the [documentation](https://computational-cell-analytics.github.io/bioimage-py/) 
+for [installation](https://computational-cell-analytics.github.io/bioimage-py/bioimage_py.html#installation) 
+and [usage examples](https://computational-cell-analytics.github.io/bioimage-py/bioimage_py.html#usage).

bioimage_py-0.1.0/bioimage_py/__init__.py

@@ -0,0 +1,29 @@
+"""bioimage_py: efficient, parallel, and distributed image analysis and segmentation.
+
+.. include:: ../docs/installation.md
+.. include:: ../docs/usage.md
+"""
+from . import filters, io, morphology, segmentation, stats  # noqa: F401
+from .copy import copy
+from .downsample import downsample
+from .runner import get_runner
+from .sources import as_source, open_cloudvolume, open_source, open_webknossos
+from .util import to_roi
+from .__version__ import __version__
+
+__all__ = [
+    "__version__",
+    "stats",
+    "filters",
+    "segmentation",
+    "morphology",
+    "io",
+    "copy",
+    "downsample",
+    "get_runner",
+    "as_source",
+    "open_source",
+    "open_cloudvolume",
+    "open_webknossos",
+    "to_roi",
+]

bioimage_py-0.1.0/bioimage_py/__version__.py

@@ -0,0 +1,2 @@
+"""Single source of truth for the package version."""
+__version__ = "0.1.0"

bioimage_py-0.1.0/bioimage_py/_indexing.py

@@ -0,0 +1,115 @@
+"""Index-normalization helpers shared across the library (ported from ``elf.util``).
+
+This is a leaf module: it imports only the standard library and numpy, so it can be used by the
+``sources`` layer, the ``io`` wrappers and elsewhere without risking an import cycle. It turns
+numpy-style basic indices (int / slice / ellipsis / tuple) into a full tuple of in-bounds slices
+plus the axes that should be squeezed afterwards.
+"""
+from __future__ import annotations
+
+import numbers
+from typing import Any, Tuple
+
+import numpy as np
+
+
+def slice_to_start_stop(s: slice, size: int) -> slice:
+    """Normalize a slice so its start/stop are positive, in-bounds coordinates."""
+    if s.step not in (None, 1):
+        raise ValueError("Nontrivial steps are not supported")
+
+    if s.start is None:
+        start = 0
+    elif -size <= s.start < 0:
+        start = size + s.start
+    elif s.start < -size or s.start >= size:
+        return slice(None, 0)
+    else:
+        start = s.start
+
+    if s.stop is None or s.stop > size:
+        stop = size
+    elif s.stop < 0:
+        stop = size + s.stop
+    else:
+        stop = s.stop
+
+    if stop < 1:
+        return slice(None, 0)
+
+    # Clamp so a reversed slice (start > stop) yields an empty region rather than a negative
+    # extent (which crashes the assemble-from-pieces wrappers downstream).
+    return slice(start, max(start, stop))
+
+
+def int_to_start_stop(i: int, size: int) -> slice:
+    """Return the unit slice corresponding to an integer coordinate."""
+    if -size < i < 0:
+        start = i + size
+    elif i >= size or i < -size:
+        raise ValueError("Index ({}) out of range (0-{})".format(i, size - 1))
+    else:
+        start = i
+    return slice(start, start + 1)
+
+
+def normalize_index(index: Any, shape: Tuple[int, ...]) -> Tuple[Tuple[slice, ...], Tuple[int, ...]]:
+    """Normalize an index into a full tuple of in-bounds slices plus the axes to squeeze.
+
+    The index may be an integer, a slice, an ellipsis, or a tuple thereof. It is expanded to one
+    entry per axis with positive start/stop coordinates; integer entries record the axis to squeeze.
+
+    Args:
+        index: The index to normalize.
+        shape: The shape of the array-like object being indexed.
+
+    Returns:
+        A tuple of the normalized slices and the axes that should be squeezed after indexing.
+    """
+    type_msg = (
+        "Advanced selection inappropriate. "
+        "Only numbers, slices (`:`), and ellipsis (`...`) are valid indices (or tuples thereof)"
+    )
+
+    if isinstance(index, tuple):
+        slices_lst = list(index)
+    elif isinstance(index, (numbers.Number, slice, type(Ellipsis))):
+        slices_lst = [index]
+    else:
+        raise TypeError(type_msg)
+
+    ndim = len(shape)
+    if len([item for item in slices_lst if item != Ellipsis]) > ndim:
+        raise TypeError("Argument sequence too long")
+    elif len(slices_lst) < ndim and Ellipsis not in slices_lst:
+        slices_lst.append(Ellipsis)
+
+    normalized = []
+    found_ellipsis = False
+    squeeze = []
+    for item in slices_lst:
+        d = len(normalized)
+        if isinstance(item, slice):
+            normalized.append(slice_to_start_stop(item, shape[d]))
+        elif isinstance(item, numbers.Number):
+            squeeze.append(d)
+            normalized.append(int_to_start_stop(int(item), shape[d]))
+        elif isinstance(item, type(Ellipsis)):
+            if found_ellipsis:
+                raise ValueError("Only one ellipsis may be used")
+            found_ellipsis = True
+            while len(normalized) + (len(slices_lst) - d - 1) < ndim:
+                normalized.append(slice(0, shape[len(normalized)]))
+        else:
+            raise TypeError(type_msg)
+    return tuple(normalized), tuple(squeeze)
+
+
+def squeeze_singletons(item: np.ndarray, to_squeeze: Tuple[int, ...]) -> np.ndarray:
+    """Squeeze the axes recorded by :func:`normalize_index` from a read result."""
+    if len(to_squeeze) == len(item.shape):
+        return item.flatten()[0]
+    elif to_squeeze:
+        return item.squeeze(to_squeeze)
+    else:
+        return item

bioimage_py-0.1.0/bioimage_py/copy.py

@@ -0,0 +1,149 @@
+"""Block-wise copy of one source into another.
+
+Copies an input source into a writable output source block-wise, reusing the runner machinery.
+This is the minimal array-output operation: there is no halo and no per-block computation, just a
+read of each block from the input and a write to the output. Typical uses are converting between
+storage formats (e.g. a tiff stack to zarr) and persisting an on-the-fly transformation (a
+``wrapper`` source) to file so the result is stored rather than recomputed on every read.
+"""
+from __future__ import annotations
+
+from typing import Optional, Sequence, Tuple
+
+import numpy as np
+
+from .runner import get_runner
+from .runner.config import RunnerConfig
+from .sources import Source, SourceLike, as_source
+from .util import BlockDescriptor, ComputeFn, check_rerun_args, to_roi
+
+__all__ = ["copy"]
+
+
+def _full_roi(ndim: int) -> Tuple[slice, ...]:
+    """Return a slicing that selects the whole array."""
+    return tuple(slice(None) for _ in range(ndim))
+
+
+def _same_array(a: Source, b: Source) -> bool:
+    """Return whether two sources wrap the same underlying array object."""
+    return getattr(a, "array", None) is getattr(b, "array", object())
+
+
+def _make_compute() -> ComputeFn:
+    """Build the per-block copy function (no captured state, so trivially cloudpickle-safe)."""
+
+    def _compute(block: BlockDescriptor, inputs: Sequence[Source], outputs: Sequence[Source],
+                 mask: Optional[Source]) -> None:
+        input_, output_ = inputs[0], outputs[0]
+        roi = to_roi(block)
+        if mask is not None:
+            m = mask[roi].astype(bool)
+            if not m.any():
+                return None
+            # Keep out-of-mask voxels of the output unchanged.
+            output_[roi] = np.where(m, input_[roi], output_[roi])
+            return None
+        output_[roi] = input_[roi]
+        return None
+
+    return _compute
+
+
+def _copy_source(
+    input: SourceLike,
+    output: Optional[SourceLike],
+    *,
+    block_shape: Optional[Tuple[int, ...]],
+    job_type: str,
+    job_config: Optional[RunnerConfig],
+    num_workers: int,
+    mask: Optional[SourceLike],
+    name: str,
+    block_ids: Optional[Sequence[int]] = None,
+    resume_from: Optional[str] = None,
+) -> SourceLike:
+    """Materialize ``input`` into ``output`` block-wise (shared by :func:`copy` and downsample).
+
+    Handles output allocation (a numpy array for local execution, a required file-backed array for
+    distributed execution), the direct (whole-array) fast path, and the runner dispatch. The output
+    shape and dtype are taken from ``input`` (so a shape-changing wrapper input is handled too).
+    """
+    check_rerun_args(job_type, resume_from, block_ids)
+    src = as_source(input)
+    ndim = src.ndim
+    # A subset/resume rerun is block-wise, so it cannot use the direct (whole-array) path.
+    direct = (job_type == "local" and num_workers == 1 and block_shape is None and mask is None
+              and block_ids is None and resume_from is None)
+
+    if output is None:
+        if job_type != "local":
+            raise ValueError(
+                f"'output' is required for distributed execution (job_type={job_type!r}); "
+                "pass a file-backed (zarr/n5) output array."
+            )
+        out_array: SourceLike = np.zeros(tuple(src.shape), dtype=src.dtype)
+    else:
+        out_array = output
+
+    out = as_source(out_array)
+    if not direct and _same_array(out, src):
+        raise ValueError(f"Block-wise {name} needs 'output' to differ from 'input'.")
+
+    if direct:
+        out[_full_roi(out.ndim)] = src[_full_roi(ndim)]
+        return out_array
+
+    compute = _make_compute()
+    runner = get_runner(job_type, job_config)
+    runner.run(compute, [src], outputs=[out], block_shape=block_shape,
+               mask=mask, num_workers=num_workers, block_ids=block_ids, resume_from=resume_from,
+               name=name)
+    return out_array
+
+
+def copy(
+    input: SourceLike,
+    output: Optional[SourceLike] = None,
+    *,
+    block_shape: Optional[Tuple[int, ...]] = None,
+    job_type: str = "local",
+    job_config: Optional[RunnerConfig] = None,
+    num_workers: int = 1,
+    mask: Optional[SourceLike] = None,
+    block_ids: Optional[Sequence[int]] = None,
+    resume_from: Optional[str] = None,
+) -> SourceLike:
+    """Copy a source into an output, block-wise.
+
+    The data is read from ``input`` and written into ``output`` one block at a time. The input may
+    be any source, including a read-only ``FileSource`` (e.g. a tiff stack) or a ``wrapper`` source
+    whose transformation is computed on read; copying it materializes the transformed data to the
+    output. The data is written into the output as-is, so the output array's dtype governs and a
+    cast is applied on assignment when it differs from the input dtype.
+
+    Args:
+        input: The input data to copy (a numpy/zarr/n5 array or a `Source`).
+        output: The output array to write into. Optional for local execution — a numpy array
+            matching the input shape and dtype is allocated and returned if omitted; **required**
+            for distributed execution, where it must be a writable, file-backed (zarr/n5) array.
+        block_shape: Shape of the processing blocks. Defaults to the input chunk shape; required
+            for unchunked data.
+        job_type: Execution backend: one of ``"local"``, ``"subprocess"`` or ``"slurm"``.
+        job_config: Backend configuration (a `RunnerConfig` / `SlurmConfig`).
+        num_workers: Number of parallel workers (threads for ``local``, tasks for distributed
+            backends).
+        mask: Optional binary mask; only voxels within the mask are copied (out-of-mask output
+            voxels are left unchanged).
+        block_ids: Restrict processing to these block ids (e.g. to re-run previously failed blocks
+            into the existing ``output``). Mutually exclusive with ``resume_from``.
+        resume_from: Distributed only; the preserved temp folder of a failed run to resume (see
+            ``runner.run``); the missing blocks are written into ``output``. Mutually exclusive
+            with ``block_ids``.
+
+    Returns:
+        The output array (the provided ``output``, or a newly allocated numpy array).
+    """
+    return _copy_source(input, output, block_shape=block_shape, job_type=job_type,
+                        job_config=job_config, num_workers=num_workers, mask=mask, name="copy",
+                        block_ids=block_ids, resume_from=resume_from)

bioimage_py-0.1.0/bioimage_py/downsample.py

@@ -0,0 +1,96 @@
+"""Block-wise downsampling of a source.
+
+Downsampling wraps the input in a :class:`~bioimage_py.wrapper.ResizedSource` at the downscaled
+target shape and copies it block-wise into the output, reusing the copy machinery. Because the
+wrapper resamples on read, this is exactly a block-wise copy of the resized source.
+"""
+from __future__ import annotations
+
+from numbers import Integral
+from typing import Optional, Sequence, Tuple, Union
+
+from .copy import _copy_source
+from .runner.config import RunnerConfig
+from .sources import SourceLike, as_source
+from .util import downscale_shape
+from .wrapper import ResizedSource
+
+__all__ = ["downsample"]
+
+# A downscaling factor: a single int (isotropic) or a per-axis sequence of ints.
+ScaleFactor = Union[int, Sequence[int]]
+
+
+def downsample(
+    input: SourceLike,
+    scale_factor: ScaleFactor,
+    output: Optional[SourceLike] = None,
+    *,
+    order: int = 0,
+    anti_aliasing: bool = False,
+    block_shape: Optional[Tuple[int, ...]] = None,
+    job_type: str = "local",
+    job_config: Optional[RunnerConfig] = None,
+    num_workers: int = 1,
+    mask: Optional[SourceLike] = None,
+    block_ids: Optional[Sequence[int]] = None,
+    resume_from: Optional[str] = None,
+) -> SourceLike:
+    """Downsample a source by an integer factor, block-wise.
+
+    The input is wrapped in a :class:`~bioimage_py.wrapper.ResizedSource` at the downscaled shape
+    (computed with :func:`~bioimage_py.util.downscale_shape`, ceil mode) and copied into the output.
+
+    The defaults (``order=0`` nearest, ``anti_aliasing=False``) are label-safe — they preserve the
+    input values and are appropriate for segmentations. For intensity / image data pass ``order=1``
+    (or higher) and ``anti_aliasing=True`` for a smooth, alias-free downsample.
+
+    Args:
+        input: The input data to downsample (a numpy/zarr/n5 array or a `Source`). 2D or 3D.
+        scale_factor: The downscaling factor: a single int (isotropic) or a per-axis sequence of
+            ints. Each factor must be ``>= 1`` (1 leaves that axis unchanged).
+        output: The output array to write into. Optional for local execution — a numpy array of the
+            downscaled shape and the input dtype is allocated and returned if omitted; **required**
+            for distributed execution, where it (and the input) must be file-backed (zarr/n5).
+        order: The interpolation order (0 to 5). Use ``0`` (nearest) for label data.
+        anti_aliasing: Whether to Gaussian pre-smooth before sampling to avoid aliasing.
+            Recommended for image data; leave ``False`` for labels.
+        block_shape: Shape of the processing blocks (in the downscaled output space). Defaults to
+            the resized source's chunk shape; required for unchunked data.
+        job_type: Execution backend: one of ``"local"``, ``"subprocess"`` or ``"slurm"``.
+        job_config: Backend configuration (a `RunnerConfig` / `SlurmConfig`).
+        num_workers: Number of parallel workers (threads for ``local``, tasks for distributed
+            backends).
+        mask: Optional binary mask in the downscaled output space; only voxels within the mask are
+            written (out-of-mask output voxels are left unchanged).
+        block_ids: Restrict processing to these block ids (in the downscaled output space), e.g. to
+            re-run previously failed blocks into the existing ``output``. Mutually exclusive with
+            ``resume_from``.
+        resume_from: Distributed only; the preserved temp folder of a failed run to resume (see
+            ``runner.run``); the missing blocks are written into ``output``. Mutually exclusive
+            with ``block_ids``.
+
+    Returns:
+        The output array (the provided ``output``, or a newly allocated numpy array).
+    """
+    src = as_source(input)
+    ndim = src.ndim
+    if isinstance(scale_factor, Integral):
+        factors: Tuple[int, ...] = (int(scale_factor),) * ndim
+    else:
+        factors = tuple(int(f) for f in scale_factor)
+        if len(factors) != ndim:
+            raise ValueError(
+                f"scale_factor {scale_factor} does not match the input dimensionality {ndim}."
+            )
+    if any(f < 1 for f in factors):
+        raise ValueError(
+            f"downsample requires scale factors >= 1, got {factors}; "
+            "use a ResizedSource directly to upsample."
+        )
+
+    target_shape = downscale_shape(src.shape, factors)
+    wrapped = ResizedSource(src, target_shape, order=order, anti_aliasing=anti_aliasing)
+    return _copy_source(wrapped, output, block_shape=block_shape, job_type=job_type,
+                        job_config=job_config, num_workers=num_workers, mask=mask, name="downsample",
+                        block_ids=block_ids, resume_from=resume_from)

bioimage_py-0.1.0/bioimage_py/filters/__init__.py

@@ -0,0 +1,14 @@
+"""Block-wise image filters."""
+from .filters import (
+    apply_filter,
+    gaussian_gradient_magnitude,
+    gaussian_smoothing,
+    laplacian_of_gaussian,
+)
+
+__all__ = [
+    "apply_filter",
+    "gaussian_smoothing",
+    "gaussian_gradient_magnitude",
+    "laplacian_of_gaussian",
+]