otsu2D 0.1.0__tar.gz

otsu2d-0.1.0/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.
+

otsu2d-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: otsu2D
+Version: 0.1.0
+Summary: Numba-accelerated local 2D Otsu thresholding for 3D images.
+Author-email: John Rick Manzanares <jdolormanzanares@impan.pl>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jhnrckmnznrs/otsu2D
+Project-URL: Issues, https://github.com/jhnrckmnznrs/otsu2D/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 2D Otsu Thresholding
+
+**Local 2D Otsu Thresholding** is a **Numba-accelerated** implementation of a *local* 2D Otsu thresholding method for 3D images.
+
+This algorithm adapts the 2D Otsu threshold within a sliding 3D window, enabling robust segmentation in datasets with spatially varying intensity distributions.
+
+---
+
+## ⚙️ Installation
+
+Install the latest stable version from PyPI:
+
+```bash
+pip install otsu2D
+```
+
+## 🚀 Example Usage
+
+```python
+import numpy as np
+from otsu2D import getBinary
+
+# Create sample 3D image
+img = np.random.randint(0, 256, size=(10, 10, 10), dtype=np.uint8)
+
+# Get threshold map and binary image
+binary = getBinary(img, window_size=(3, 3, 3),  mean_window_size =(3,3,3))
+```
+
+## 🖥️ Command Line Usage
+
+You can execute the script with custom parameters:
+
+```bash
+python runner.py --shape 10 10 10 --window 3 3 3 --mean_window 3 3 3
+```
+
+## 📦 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.

otsu2d-0.1.0/README.md

@@ -0,0 +1,60 @@
+# 🧠 Local 2D Otsu Thresholding
+
+**Local 2D Otsu Thresholding** is a **Numba-accelerated** implementation of a *local* 2D Otsu thresholding method for 3D images.
+
+This algorithm adapts the 2D Otsu threshold within a sliding 3D window, enabling robust segmentation in datasets with spatially varying intensity distributions.
+
+---
+
+## ⚙️ Installation
+
+Install the latest stable version from PyPI:
+
+```bash
+pip install otsu2D
+```
+
+## 🚀 Example Usage
+
+```python
+import numpy as np
+from otsu2D import getBinary
+
+# Create sample 3D image
+img = np.random.randint(0, 256, size=(10, 10, 10), dtype=np.uint8)
+
+# Get threshold map and binary image
+binary = getBinary(img, window_size=(3, 3, 3),  mean_window_size =(3,3,3))
+```
+
+## 🖥️ Command Line Usage
+
+You can execute the script with custom parameters:
+
+```bash
+python runner.py --shape 10 10 10 --window 3 3 3 --mean_window 3 3 3
+```
+
+## 📦 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.

otsu2d-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools >= 77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "otsu2D"
+version = "0.1.0"
+description = "Numba-accelerated local 2D Otsu thresholding for 3D images."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [
+  {name="John Rick Manzanares", email="jdolormanzanares@impan.pl"}
+]
+dependencies = [
+  "numpy",
+  "numba"
+]
+requires-python = ">=3.9"
+
+[project.optional-dependencies]
+tiff = ["tifffile", "matplotlib"]
+
+[project.scripts]
+otsu-2d = "otsu2D.runner:main"
+
+[project.urls]
+Homepage = "https://github.com/jhnrckmnznrs/otsu2D"
+Issues = "https://github.com/jhnrckmnznrs/otsu2D/issues"

otsu2d-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

otsu2d-0.1.0/src/otsu2D/__init__.py

@@ -0,0 +1,40 @@
+"""
+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 2D Otsu thresholding to get binary mask
+getThreshold : Compute 2D Otsu threshold for 1D intensity values and 1D local mean values
+
+Example
+-------
+>>> import numpy as np
+>>> from modifiedOtsu import getBinary
+>>> 
+>>> # Create sample 3D image
+>>> img = np.random.randint(0, 256, size=(50, 50, 50), dtype=np.uint8)
+>>> 
+>>> # Get binary image
+>>> binary = getBinary(img, window_size=(3, 3, 3))
+"""
+
+from .core import getBinary, getThreshold
+
+# Package metadata
+__version__ = "0.1.0"
+__author__ = "John Rick Manzanares"
+__email__ = "jdolormanzanares@impan.pl"
+
+# Define what gets imported with "from Otsu2D import *"
+__all__ = [
+    "getBinary",
+    "getThreshold",
+]
+
+# Optional: Add convenience functions or constants
+DEFAULT_WINDOW_SIZE = (3, 3, 3)
+DEFAULT_MEAN_WINDOW_SIZE = (3, 3, 3)

otsu2d-0.1.0/src/otsu2D/core.py

@@ -0,0 +1,429 @@
+"""
+Core implementation of local 2D 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
+def _getBinary(
+    img: np.ndarray,
+    window_size: Tuple[int, int, int],
+    mean_window_size: Tuple[int, int, int],
+) -> np.ndarray:
+    """
+    Internal Numba-compiled implementation.
+    No validation - assumes inputs are correct.
+    """
+
+    localMean = getLocalMean(img, mean_window_size)
+
+
+    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))
+    paddedLocalMean = _padReflect(localMean, (z_pad, y_pad, x_pad))
+    binary = 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):
+                windowIntensity = padded[
+                    z : z + z_win, y : y + y_win, x : x + x_win
+                ].ravel()
+                windowMean = paddedLocalMean[
+                    z : z + z_win, y : y + y_win, x : x + x_win
+                ].ravel()
+                s_real, t_real = getThreshold(windowIntensity, windowMean)
+
+                # Element-wise comparison at each voxel
+                condition1 = img[z, y, x] > s_real
+                condition2 = localMean[z, y, x] > t_real
+
+                binary[z, y, x] = condition1 & condition2
+
+    return binary.astype(np.uint8) * 255
+
+
+@njit
+def getLocalMean(
+    image: np.ndarray, window_size: Tuple[int, int, int] = (3, 3, 3)
+) -> np.ndarray:
+    """
+    Compute local mean for a 3D image using integral image (fast) without padding.
+    Only voxels where the full window fits are computed.
+
+    Parameters
+    ----------
+    image : np.ndarray
+        3D input image (z, y, x)
+    window_size : int
+        Neighborhood size for local mean calculation (should be odd)
+
+    Returns
+    -------
+    np.ndarray
+        Local mean image, same shape as input, with zeros at boundaries
+        where the full window does not fit. dtype=np.uint16
+    """
+    # z_max, y_max, x_max = image.shape
+    ws_z, ws_y, ws_x = window_size
+    pad = (ws_z // 2, ws_y // 2, ws_x // 2)
+    padded = _padReflect(image, pad)
+
+    z_max, y_max, x_max = padded.shape
+
+    # Compute integral image
+    integral = np.zeros((z_max, y_max, x_max), dtype=np.float64)
+    for z in range(z_max):
+        for y in range(y_max):
+            for x in range(x_max):
+                val = padded[z, y, x]
+                if z > 0:
+                    val += integral[z - 1, y, x]
+                if y > 0:
+                    val += integral[z, y - 1, x]
+                if x > 0:
+                    val += integral[z, y, x - 1]
+                if z > 0 and y > 0:
+                    val -= integral[z - 1, y - 1, x]
+                if z > 0 and x > 0:
+                    val -= integral[z - 1, y, x - 1]
+                if y > 0 and x > 0:
+                    val -= integral[z, y - 1, x - 1]
+                if z > 0 and y > 0 and x > 0:
+                    val += integral[z - 1, y - 1, x - 1]
+                integral[z, y, x] = val
+
+    # Compute local mean
+    local_mean = np.zeros_like(image, dtype=np.float32)
+    z0, y0, x0 = pad
+
+    # Only compute where the full window fits
+    for z in range(ws_z - 1, z_max - z0):
+        for y in range(ws_y - 1, y_max - y0):
+            for x in range(ws_x - 1, x_max - x0):
+                z1, y1, x1 = z - z0, y - y0, x - x0
+                z2, y2, x2 = z + z0, y + y0, x + x0
+
+                s = integral[z2, y2, x2]
+                if z1 > 0:
+                    s -= integral[z1 - 1, y2, x2]
+                if y1 > 0:
+                    s -= integral[z2, y1 - 1, x2]
+                if x1 > 0:
+                    s -= integral[z2, y2, x1 - 1]
+                if z1 > 0 and y1 > 0:
+                    s += integral[z1 - 1, y1 - 1, x2]
+                if z1 > 0 and x1 > 0:
+                    s += integral[z1 - 1, y2, x1 - 1]
+                if y1 > 0 and x1 > 0:
+                    s += integral[z2, y1 - 1, x1 - 1]
+                if z1 > 0 and y1 > 0 and x1 > 0:
+                    s -= integral[z1 - 1, y1 - 1, x1 - 1]
+
+                local_mean[z - z0, y - y0, x - x0] = s / (ws_z * ws_y * ws_x)
+
+    return local_mean.astype(np.uint16)
+
+
+@njit
+def cumSum(arr, axis=None):
+    """
+    Compute cumulative sum manually (Numba-compatible).
+    Supports axis=None, axis=0, and axis=1 (like np.cumsum).
+    """
+    rows, cols = arr.shape
+    out = np.zeros_like(arr)
+    if axis is None:
+        # Flattened cumulative sum
+        flat = arr.ravel()
+        out_flat = out.ravel()
+        total = 0.0
+        for i in range(flat.size):
+            total += flat[i]
+            out_flat[i] = total
+        return out
+    elif axis == 0:
+        # Cumulative sum along rows (down each column)
+        for j in range(cols):
+            total = 0.0
+            for i in range(rows):
+                total += arr[i, j]
+                out[i, j] = total
+        return out
+    elif axis == 1:
+        # Cumulative sum along columns (across each row)
+        for i in range(rows):
+            total = 0.0
+            for j in range(cols):
+                total += arr[i, j]
+                out[i, j] = total
+        return out
+    else:
+        raise ValueError("axis must be None, 0, or 1")
+
+def _validate_window_size(name, window_size):
+    """
+    Validate that a window size argument is a tuple or list of three positive odd integers.
+
+    This function checks that the provided `window_size`:
+      - Is a tuple or list.
+      - Has exactly three elements corresponding to (z, y, x).
+      - Contains only integer values.
+      - Contains only positive values.
+      - Contains only odd values (since even sizes cannot be centered).
+
+    If any of these conditions are not met, a ValueError is raised with a descriptive
+    message that includes the variable name for easier debugging.
+
+    Parameters
+    ----------
+    name : str
+        The name of the variable being validated (used in error messages).
+    window_size : tuple or list of int
+        The window size to validate. Must contain exactly three positive odd integers.
+
+    Raises
+    ------
+    ValueError
+        If `window_size` is not a tuple or list of three positive odd integers.
+    """
+    if not isinstance(window_size, (tuple, list)):
+        raise ValueError(
+            f"{name} must be a tuple or list, got {type(window_size)}"
+        )
+
+    if len(window_size) != 3:
+        raise ValueError(
+            f"{name} 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"{name} elements must be integers, got {window_size}")
+
+    if any(w <= 0 for w in window_size):
+        raise ValueError(f"{name} 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"{name} 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."
+        )
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+
+@njit
+def getThreshold(intensity_values: np.ndarray, local_mean_values: np.ndarray):
+    """
+    Compute 2D Otsu threshold for a local neighborhood.
+
+    Parameters:
+    intensity_values (1D array): Intensity values in the neighborhood
+    local_mean_values (1D array): Local mean values in the neighborhood
+
+    Returns:
+    s_real (int): Optimal intensity threshold
+    t_real (int): Optimal local mean threshold
+    """
+    # Build local 2D histogram
+    g_min, g_max = intensity_values.min(), intensity_values.max()
+    m_min, m_max = local_mean_values.min(), local_mean_values.max()
+
+    # Handle degenerate cases
+    if g_min == g_max or m_min == m_max:
+        return g_min, m_min
+
+    g_range = g_max - g_min + 1
+    m_range = m_max - m_min + 1
+
+    # Build histogram
+    hist_2d = np.zeros((g_range, m_range), dtype=np.uint32)
+    flat_g = intensity_values - g_min
+    flat_m = local_mean_values - m_min
+
+    for i in range(len(flat_g)):
+        hist_2d[flat_g[i], flat_m[i]] += 1
+
+    p = hist_2d.astype(np.float64) / hist_2d.sum()
+
+    # Global means for this neighborhood
+    i_vals = (np.arange(g_range) + g_min)[:, None]
+    j_vals = (np.arange(m_range) + m_min)[None, :]
+
+    mu_T0 = np.sum(i_vals * p)
+    mu_T1 = np.sum(j_vals * p)
+
+    # Cumulative sums
+    P_cum = cumSum(cumSum(p, axis=0), axis=1)
+    mu_i_cum = cumSum(cumSum(i_vals * p, axis=0), axis=1)
+    mu_j_cum = cumSum(cumSum(j_vals * p, axis=0), axis=1)
+
+    max_trace = 0
+    best_s = best_t = 0
+
+    for s in range(g_range - 1):
+        for t in range(m_range - 1):
+            P0 = P_cum[s, t]
+
+            if P0 <= 0 or P0 >= 1.0:
+                continue
+
+            mu_i = mu_i_cum[s, t]
+            mu_j = mu_j_cum[s, t]
+
+            numerator = (mu_i - P0 * mu_T0) ** 2 + (mu_j - P0 * mu_T1) ** 2
+            denominator = P0 * (1 - P0)
+            trace_SB = numerator / denominator
+
+            if trace_SB > max_trace:
+                max_trace = trace_SB
+                best_s, best_t = s, t
+
+    s_real = best_s + g_min
+    t_real = best_t + m_min
+
+    return s_real, t_real
+
+
+def getBinary(
+    img: np.ndarray,
+    window_size: Tuple[int, int, int] = (3, 3, 3),
+    mean_window_size: Tuple[int, int, int] = (3, 3, 3),
+) -> np.ndarray:
+    """
+    Apply local 2D 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 Otsu2D import getBinary
+    >>>
+    >>> # Create sample 3D grayscale image
+    >>> img = np.random.randint(0, 256, size=(50, 50, 50), dtype=np.uint8)
+    >>>
+    >>> # Get binary mask
+    >>> mask = getBinary(img, window_size=(5, 5, 5), delta=0.2, binarize=True)
+    >>> print(mask.shape, mask.dtype)
+    (50, 50, 50) uint8
+    >>>
+    >>> # Get threshold values
+    >>> thresholds = getBinary(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 img.size == 0:
+        raise ValueError("Input image is empty")
+
+    _validate_window_size("window_size", window_size)
+    _validate_window_size("mean_window_size", mean_window_size)
+
+    # Call Numba implementation
+    return _getBinary(img, window_size, mean_window_size)

otsu2d-0.1.0/src/otsu2D/runner.py

@@ -0,0 +1,173 @@
+# ============================================================================
+# Command Line Runner for local 2D Otsu Thresholding
+# ============================================================================
+
+import argparse
+import numpy as np
+import os
+import matplotlib.pyplot as plt
+from otsu2D import getBinary
+
+
+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(binary: np.ndarray, image_path: str, outdir: str, fmt: str):
+    """
+    Save 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]
+
+    bin_path = os.path.join(outdir, f"{base_name}_binary.{fmt}")
+
+    if fmt == "npy":
+        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(bin_path.replace(".tiff", ".npy"), binary)
+            return
+        tifffile.imwrite(bin_path, binary.astype(np.uint8))
+        print(f"Saved TIFF files:\n  {bin_path}")
+
+    else:
+        raise ValueError(f"Unsupported format: {fmt}. Choose 'npy' or 'tiff'.")
+
+
+def show_results(img: np.ndarray, binary: np.ndarray, z_index: int = None):
+    """
+    Show a chosen or middle slice for 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, 2, figsize=(12, 6))
+    axes[0].imshow(img[z_index], cmap="gray")
+    axes[0].set_title(f"Original (z={z_index})")
+    axes[1].imshow(binary[z_index], cmap="gray")
+    axes[1].set_title("Binary Mask")
+    for ax in axes:
+        ax.axis("off")
+
+    plt.tight_layout()
+    plt.show()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run local 2D 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="Intensity window size (z y x). Default: 3 3 3",
+    )
+    parser.add_argument(
+        "--mean_window",
+        type=int,
+        nargs=3,
+        default=[3, 3, 3],
+        help="Local window size (z y x). Default: 3 3 3",
+    )
+    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 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 local 2D Otsu Thresholding
+    print("Running modified Otsu thresholding...")
+    binary = getBinary(img, window_size=tuple(args.window), mean_window_size=tuple(args.mean_window))
+
+    # Print results
+    print("------------------------------------------------------------")
+    print(f"Binary mask shape: {binary.shape}")
+
+    # Save outputs
+    save_output(binary, args.image, args.outdir, args.format)
+
+    # Show outputs if requested
+    if args.show:
+        show_results(img, binary, args.slice)
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

otsu2d-0.1.0/src/otsu2D.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: otsu2D
+Version: 0.1.0
+Summary: Numba-accelerated local 2D Otsu thresholding for 3D images.
+Author-email: John Rick Manzanares <jdolormanzanares@impan.pl>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jhnrckmnznrs/otsu2D
+Project-URL: Issues, https://github.com/jhnrckmnznrs/otsu2D/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 2D Otsu Thresholding
+
+**Local 2D Otsu Thresholding** is a **Numba-accelerated** implementation of a *local* 2D Otsu thresholding method for 3D images.
+
+This algorithm adapts the 2D Otsu threshold within a sliding 3D window, enabling robust segmentation in datasets with spatially varying intensity distributions.
+
+---
+
+## ⚙️ Installation
+
+Install the latest stable version from PyPI:
+
+```bash
+pip install otsu2D
+```
+
+## 🚀 Example Usage
+
+```python
+import numpy as np
+from otsu2D import getBinary
+
+# Create sample 3D image
+img = np.random.randint(0, 256, size=(10, 10, 10), dtype=np.uint8)
+
+# Get threshold map and binary image
+binary = getBinary(img, window_size=(3, 3, 3),  mean_window_size =(3,3,3))
+```
+
+## 🖥️ Command Line Usage
+
+You can execute the script with custom parameters:
+
+```bash
+python runner.py --shape 10 10 10 --window 3 3 3 --mean_window 3 3 3
+```
+
+## 📦 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.

otsu2d-0.1.0/src/otsu2D.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/otsu2D/__init__.py
+src/otsu2D/core.py
+src/otsu2D/runner.py
+src/otsu2D.egg-info/PKG-INFO
+src/otsu2D.egg-info/SOURCES.txt
+src/otsu2D.egg-info/dependency_links.txt
+src/otsu2D.egg-info/entry_points.txt
+src/otsu2D.egg-info/requires.txt
+src/otsu2D.egg-info/top_level.txt
+tests/test_functional.py
+tests/test_validation.py

otsu2d-0.1.0/src/otsu2D.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

otsu2d-0.1.0/src/otsu2D.egg-info/entry_points.txt

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

otsu2d-0.1.0/src/otsu2D.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy
+numba
+
+[tiff]
+tifffile
+matplotlib

otsu2d-0.1.0/src/otsu2D.egg-info/top_level.txt

@@ -0,0 +1 @@
+otsu2D

otsu2d-0.1.0/tests/test_functional.py

@@ -0,0 +1,28 @@
+"""
+Optional functional correctness test for getMask.
+Checks internal consistency without assuming exact threshold values.
+"""
+
+import numpy as np
+from otsu2D.core import getMask  # Adjust based on your package name
+
+
+def test_getBinary_consistency():
+    """Test that binary mask corresponds correctly to threshold map."""
+    # Small synthetic 3D image
+    img = np.random.randint(0, 256, size=(5, 5, 5), dtype=np.uint8)
+
+    # Run getMask
+    binary_mask = getMask(img, window_size=(3, 3, 3), mean_window_size=(3,3,3))
+
+    # Check shapes
+    assert binary_mask.shape == img.shape, "Binary mask shape mismatch"
+
+    # Check types
+    assert binary_mask.dtype == bool, "Binary mask should be boolean"
+
+    print("✓ getMask consistency functional test passed")
+
+
+if __name__ == "__main__":
+    test_getBinary_consistency()

otsu2d-0.1.0/tests/test_validation.py

@@ -0,0 +1,159 @@
+"""
+Input validation tests for getBinary
+"""
+
+import numpy as np
+from otsu2D.core import getBinary
+
+# Color codes for terminal output
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+RESET = "\033[0m"
+
+
+def print_test_result(test_name: str, passed: bool, error_msg: str = ""):
+    """Print formatted test result"""
+    if passed:
+        print(f"{GREEN}✓ PASS{RESET}: {test_name}")
+    else:
+        print(f"{RED}✗ FAIL{RESET}: {test_name}")
+        if error_msg:
+            print(f"  {YELLOW}Expected error not raised or wrong error message{RESET}")
+            print(f"  Got: {error_msg}")
+
+
+def test_validation():
+    """Run all validation tests"""
+    print("=" * 70)
+    print("TESTING INPUT VALIDATION FOR getBinary")
+    print("=" * 70)
+
+    total_tests = 0
+    passed_tests = 0
+
+    # Test 1: Valid input (should NOT raise error)
+    print("\n--- Test 1: Valid Input ---")
+    total_tests += 1
+    try:
+        img = np.random.randint(0, 256, size=(4, 4, 4), dtype=np.uint8)
+        result = getBinary(img, (3, 3, 3), (3,3,3))
+        print_test_result("Valid input should work", True)
+        passed_tests += 1
+    except Exception as e:
+        print_test_result("Valid input should work", False, str(e))
+
+    # Test 2: Wrong number of dimensions (2D)
+    print("\n--- Test 2: 2D Image (should fail) ---")
+    total_tests += 1
+    try:
+        img_2d = np.random.randint(0, 256, size=(4, 4), dtype=np.uint8)
+        result = getBinary(img, (3, 3, 3), (3,3,3))
+        print_test_result("Should reject 2D image", False, "No error raised")
+    except ValueError as e:
+        if "3D" in str(e) and "2D" in str(e):
+            print_test_result("Should reject 2D image", True)
+            passed_tests += 1
+        else:
+            print_test_result("Should reject 2D image", False, str(e))
+    except Exception as e:
+        print_test_result("Should reject 2D image", False, f"Wrong exception: {e}")
+
+    # Test 3: Wrong number of dimensions (4D)
+    print("\n--- Test 3: 4D Image (should fail) ---")
+    total_tests += 1
+    try:
+        img_4d = np.random.randint(0, 256, size=(5, 4, 4, 4), dtype=np.uint8)
+        result = getBinary(img, (3, 3, 3), (3,3,3))
+        print_test_result("Should reject 4D image", False, "No error raised")
+    except ValueError as e:
+        if "3D" in str(e) and "4D" in str(e):
+            print_test_result("Should reject 4D image", True)
+            passed_tests += 1
+        else:
+            print_test_result("Should reject 4D image", False, str(e))
+    except Exception as e:
+        print_test_result("Should reject 4D image", False, f"Wrong exception: {e}")
+
+    # Test 4: Float dtype (should fail)
+    print("\n--- Test 4: Float Image (should fail) ---")
+    total_tests += 1
+    try:
+        img_float = np.random.rand(4, 4, 4).astype(np.float32)
+        result = getBinary(img, (3, 3, 3), (3,3,3))
+        print_test_result("Should reject float dtype", False, "No error raised")
+    except ValueError as e:
+        if "integer" in str(e).lower() and "float" in str(e).lower():
+            print_test_result("Should reject float dtype", True)
+            passed_tests += 1
+        else:
+            print_test_result("Should reject float dtype", False, str(e))
+    except Exception as e:
+        print_test_result("Should reject float dtype", False, f"Wrong exception: {e}")
+
+    # Test 5: Float64 dtype (should fail)
+    print("\n--- Test 5: Float64 Image (should fail) ---")
+    total_tests += 1
+    try:
+        img_float64 = np.random.rand(4, 4, 4)
+        result = getBinary(img, (3, 3, 3), (3,3,3))
+        print_test_result("Should reject float64 dtype", False, "No error raised")
+    except ValueError as e:
+        if "integer" in str(e).lower():
+            print_test_result("Should reject float64 dtype", True)
+            passed_tests += 1
+        else:
+            print_test_result("Should reject float64 dtype", False, str(e))
+    except Exception as e:
+        print_test_result("Should reject float64 dtype", False, f"Wrong exception: {e}")
+
+    # Test 6: Negative value in window_size
+    total_tests += 1
+    try:
+        img = np.random.randint(0, 256, size=(4, 4, 4), dtype=np.uint8)
+        getBinary(img, (3, -3, 3), (3,3,3))
+        print_test_result(
+            "Negative window_size value should fail", False, "No error raised"
+        )
+    except ValueError as e:
+        if "positive" in str(e).lower():
+            print_test_result("Negative window_size value should fail", True)
+            passed_tests += 1
+        else:
+            print_test_result("Negative window_size value should fail", False, str(e))
+    except Exception as e:
+        print_test_result(
+            "Negative window_size value should fail", False, f"Wrong exception: {e}"
+        )
+
+    # Test 7: Negative in mean_window_size
+    total_tests += 1
+    try:
+        img = np.random.randint(0, 256, size=(4, 4, 4), dtype=np.uint8)
+        getBinary(img, (3, 3, 3), (3,-3,3))
+        print_test_result("Negative mean_window_size should fail", False, "No error raised")
+    except ValueError as e:
+        if "non-negative" in str(e).lower() or "positive" in str(e).lower():
+            print_test_result("Negative mean_window_size should fail", True)
+            passed_tests += 1
+        else:
+            print_test_result("Negative mean_window_size should fail", False, str(e))
+    except Exception as e:
+        print_test_result("Negative mean_window_size should fail", False, f"Wrong exception: {e}")
+
+    # Summary
+    print("\n" + "=" * 70)
+    print(f"SUMMARY: {passed_tests}/{total_tests} tests passed")
+    print("=" * 70)
+
+    if passed_tests == total_tests:
+        print(f"{GREEN}All tests passed! ✓{RESET}")
+    else:
+        print(f"{RED}{total_tests - passed_tests} test(s) failed! ✗{RESET}")
+
+    return passed_tests, total_tests
+
+
+# ===== MAIN ENTRY POINT =====
+if __name__ == "__main__":
+    test_validation()