Metadata-Version: 2.4
Name: modifiedOtsu
Version: 0.1.1
Summary: Numba-accelerated local modified Otsu thresholding following Park et al.'s 2D+time formulation, with an optional 3D extension.
Author-email: John Rick Manzanares <jdolormanzanares@impan.pl>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jhnrckmnznrs/modifiedOtsu
Project-URL: Issues, https://github.com/jhnrckmnznrs/modifiedOtsu/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numba
Provides-Extra: tiff
Requires-Dist: tifffile; extra == "tiff"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: tifffile; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# modifiedOtsu

`modifiedOtsu` implements the local modified Otsu thresholding step used by
Park et al. in *Segmentation-based tracking of macrophages in 2D+time microscopy
movies inside a living animal*.

The package default is `window_size=(3, 3, 3)` for volumetric use. For a 2D+time movie with shape `(t, y, x)`, use `window_size=(1, s, s)` explicitly for the exact 2D local window used by Park et al. A larger first window dimension, such as `(3, 7, 7)`, is a 3D/temporal extension, not the exact 2D local window from the paper.

The binary decision is:

```python
binary = image > threshold_map
```

The contrast rejection rule is the relative class-mean rule:

```text
abs(mu_foreground - mu_background) / abs(mu_background) > delta
```

If `mu_background == 0` and the two means differ, the relative separation is
considered infinite rather than rejecting the window.

## Install

```bash
python -m pip install .
```

For TIFF I/O:

```bash
python -m pip install '.[tiff]'
```

## Python API

```python
import tifffile
from modifiedOtsu import getMask

movie = tifffile.imread("movie.tif")  # shape: (t, y, x)
thresholds, mask = getMask(movie, window_size=(1, 7, 7), delta=0.2)
```

Default volumetric call:

```python
thresholds, mask = getMask(volume, delta=0.2)  # default window_size=(3, 3, 3)
```


Use `delta=0` for ordinary local Otsu without the extra relative-contrast
rejection.

For a 3D volume extension:

```python
thresholds, mask = getMask(volume, window_size=(3, 7, 7), delta=0.2)
```

## CLI

One TIFF/NumPy volume:

```bash
modified-otsu --input image.tif --window 3 3 3 --delta 0.2
```

Directory, recursively preserving subdirectories:

```bash
modified-otsu \
  --input dataset \
  --output-dir results \
  --recursive \
  --window 3 3 3 \
  --delta 0.2
```

With threshold maps:

```bash
modified-otsu --input image.tif --window 3 3 3 --save-thresholds
```

Masks are saved as TIFF files with values `0` and `255`.
