modifiedOtsu 0.1.0__py3-none-any.whl

modifiedOtsu/__init__.py

@@ -0,0 +1,39 @@
+"""
+Local 2D Otsu Thresholding for 3D Images
+==========================================
+
+A high-performance implementation of local 2D Otsu thresholding for 3D grayscale images
+using Numba acceleration.
+
+Main Functions
+--------------
+getBinary : Apply local Otsu thresholding to get binary mask or thresholds
+getThreshold : Compute Otsu threshold for 1D intensity values
+
+Example
+-------
+>>> import numpy as np
+>>> from modifiedOtsu import getMask
+>>> 
+>>> # Create sample 3D image
+>>> img = np.random.randint(0, 256, size=(50, 50, 50), dtype=np.uint8)
+>>> 
+>>> # Get threshold mask and binary image
+>>> threshold, binary = getMask(img, window_size=(3, 3, 3), delta=0.2)
+"""
+
+from .core import getMask, getThreshold
+
+# Package metadata
+__version__ = "0.1.0"
+__author__ = "John Rick Manzanares"
+__email__ = "jdolormanzanares@impan.pl"
+
+# Define what gets imported with "from modifiedOtsu import *"
+__all__ = [
+    "getBinary",
+    "getThreshold",
+]
+
+# Optional: Add convenience functions or constants
+DEFAULT_WINDOW_SIZE = (3, 3, 3)

modifiedOtsu/core.py

@@ -0,0 +1,291 @@
+"""
+Core implementation of modified Otsu thresholding.
+"""
+
+import numpy as np
+from numba import njit, prange
+from typing import Tuple
+
+
+# ============================================================================
+# Helper Functions (Internal)
+# ============================================================================
+
+
+@njit
+def _padReflect(img: np.ndarray, pad_width: Tuple[int, int, int]) -> np.ndarray:
+    """
+    Manual reflect padding for 3D arrays (Numba-compatible).
+
+    Parameters
+    ----------
+    img : np.ndarray
+        3D input array
+    pad_width : tuple of int
+        Padding size for each dimension (z_pad, y_pad, x_pad)
+
+    Returns
+    -------
+    np.ndarray
+        Padded array with reflect mode
+    """
+    z_pad, y_pad, x_pad = pad_width
+    z_max, y_max, x_max = img.shape
+
+    padded = np.zeros(
+        (z_max + 2 * z_pad, y_max + 2 * y_pad, x_max + 2 * x_pad), dtype=img.dtype
+    )
+
+    # Copy center
+    padded[z_pad : z_pad + z_max, y_pad : y_pad + y_max, x_pad : x_pad + x_max] = img
+
+    # Reflect padding for Z
+    for i in range(z_pad):
+        padded[z_pad - 1 - i, y_pad : y_pad + y_max, x_pad : x_pad + x_max] = img[
+            i, :, :
+        ]
+        padded[z_pad + z_max + i, y_pad : y_pad + y_max, x_pad : x_pad + x_max] = img[
+            z_max - 1 - i, :, :
+        ]
+
+    # Reflect padding for Y
+    for j in range(y_pad):
+        padded[:, y_pad - 1 - j, x_pad : x_pad + x_max] = padded[
+            :, y_pad + j, x_pad : x_pad + x_max
+        ]
+        padded[:, y_pad + y_max + j, x_pad : x_pad + x_max] = padded[
+            :, y_pad + y_max - 1 - j, x_pad : x_pad + x_max
+        ]
+
+    # Reflect padding for X
+    for k in range(x_pad):
+        padded[:, :, x_pad - 1 - k] = padded[:, :, x_pad + k]
+        padded[:, :, x_pad + x_max + k] = padded[:, :, x_pad + x_max - 1 - k]
+
+    return padded
+
+
+@njit(parallel=True)
+def _getMask(
+    img: np.ndarray, window_size: Tuple[int, int, int], delta: float
+) -> np.ndarray:
+    """
+    Internal Numba-compiled implementation.
+    No validation - assumes inputs are correct.
+    """
+    z_win, y_win, x_win = window_size
+    z_pad, y_pad, x_pad = z_win // 2, y_win // 2, x_win // 2
+
+    padded = _padReflect(img, (z_pad, y_pad, x_pad))
+    mask = np.zeros_like(img, dtype=np.int32)
+    z_max, y_max, x_max = img.shape
+
+    for z in prange(z_max):
+        for y in range(y_max):
+            for x in range(x_max):
+                window = padded[z : z + z_win, y : y + y_win, x : x + x_win].ravel()
+                mask[z, y, x] = getThreshold(window, delta)
+    
+    return mask, (img > mask)
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+
+@njit
+def getThreshold(values: np.ndarray, delta: float = 0.2) -> int:
+    """
+    Compute Otsu threshold for a 1D array of intensity values.
+
+    This implementation assumes integer input values. The algorithm bins values
+    by their integer representation and computes the optimal threshold that
+    maximizes between-class variance.
+
+    Parameters
+    ----------
+    values : np.ndarray
+        1D array of integer intensity values
+    delta : float, default=0.2
+        Contrast threshold. If the relative difference between foreground
+        and background means is below this threshold, the maximum value + 1
+        is returned (indicating insufficient contrast).
+
+    Returns
+    -------
+    int
+        The optimal threshold value, or max(values) + 1 if contrast is too low
+
+    Notes
+    -----
+    The algorithm:
+    1. Creates a histogram of input values
+    2. Iterates through possible thresholds
+    3. Computes between-class variance for each threshold
+    4. Returns the threshold with maximum variance
+    5. If contrast is too low (|mB - mF| / mB <= delta), returns max + 1
+
+    Examples
+    --------
+    >>> values = np.array([10, 10, 10, 20, 20, 30, 30, 30], dtype=np.int32)
+    >>> threshold = getThreshold(values, delta=0.2)
+    """
+    mn = values.min()
+    mx = values.max()
+
+    if mx == mn:
+        return int(mx)
+
+    binned_values = (values - mn).astype(np.int32)
+    hist = np.bincount(binned_values, minlength=mx - mn + 1)
+    bin_edges = np.arange(len(hist)) + mn
+
+    total = values.size
+    sum_total = np.sum(bin_edges * hist)
+    sumB = 0.0
+    wB = 0
+    maximum = 0.0
+    threshold = 0
+    best_mB, best_mF = 0.0, 0.0
+
+    for i in range(len(hist)):
+        wB += hist[i]
+        if wB == 0:
+            continue
+        wF = total - wB
+        if wF == 0:
+            break
+
+        sumB += bin_edges[i] * hist[i]
+        mB = sumB / wB
+        mF = (sum_total - sumB) / wF
+        between = wB * wF * (mB - mF) ** 2
+
+        if between > maximum:
+            maximum = between
+            threshold = bin_edges[i]
+            best_mB = mB
+            best_mF = mF
+
+    # Force threshold to max if contrast is too low
+    if best_mB == 0 or abs(best_mB - best_mF) / best_mB <= delta:
+        threshold = mx + 1
+
+    return int(threshold)
+
+
+def getMask(
+    img: np.ndarray,
+    window_size: Tuple[int, int, int] = (3, 3, 3),
+    delta: float = 0.2
+) -> np.ndarray:
+    """
+    Apply local Otsu thresholding to a 3D grayscale image.
+
+    For each pixel, computes an optimal threshold based on the intensity
+    distribution in a local neighborhood window, then either returns the
+    threshold values or a binary mask.
+
+    Parameters
+    ----------
+    img : np.ndarray
+        3D input image with integer dtype (e.g., uint8, uint16, int32).
+        Shape should be (z, y, x).
+    window_size : tuple of int
+        Local neighborhood size as (z_size, y_size, x_size).
+        Should be positive odd integers for centered windows.
+    delta : float, default=0.2
+        Contrast parameter for Otsu thresholding. Lower values are more
+        permissive, higher values require stronger contrast.
+
+    Returns
+    -------
+    np.ndarray
+        If binarize=True: Binary mask with same shape as input (dtype=uint8)
+        If binarize=False: Threshold map with same shape as input (dtype=int32)
+
+    Raises
+    ------
+    ValueError
+        If input validation fails (wrong dimensions, dtype, window_size, etc.)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from modifiedOtsu import getMask
+    >>>
+    >>> # Create sample 3D grayscale image
+    >>> img = np.random.randint(0, 256, size=(50, 50, 50), dtype=np.uint8)
+    >>>
+    >>> # Get binary mask
+    >>> mask = getMask(img, window_size=(5, 5, 5), delta=0.2, binarize=True)
+    >>> print(mask.shape, mask.dtype)
+    (50, 50, 50) uint8
+    >>>
+    >>> # Get threshold values
+    >>> thresholds = getMask(img, window_size=(5, 5, 5), delta=0.2, binarize=False)
+    >>> print(thresholds.shape, thresholds.dtype)
+    (50, 50, 50) int32
+
+    Notes
+    -----
+    - Uses reflect padding at image boundaries
+    - Parallelized using Numba for high performance
+    - Input must be integer dtype (float images should be converted first)
+    """
+    # Validation
+    if img.ndim != 3:
+        raise ValueError(
+            f"Expected 3D image, got {img.ndim}D array with shape {img.shape}"
+        )
+
+    if not np.issubdtype(img.dtype, np.integer):
+        raise ValueError(
+            f"Expected integer dtype (e.g., uint8, uint16, int32), got {img.dtype}. "
+            f"Convert using img.astype(np.uint8) or similar."
+        )
+
+    if not isinstance(window_size, (tuple, list)):
+        raise ValueError(
+            f"window_size must be a tuple or list, got {type(window_size)}"
+        )
+
+    if len(window_size) != 3:
+        raise ValueError(
+            f"window_size must have 3 elements (z, y, x), got {len(window_size)}"
+        )
+
+    if not all(isinstance(w, (int, np.integer)) for w in window_size):
+        raise ValueError(f"window_size elements must be integers, got {window_size}")
+
+    if any(w <= 0 for w in window_size):
+        raise ValueError(f"window_size elements must be positive, got {window_size}")
+
+    if any(w % 2 == 0 for w in window_size):
+        z_win, y_win, x_win = window_size
+        raise ValueError(
+            f"window_size elements should be odd numbers for centered windows, "
+            f"got {window_size}. Consider using "
+            f"({z_win+1 if z_win%2==0 else z_win}, "
+            f"{y_win+1 if y_win%2==0 else y_win}, "
+            f"{x_win+1 if x_win%2==0 else x_win}) instead."
+        )
+
+    z_max, y_max, x_max = img.shape
+    z_win, y_win, x_win = window_size
+    if z_win > z_max or y_win > y_max or x_win > x_max:
+        raise ValueError(
+            f"window_size {window_size} is larger than image dimensions {img.shape}"
+        )
+
+    if not isinstance(delta, (int, float)):
+        raise ValueError(f"delta must be a number, got {type(delta)}")
+
+    if delta < 0:
+        raise ValueError(f"delta must be non-negative, got {delta}")
+
+    if img.size == 0:
+        raise ValueError("Input image is empty")
+
+    # Call Numba implementation
+    return _getMask(img, window_size, delta)

modifiedOtsu/runner.py

@@ -0,0 +1,179 @@
+# ============================================================================
+# Command Line Runner for Modified Otsu Thresholding
+# ============================================================================
+
+import argparse
+import numpy as np
+import os
+import matplotlib.pyplot as plt
+from modifiedOtsu import getMask
+
+
+def load_image(image_path: str) -> np.ndarray:
+    """
+    Load a 3D image from a file (.npy or .tif/.tiff).
+    """
+    if not os.path.exists(image_path):
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+
+    ext = os.path.splitext(image_path)[1].lower()
+
+    if ext == ".npy":
+        img = np.load(image_path)
+    elif ext in [".tif", ".tiff"]:
+        try:
+            import tifffile
+        except ImportError:
+            raise ImportError(
+                "tifffile is required to read TIFF images. "
+                "Install it via 'pip install tifffile'."
+            )
+        img = tifffile.imread(image_path)
+    else:
+        raise ValueError(
+            f"Unsupported file format: {ext}. Use .npy or .tif/.tiff files."
+        )
+
+    if img.ndim != 3:
+        raise ValueError(f"Expected a 3D image, got shape {img.shape}")
+
+    if not np.issubdtype(img.dtype, np.integer):
+        img = img.astype(np.uint8)
+
+    return img
+
+
+def save_output(threshold: np.ndarray, binary: np.ndarray, image_path: str, outdir: str, fmt: str):
+    """
+    Save threshold and binary arrays to the specified directory and format.
+    Filenames follow: {input_filename}_{threshold/binary}.{format}
+    """
+    os.makedirs(outdir, exist_ok=True)
+
+    # Extract base name (without extension)
+    base_name = os.path.splitext(os.path.basename(image_path))[0]
+
+    th_path = os.path.join(outdir, f"{base_name}_threshold.{fmt}")
+    bin_path = os.path.join(outdir, f"{base_name}_binary.{fmt}")
+
+    if fmt == "npy":
+        np.save(th_path, threshold)
+        np.save(bin_path, binary)
+        print(f"Saved NPY files:\n  {th_path}\n  {bin_path}")
+
+    elif fmt in ["tif", "tiff"]:
+        try:
+            import tifffile
+        except ImportError:
+            print("tifffile not installed — cannot save as TIFF. Saving as NPY instead.")
+            np.save(th_path.replace(".tiff", ".npy"), threshold)
+            np.save(bin_path.replace(".tiff", ".npy"), binary)
+            return
+        tifffile.imwrite(th_path, threshold.astype(np.uint16))
+        tifffile.imwrite(bin_path, binary.astype(np.uint8))
+        print(f"Saved TIFF files:\n  {th_path}\n  {bin_path}")
+
+    else:
+        raise ValueError(f"Unsupported format: {fmt}. Choose 'npy' or 'tiff'.")
+
+
+def show_results(img: np.ndarray, threshold: np.ndarray, binary: np.ndarray, z_index: int = None):
+    """
+    Show a chosen or middle slice for threshold and binary output.
+    """
+    if z_index is None:
+        z_index = img.shape[0] // 2
+
+    if z_index < 0 or z_index >= img.shape[0]:
+        raise ValueError(f"Invalid z-index {z_index}. Must be in range [0, {img.shape[0]-1}]")
+
+    fig, axes = plt.subplots(1, 3, figsize=(12, 4))
+    axes[0].imshow(img[z_index], cmap="gray")
+    axes[0].set_title(f"Original (z={z_index})")
+    axes[1].imshow(threshold[z_index], cmap="gray")
+    axes[1].set_title("Local Thresholds")
+    axes[2].imshow(binary[z_index], cmap="gray")
+    axes[2].set_title("Binary Mask")
+    for ax in axes:
+        ax.axis("off")
+
+    plt.tight_layout()
+    plt.show()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run Modified Otsu Thresholding on a 3D image."
+    )
+    parser.add_argument(
+        "--image",
+        type=str,
+        required=True,
+        help="Path to a 3D image file (.npy or .tif/.tiff)",
+    )
+    parser.add_argument(
+        "--window",
+        type=int,
+        nargs=3,
+        default=[3, 3, 3],
+        help="Local window size (z y x). Default: 3 3 3",
+    )
+    parser.add_argument(
+        "--delta",
+        type=float,
+        default=0.2,
+        help="Contrast delta parameter (default: 0.2)",
+    )
+    parser.add_argument(
+        "--outdir",
+        type=str,
+        default="outputs",
+        help="Directory to save outputs (default: ./outputs)",
+    )
+    parser.add_argument(
+        "--format",
+        type=str,
+        default="npy",
+        choices=["npy", "tif", "tiff"],
+        help="Output file format (default: npy)",
+    )
+    parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Display threshold and binary slices using matplotlib",
+    )
+    parser.add_argument(
+        "--slice",
+        type=int,
+        default=None,
+        help="Optional z-index to visualize (default: middle slice)",
+    )
+
+    args = parser.parse_args()
+
+    # Load image
+    print(f"Loading image: {args.image}")
+    img = load_image(args.image)
+    print(f"Image loaded with shape {img.shape} and dtype {img.dtype}")
+
+    # Run Modified Otsu Thresholding
+    print("Running modified Otsu thresholding...")
+    threshold, binary = getMask(img, window_size=tuple(args.window), delta=args.delta)
+
+    # Print results
+    print("------------------------------------------------------------")
+    print(f"Threshold map shape: {threshold.shape}")
+    print(f"Binary mask shape: {binary.shape}")
+
+    # Save outputs
+    save_output(threshold, binary, args.image, args.outdir, args.format)
+
+    # Show outputs if requested
+    if args.show:
+        show_results(img, threshold, binary, args.slice)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

modifiedotsu-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: modifiedOtsu
+Version: 0.1.0
+Summary: Numba-accelerated local modified Otsu thresholding for 3D images.
+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"
+Requires-Dist: matplotlib; extra == "tiff"
+Dynamic: license-file
+
+# 🧠 Local Modified Otsu Thresholding
+
+**Local Modified Otsu Thresholding** is a **Numba-accelerated** implementation of a *local, contrast-adaptive* Otsu thresholding method for 3D images.
+
+This algorithm adapts the Otsu threshold within a sliding 3D window, enabling robust segmentation in datasets with spatially varying intensity distributions.
+
+The method is inspired by the segmentation approach described in **Subsection 2.2.2** of the article:
+
+> *Segmentation-based tracking of macrophages in 2D + time microscopy movies inside a living animal*
+> 
+> *Computers in Biology and Medicine, 153 (2023), 106499*
+> 
+> [https://doi.org/10.1016/j.compbiomed.2022.106499](https://doi.org/10.1016/j.compbiomed.2022.106499)
+
+If you use this implementation in your research, please cite the original work that inspired this algorithm.
+
+---
+
+## ⚙️ Installation
+
+Install the latest stable version from PyPI:
+
+```bash
+pip install modifiedOtsu
+```
+
+## 🚀 Example Usage
+
+```python
+import numpy as np
+from modifiedOtsu import getMask
+
+# Create sample 3D image
+img = np.random.randint(0, 256, size=(10, 10, 10), dtype=np.uint8)
+
+# Get threshold map and binary image
+threshold, binary = getMask(img, window_size=(3, 3, 3), delta=0.2)
+```
+
+## 🖥️ Command Line Usage
+
+You can execute the script with custom parameters:
+
+```bash
+python runner.py --shape 10 10 10 --window 3 3 3 --delta 0.2
+```
+
+## 📦 Dependencies
+
+- NumPy
+- Numba
+- Matplotlib
+
+Install dependencies with:
+
+```bash
+pip install numpy numba matplotlib
+```
+
+## 📜 License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! If you'd like to fix a bug, add a feature, or improve performance, please open a pull request or contact the maintainers.
+
+## 💬 Contact
+
+For questions, issues, or feedback, open an issue on GitHub.

modifiedotsu-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+modifiedOtsu/__init__.py,sha256=4RwEI6MGz0hNpPRQ3Fh9xGgQqmtfGPT3pf-ErYzEXe4,1032
+modifiedOtsu/core.py,sha256=2iJNrTAwpxJCPQfS3WR4cOLih3Q4Z7l_R1mzawchDBE,9029
+modifiedOtsu/runner.py,sha256=BFXSiqm7L7l0GZAuDygZ_R8PY_odAoZypLuaVanqEe8,5475
+modifiedotsu-0.1.0.dist-info/licenses/LICENSE,sha256=nf6nNGBSlKqD389gsU-_DPce5IOf-lk_MceXNyoDpMg,1078
+modifiedotsu-0.1.0.dist-info/METADATA,sha256=xbPoLCMlJP42CGF1qkwCZe-8RfH8xCVTKfJOBQ5WiBM,2484
+modifiedotsu-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+modifiedotsu-0.1.0.dist-info/entry_points.txt,sha256=8PFdo6g2IrSC_Nid05rnpq7IWxkMBtlfyTQEdWJQbnk,59
+modifiedotsu-0.1.0.dist-info/top_level.txt,sha256=kF51f_OBYTVQtFubEaNsrNW9R7HNUWKP_UYTAag-spM,13
+modifiedotsu-0.1.0.dist-info/RECORD,,

modifiedotsu-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modifiedotsu-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modified-otsu = modifiedOtsu.runner:main

modifiedotsu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 John Rick Manzanares
+
+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.
+

modifiedotsu-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modifiedOtsu