nbmorph 0.1.0__tar.gz → 0.2.0__tar.gz

{nbmorph-0.1.0/src/nbmorph.egg-info → nbmorph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbmorph
-Version: 0.1.0
+Version: 0.2.0
 Summary: A small package with Numba-accelerated morphological operations.
 Author-email: Marius Causemann <mariusca@simula.no>
 License: MIT License
@@ -42,13 +42,16 @@ Dynamic: license-file
 
 # nbmorph
 
+[![Tests](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml/badge.svg)](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml)
+[![PyPI version](https://badge.fury.io/py/nbmorph.svg)](https://badge.fury.io/py/nbmorph)
+
 A small, Numba-accelerated Python package for morphological operations on 3D labeled images.
 
 `nbmorph` provides a set of common morphological operations optimized for performance using Numba. It is designed to work with 3D NumPy arrays representing labeled image data, where different integer labels correspond to different objects.
 
 ## Features
 
-* **Numba-accelerated:** Operations are just-in-time compiled with Numba for high performance on CPUs.
+* **Numba-accelerated and multithreaded:** Operations are just-in-time compiled with Numba for high performance on CPUs.
 
 * **3D Label Image Support:** All operations are designed for 3D labeled images (integer NumPy arrays).
 
@@ -67,52 +70,52 @@ A small, Numba-accelerated Python package for morphological operations on 3D lab
   * `smooth_labels_spherical`: Smoothes object boundaries by performing an opening followed by a closing.
 
 ![Effect of Morphological Smoothing](img/smoothing_effect.png)
-*Demonstration of the smoothing effect with varying radii and iterations on a sample image.*
+*Demonstration of the smoothing effect with varying radii and iterations on a sample image. The smoothing is followed by a dilation operation to fill up the empty space.*
 
 
 ## Installation
 
-You can install `nbmorph` directly from the source directory using pip:
+You can install `nbmorph` directly from pypi using pip:
 
 ```
-pip install .
+pip install nbmorph
 
 ```
 
 
 ## Usage
 
-Here is a basic example of how to use `nbmorph` to apply morphological smoothing to a 3D labeled image.
+Here is a basic example of how to use `nbmorph` to apply operations to a 3D labeled image.
 
 ```
 import numpy as np
 import nbmorph
+import numba
+
+numba.set_num_threads(4)
 
 # Create a sample 3D labeled image
-# For example, a 5x5x5 cube of label 1 in a 10x10x10 volume
+# For example, a 5x5x5 cube of two different labels in a 10x10x10 volume
 labels = np.zeros((10, 10, 10), dtype=np.uint16)
-labels[2:7, 2:7, 2:7] = 1
+labels[2:7, 2:7, 2:5] = 1
+labels[2:7, 2:7, 5:7] = 2
 
-# Apply morphological smoothing with a radius of 1
-smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
-
-print("Smoothing complete. The smoothed labels are in the 'smoothed_labels' array.")
-
-```
+# First execution may take a while due to numba compilation
+# Apply morphological erosion with a radius of 1
+eroded_labels = nbmorph.erode_labels_spherical(labels, radius=1)
 
-## Operations
+# Apply morphological dilation with a radius of 1
+dilated_labels = nbmorph.dilate_labels_spherical(labels, radius=1)
 
-The core functions of the library are:
+# Apply morphological opening with a radius of 1
+opened_labels = nbmorph.open_labels_spherical(labels, radius=1)
 
-* `nbmorph.dilate_labels_spherical(labels, radius=1)`
+# Apply morphological closing with a radius of 1
+closed_labels = nbmorph.close_labels_spherical(labels, radius=1)
 
-* `nbmorph.erode_labels_spherical(labels, radius=1)`
-
-* `nbmorph.open_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.close_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.smooth_labels_spherical(labels, radius=1, iterations=1)`
+# Apply morphological smoothing with a radius of 1
+smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
+```
 
 ## Testing
 

{nbmorph-0.1.0 → nbmorph-0.2.0}/README.md

@@ -1,12 +1,15 @@
 # nbmorph
 
+[![Tests](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml/badge.svg)](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml)
+[![PyPI version](https://badge.fury.io/py/nbmorph.svg)](https://badge.fury.io/py/nbmorph)
+
 A small, Numba-accelerated Python package for morphological operations on 3D labeled images.
 
 `nbmorph` provides a set of common morphological operations optimized for performance using Numba. It is designed to work with 3D NumPy arrays representing labeled image data, where different integer labels correspond to different objects.
 
 ## Features
 
-* **Numba-accelerated:** Operations are just-in-time compiled with Numba for high performance on CPUs.
+* **Numba-accelerated and multithreaded:** Operations are just-in-time compiled with Numba for high performance on CPUs.
 
 * **3D Label Image Support:** All operations are designed for 3D labeled images (integer NumPy arrays).
 
@@ -25,52 +28,52 @@ A small, Numba-accelerated Python package for morphological operations on 3D lab
   * `smooth_labels_spherical`: Smoothes object boundaries by performing an opening followed by a closing.
 
 ![Effect of Morphological Smoothing](img/smoothing_effect.png)
-*Demonstration of the smoothing effect with varying radii and iterations on a sample image.*
+*Demonstration of the smoothing effect with varying radii and iterations on a sample image. The smoothing is followed by a dilation operation to fill up the empty space.*
 
 
 ## Installation
 
-You can install `nbmorph` directly from the source directory using pip:
+You can install `nbmorph` directly from pypi using pip:
 
 ```
-pip install .
+pip install nbmorph
 
 ```
 
 
 ## Usage
 
-Here is a basic example of how to use `nbmorph` to apply morphological smoothing to a 3D labeled image.
+Here is a basic example of how to use `nbmorph` to apply operations to a 3D labeled image.
 
 ```
 import numpy as np
 import nbmorph
+import numba
+
+numba.set_num_threads(4)
 
 # Create a sample 3D labeled image
-# For example, a 5x5x5 cube of label 1 in a 10x10x10 volume
+# For example, a 5x5x5 cube of two different labels in a 10x10x10 volume
 labels = np.zeros((10, 10, 10), dtype=np.uint16)
-labels[2:7, 2:7, 2:7] = 1
+labels[2:7, 2:7, 2:5] = 1
+labels[2:7, 2:7, 5:7] = 2
 
-# Apply morphological smoothing with a radius of 1
-smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
-
-print("Smoothing complete. The smoothed labels are in the 'smoothed_labels' array.")
-
-```
+# First execution may take a while due to numba compilation
+# Apply morphological erosion with a radius of 1
+eroded_labels = nbmorph.erode_labels_spherical(labels, radius=1)
 
-## Operations
+# Apply morphological dilation with a radius of 1
+dilated_labels = nbmorph.dilate_labels_spherical(labels, radius=1)
 
-The core functions of the library are:
+# Apply morphological opening with a radius of 1
+opened_labels = nbmorph.open_labels_spherical(labels, radius=1)
 
-* `nbmorph.dilate_labels_spherical(labels, radius=1)`
+# Apply morphological closing with a radius of 1
+closed_labels = nbmorph.close_labels_spherical(labels, radius=1)
 
-* `nbmorph.erode_labels_spherical(labels, radius=1)`
-
-* `nbmorph.open_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.close_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.smooth_labels_spherical(labels, radius=1, iterations=1)`
+# Apply morphological smoothing with a radius of 1
+smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
+```
 
 ## Testing
 
@@ -91,4 +94,4 @@ python scripts/benchmark.py
 
 ## License
 
-This project is licensed under the MIT License - see the `LICENSE` file for details.
+This project is licensed under the MIT License - see the `LICENSE` file for details.

{nbmorph-0.1.0 → nbmorph-0.2.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "nbmorph"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
   { name="Marius Causemann", email="mariusca@simula.no" },
 ]

{nbmorph-0.1.0 → nbmorph-0.2.0}/src/nbmorph/diamond_kernel.py

@@ -5,10 +5,38 @@ from .ops import choose_op
 
 @numba.njit(inline="always")
 def clamp(index, size):
+    """
+    Clamps an index to valid bounds for a 3x3 neighborhood.
+
+    This function calculates the valid range for a 3x3 neighborhood around a given index,
+    ensuring it stays within the array bounds.
+
+    Args:
+        index (int): The center index.
+        size (int): The size of the array dimension.
+
+    Returns:
+        Tuple[int, int]: The lower and upper bounds for the neighborhood.
+    """
     return max(0,index-1), min(index+1, size-1)
   
 @numba.njit(parallel=True, cache=True)
 def diamond_loop_padded(data, opname:str, out=None, onlyzero=False):
+    """
+    Applies a morphological operation using a diamond (6-connected) kernel to a 3D array.
+
+    This function processes each voxel in the array, applying the specified operation
+    to its 6-connected neighbors. It handles boundary conditions by padding.
+
+    Args:
+        data (np.ndarray): The input 3D array.
+        opname (str): The operation to perform ("min", "max", "zeroedges").
+        out (np.ndarray, optional): The output array. If None, a new array is created.
+        onlyzero (bool, optional): If True, only processes voxels with value 0. Defaults to False.
+
+    Returns:
+        np.ndarray: The processed 3D array.
+    """
     if out is None:
         out = np.empty_like(data)
     assert data.shape == out.shape

nbmorph-0.2.0/src/nbmorph/minmax.py

@@ -0,0 +1,72 @@
+import numpy as np
+import numba
+from .diamond_kernel import diamond_loop_padded 
+from .box_kernel import kernel3x3x3
+
+@numba.njit(cache=True)
+def minimum_box(a, out=None, onlyzero=False):
+    """
+    Applies a 3x3x3 box minimum filter to a 3D array.
+
+    This function computes the minimum value within a 3x3x3 neighborhood for each voxel.
+
+    Args:
+        a (np.ndarray): The input 3D array.
+        out (np.ndarray, optional): The output array. If None, a new array is created.
+        onlyzero (bool, optional): If True, only processes voxels with value 0. Defaults to False.
+
+    Returns:
+        np.ndarray: The filtered 3D array.
+    """
+    return kernel3x3x3(a, opname="min", out=out, onlyzero=onlyzero)
+
+@numba.njit(cache=True)
+def maximum_box(a, out=None, onlyzero=False):
+    """
+    Applies a 3x3x3 box maximum filter to a 3D array.
+
+    This function computes the maximum value within a 3x3x3 neighborhood for each voxel.
+
+    Args:
+        a (np.ndarray): The input 3D array.
+        out (np.ndarray, optional): The output array. If None, a new array is created.
+        onlyzero (bool, optional): If True, only processes voxels with value 0. Defaults to False.
+
+    Returns:
+        np.ndarray: The filtered 3D array.
+    """
+    return kernel3x3x3(a, opname="max", out=out, onlyzero=onlyzero)
+
+@numba.njit(cache=True)
+def minimum_diamond(data, out=None, onlyzero=False):
+    """
+    Applies a diamond (6-connected) minimum filter to a 3D array.
+
+    This function computes the minimum value within a diamond-shaped neighborhood for each voxel.
+
+    Args:
+        data (np.ndarray): The input 3D array.
+        out (np.ndarray, optional): The output array. If None, a new array is created.
+        onlyzero (bool, optional): If True, only processes voxels with value 0. Defaults to False.
+
+    Returns:
+        np.ndarray: The filtered 3D array.
+    """
+    return diamond_loop_padded(data, opname="min", out=out, onlyzero=onlyzero)
+
+@numba.njit(cache=True)
+def maximum_diamond(data, out=None, onlyzero=False):
+    """
+    Applies a diamond (6-connected) maximum filter to a 3D array.
+
+    This function computes the maximum value within a diamond-shaped neighborhood for each voxel.
+
+    Args:
+        data (np.ndarray): The input 3D array.
+        out (np.ndarray, optional): The output array. If None, a new array is created.
+        onlyzero (bool, optional): If True, only processes voxels with value 0. Defaults to False.
+
+    Returns:
+        np.ndarray: The filtered 3D array.
+    """
+    return diamond_loop_padded(data, opname="max", out=out, onlyzero=onlyzero)

{nbmorph-0.1.0 → nbmorph-0.2.0}/src/nbmorph/mode.py

@@ -4,19 +4,32 @@ from .minmax import maximum_box, maximum_diamond
 
 @numba.njit
 def fast_mode(a):
+    """
+    Find the mode of a 1D array, ignoring zeros.
+
+    This is an O(n^2) algorithm, but fast on small data (len(a) < 50), as needed here.
+
+    Args:
+        a (np.ndarray): The input 1D array.
+
+    Returns:
+        The mode of the array.
+    """
     return fast_modeN(a, len(a))
 
 @numba.njit(inline="always")
 def fast_modeN(a, N):
     """
-    Find the mode of a 1D array, ignoring zeros. This is an O(n^2) algorithm, 
-    but fast on small data (len(a) < 50), as needed here.
+    Find the mode of the first N elements of a 1D array, ignoring zeros.
+
+    This is an O(n^2) algorithm, but fast on small data (N < 50), as needed here.
 
     Args:
         a (np.ndarray): The input 1D array.
+        N (int): The number of elements to consider.
 
     Returns:
-        The mode of the array.
+        The mode of the first N elements of the array.
     """
     max_count = 0
     current_count = 0
@@ -40,7 +53,16 @@ def fast_modeN(a, N):
 
 @numba.njit(inline="always")
 def _cs(a, b):
-    """Performs a compare-swap on two values."""
+    """
+    Performs a compare-swap on two values.
+
+    Args:
+        a: First value.
+        b: Second value.
+
+    Returns:
+        Tuple containing the smaller value followed by the larger value.
+    """
     if a > b:
         return b, a
     else:
@@ -54,7 +76,15 @@ def sort26_network(
 ):
     """
     Sorts 26 elements using a pre-defined sorting network.
-    From https://bertdobbelaere.github.io/sorting_networks.html
+
+    This function implements a sorting network from https://bertdobbelaere.github.io/sorting_networks.html
+    to efficiently sort a fixed number of elements.
+
+    Args:
+        v0-v25: The 26 values to be sorted.
+
+    Returns:
+        Tuple containing the 26 input values in sorted order (ascending).
     """
     v0, v1 = _cs(v0, v1); v2, v3 = _cs(v2, v3); v4, v5 = _cs(v4, v5); v6, v7 = _cs(v6, v7); v8, v9 = _cs(v8, v9); v10, v11 = _cs(v10, v11); v12, v13 = _cs(v12, v13); v14, v15 = _cs(v14, v15); v16, v17 = _cs(v16, v17); v18, v19 = _cs(v18, v19); v20, v21 = _cs(v20, v21); v22, v23 = _cs(v22, v23); v24, v25 = _cs(v24, v25)
     v0, v2 = _cs(v0, v2); v1, v3 = _cs(v1, v3); v4, v6 = _cs(v4, v6); v5, v7 = _cs(v5, v7); v8, v10 = _cs(v8, v10); v9, v11 = _cs(v9, v11); v14, v16 = _cs(v14, v16); v15, v17 = _cs(v15, v17); v18, v20 = _cs(v18, v20); v19, v21 = _cs(v19, v21); v22, v24 = _cs(v22, v24); v23, v25 = _cs(v23, v25)
@@ -78,7 +108,15 @@ def sort26_network(
 def sort6_network(v0, v1, v2, v3, v4, v5):
     """
     Sorts 6 elements using a pre-defined sorting network.
-    From https://bertdobbelaere.github.io/sorting_networks.html
+
+    This function implements a sorting network from https://bertdobbelaere.github.io/sorting_networks.html
+    to efficiently sort a fixed number of elements.
+
+    Args:
+        v0-v5: The 6 values to be sorted.
+
+    Returns:
+        Tuple containing the 6 input values in sorted order (ascending).
     """
     v0, v5 = _cs(v0, v5)
     v1, v3 = _cs(v1, v3)
@@ -102,11 +140,20 @@ def sort6_network(v0, v1, v2, v3, v4, v5):
 @numba.njit(inline="always")
 def mode_diamond(data, z, y, x):
     """
-    Calculates the mode of a diamond neighborhood.
-    The neighborhood includes its 6 direct neighbors: 
-    (z, y, x-1), (z, y, x+1), (z, y-1, x),
-    (z, y+1, x), (z-1, y, x), (z+1, y, x).
-    """    
+    Calculates the mode of a diamond neighborhood in a 3D array.
+
+    The diamond neighborhood includes the 6 direct (6-connected) neighbors of the center point:
+    (z, y, x-1), (z, y, x+1), (z, y-1, x), (z, y+1, x), (z-1, y, x), (z+1, y, x).
+
+    Args:
+        data (np.ndarray): The 3D input array.
+        z (int): Z-coordinate of the center point.
+        y (int): Y-coordinate of the center point.
+        x (int): X-coordinate of the center point.
+
+    Returns:
+        The mode (most frequent value) of the diamond neighborhood, ignoring zeros.
+    """
 
     (v0, v1, v2, v3, v4, v5) = sort6_network(
         data[z, y, x-1], data[z, y, x+1],
@@ -140,9 +187,19 @@ def mode_diamond(data, z, y, x):
 @numba.njit(inline="always")
 def mode_box(data, z, y, x):
     """
-    Calculates the mode of a 3x3x3 neighborhood by explicitly
-    accessing all 26 neighbors.
-    """    
+    Calculates the mode of a 3x3x3 neighborhood in a 3D array.
+
+    The neighborhood includes all 26 surrounding voxels of the center point.
+
+    Args:
+        data (np.ndarray): The 3D input array.
+        z (int): Z-coordinate of the center point.
+        y (int): Y-coordinate of the center point.
+        x (int): X-coordinate of the center point.
+
+    Returns:
+        The mode (most frequent value) of the 3x3x3 neighborhood, ignoring zeros.
+    """
 
     (v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, v10, v11,
     v12, v13, v14, v15, v16, v17, v18, v19, v20,
@@ -236,7 +293,26 @@ def mode_box(data, z, y, x):
 
 
 @numba.njit(inline="always")
-def load_box_stencil(data, z, y, x, sz,sy,sx, nbs):
+def load_box_stencil(data, z, y, x, sz, sy, sx, nbs):
+    """
+    Loads a 3x3x3 box stencil into a neighbors array, counting only non-zero values.
+
+    This function extracts the 26 neighbors of a center point in a 3D array, handling
+    boundary conditions appropriately.
+
+    Args:
+        data (np.ndarray): The 3D input array.
+        z (int): Z-coordinate of the center point.
+        y (int): Y-coordinate of the center point.
+        x (int): X-coordinate of the center point.
+        sz (int): Size of the array in Z-dimension.
+        sy (int): Size of the array in Y-dimension.
+        sx (int): Size of the array in X-dimension.
+        nbs (np.ndarray): Pre-allocated array to store the neighbor values.
+
+    Returns:
+        int: The number of non-zero values loaded into the neighbors array.
+    """
     z1 = -1 if z > 0 else 0; z2 = 2 if z < sz-1 else 1
     y1 = -1 if y > 0 else 0; y2 = 2 if y < sy-1 else 1
     x1 = -1 if x > 0 else 0; x2 = 2 if x < sx-1 else 1

{nbmorph-0.1.0 → nbmorph-0.2.0}/src/nbmorph/morphology.py

@@ -12,12 +12,14 @@ def dilate_labels_spherical(labels: np.ndarray, radius: int=1,
     Performs fast, quasi-spherical multilabel dilation on a CPU.
     This approximates a spherical structuring element by alternating between a box (3x3x3)
     and a diamond (6-connected) kernel for each iteration.
+
     Args:
-        labels: The input 3D labeled image (must be an integer type).
-        radius: The dilation radius in voxels. Each iteration expands by one voxel.
+        labels (np.ndarray): The input 3D labeled image (must be an integer type).
+        radius (int, optional): The dilation radius in voxels. Each iteration expands by one voxel. Defaults to 1.
+        struct_sequence (str, optional): The sequence of structuring elements to use. "D" for diamond, "B" for box. Defaults to "DDB".
 
     Returns:
-        The dilated 3D labeled image.
+        np.ndarray: The dilated 3D labeled image.
     """
     # Use two buffers that are swapped (ping-pong) to propagate labels iteratively
     # We start by copying the original labels to both
@@ -45,11 +47,12 @@ def erode_labels_spherical(labels: np.ndarray, radius: int=1,
     Performs fast, quasi-spherical multilabel erosion on a CPU.
 
     Args:
-        labels (np.ndarray): The input 3D labeled image.
-        radius (int, optional): The erosion radius. Defaults to 1.
+        labels (np.ndarray): The input 3D labeled image (must be an integer type).
+        radius (int, optional): The erosion radius in voxels. Each iteration shrinks by one voxel. Defaults to 1.
+        struct_sequence (str, optional): The sequence of structuring elements to use. "D" for diamond, "B" for box. Defaults to "DDB".
 
     Returns:
-        np.ndarray: The eroded labeled image.
+        np.ndarray: The eroded 3D labeled image.
     """
     assert radius > 0
     pong = np.copy(labels)
@@ -71,18 +74,18 @@ def erode_labels_spherical(labels: np.ndarray, radius: int=1,
         ping, pong = pong, ping
     return ping
 
-#@numba.njit
+@numba.njit
 def open_labels_spherical(labels: np.ndarray, radius: int=1, iterations:int=1) -> np.ndarray:
     """
     Performs a morphological opening on a labeled image.
 
     Args:
-        labels (np.ndarray): The input 3D labeled image.
-        radius (int): The radius of the spherical structuring element.
+        labels (np.ndarray): The input 3D labeled image (must be an integer type).
+        radius (int, optional): The radius of the spherical structuring element. Defaults to 1.
         iterations (int, optional): The number of iterations. Defaults to 1.
 
     Returns:
-        np.ndarray: The opened labeled image.
+        np.ndarray: The opened 3D labeled image.
     """
     out = np.copy(labels)
     for i in range(iterations):
@@ -90,42 +93,44 @@ def open_labels_spherical(labels: np.ndarray, radius: int=1, iterations:int=1) -
         out = dilate_labels_spherical(out, radius)
     return out
 
-#@numba.njit
+@numba.njit
 def close_labels_spherical(labels: np.ndarray, radius: int, iterations:int=1) -> np.ndarray:
     """
     Performs a morphological closing on a labeled image.
 
     Args:
-        labels (np.ndarray): The input 3D labeled image.
+        labels (np.ndarray): The input 3D labeled image (must be an integer type).
         radius (int): The radius of the spherical structuring element.
         iterations (int, optional): The number of iterations. Defaults to 1.
 
     Returns:
-        np.ndarray: The closed labeled image.
+        np.ndarray: The closed 3D labeled image.
     """
     out = np.copy(labels)
-    #print("closing...")
     for i in range(iterations):
-        out1 = dilate_labels_spherical(out, radius)
-        #print(f"after dilate: {out1.sum()}")
-        out = erode_labels_spherical(out1, radius)
-        #print(f"after erode: {out.sum()}")
+        out = dilate_labels_spherical(out, radius)
+        out = erode_labels_spherical(out, radius)
     return out
 
-#@numba.njit
-def smooth_labels_spherical(labels: np.ndarray, radius: int, iterations:int=1) -> np.ndarray:
+@numba.njit
+def smooth_labels_spherical(labels: np.ndarray, radius: int,
+                            iterations:int=1, dilate_radius:int=0) -> np.ndarray:
     """
     Performs a morphological smoothing on a labeled image.
 
     Args:
-        labels (np.ndarray): The input 3D labeled image.
+        labels (np.ndarray): The input 3D labeled image (must be an integer type).
         radius (int): The radius of the spherical structuring element.
         iterations (int, optional): The number of iterations. Defaults to 1.
+        dilate_radius (int, optional): Additional dilation radius to apply after smoothing. Defaults to 0.
 
     Returns:
-        np.ndarray: The smoothed labeled image.
+        np.ndarray: The smoothed 3D labeled image.
     """
+    out = np.copy(labels)
     for i in range(iterations):
-        labels = open_labels_spherical(labels, radius)
-        labels = close_labels_spherical(labels, radius)
-    return labels
+        out = open_labels_spherical(out, radius)
+        out = close_labels_spherical(out, radius)
+        if dilate_radius > 0:
+            out = dilate_labels_spherical(out, dilate_radius)
+    return out

nbmorph-0.2.0/src/nbmorph/ops.py

@@ -0,0 +1,40 @@
+import numba
+
+@numba.njit(inline="always")
+def zero_if_not_allequal(nbs):
+    """
+    Returns the first value if all values in the array are equal, otherwise returns 0.
+
+    This function is used for the "zeroedges" operation to identify boundary voxels.
+
+    Args:
+        nbs (np.ndarray): Array of neighbor values.
+
+    Returns:
+        int: The first value if all values are equal, otherwise 0.
+    """
+    if max(nbs) == min(nbs):
+        return nbs[0]
+    else:
+        return 0
+
+@numba.njit(inline="always")
+def choose_op(opname, nbs, onlyzero):
+    """
+    Selects and applies a morphological operation to a neighborhood of values.
+
+    This function dispatches to the appropriate operation based on the opname parameter.
+
+    Args:
+        opname (str): The operation to perform ("min", "max", "zeroedges").
+        nbs (np.ndarray): Array of neighbor values.
+        onlyzero (bool): If True, only processes voxels with value 0.
+
+    Returns:
+        The result of the applied operation.
+    """
+    if onlyzero and nbs[0]>0: return nbs[0]
+    match opname:
+        case "min": return min(nbs)
+        case "max": return max(nbs)
+        case "zeroedges": return zero_if_not_allequal(nbs)

{nbmorph-0.1.0 → nbmorph-0.2.0}/src/nbmorph/utils.py

@@ -3,4 +3,4 @@ import numba
 
 @numba.njit
 def cycle(s: str, i:int):
-    return (s*i)[:i]
+    return (s*i)[:i]

{nbmorph-0.1.0 → nbmorph-0.2.0}/src/nbmorph/zero_edges.py

@@ -5,10 +5,14 @@ from .box_kernel import kernel3x3x3
 @numba.njit(cache=True)
 def zero_label_edges_box(a, out=None):
     """
-    Set the edges of labels to zero.
+    Sets the edges of labels to zero using a 3x3x3 box neighborhood.
+
+    This function identifies voxels at the boundary of labeled regions and sets them to zero,
+    effectively eroding the labels by one voxel.
 
     Args:
         a (np.ndarray): The input 3D labeled array.
+        out (np.ndarray, optional): The output array. If None, a new array is created.
 
     Returns:
         np.ndarray: The array with label edges set to zero.
@@ -19,7 +23,3 @@ def zero_label_edges_box(a, out=None):
 @numba.njit(cache=True)
 def zero_label_edges_diamond(data, out=None):
     return diamond_loop_padded(data, out=out, opname="zeroedges")
-
-
-
-

{nbmorph-0.1.0 → nbmorph-0.2.0/src/nbmorph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbmorph
-Version: 0.1.0
+Version: 0.2.0
 Summary: A small package with Numba-accelerated morphological operations.
 Author-email: Marius Causemann <mariusca@simula.no>
 License: MIT License
@@ -42,13 +42,16 @@ Dynamic: license-file
 
 # nbmorph
 
+[![Tests](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml/badge.svg)](https://github.com/MariusCausemann/nbmorph/actions/workflows/test.yaml)
+[![PyPI version](https://badge.fury.io/py/nbmorph.svg)](https://badge.fury.io/py/nbmorph)
+
 A small, Numba-accelerated Python package for morphological operations on 3D labeled images.
 
 `nbmorph` provides a set of common morphological operations optimized for performance using Numba. It is designed to work with 3D NumPy arrays representing labeled image data, where different integer labels correspond to different objects.
 
 ## Features
 
-* **Numba-accelerated:** Operations are just-in-time compiled with Numba for high performance on CPUs.
+* **Numba-accelerated and multithreaded:** Operations are just-in-time compiled with Numba for high performance on CPUs.
 
 * **3D Label Image Support:** All operations are designed for 3D labeled images (integer NumPy arrays).
 
@@ -67,52 +70,52 @@ A small, Numba-accelerated Python package for morphological operations on 3D lab
   * `smooth_labels_spherical`: Smoothes object boundaries by performing an opening followed by a closing.
 
 ![Effect of Morphological Smoothing](img/smoothing_effect.png)
-*Demonstration of the smoothing effect with varying radii and iterations on a sample image.*
+*Demonstration of the smoothing effect with varying radii and iterations on a sample image. The smoothing is followed by a dilation operation to fill up the empty space.*
 
 
 ## Installation
 
-You can install `nbmorph` directly from the source directory using pip:
+You can install `nbmorph` directly from pypi using pip:
 
 ```
-pip install .
+pip install nbmorph
 
 ```
 
 
 ## Usage
 
-Here is a basic example of how to use `nbmorph` to apply morphological smoothing to a 3D labeled image.
+Here is a basic example of how to use `nbmorph` to apply operations to a 3D labeled image.
 
 ```
 import numpy as np
 import nbmorph
+import numba
+
+numba.set_num_threads(4)
 
 # Create a sample 3D labeled image
-# For example, a 5x5x5 cube of label 1 in a 10x10x10 volume
+# For example, a 5x5x5 cube of two different labels in a 10x10x10 volume
 labels = np.zeros((10, 10, 10), dtype=np.uint16)
-labels[2:7, 2:7, 2:7] = 1
+labels[2:7, 2:7, 2:5] = 1
+labels[2:7, 2:7, 5:7] = 2
 
-# Apply morphological smoothing with a radius of 1
-smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
-
-print("Smoothing complete. The smoothed labels are in the 'smoothed_labels' array.")
-
-```
+# First execution may take a while due to numba compilation
+# Apply morphological erosion with a radius of 1
+eroded_labels = nbmorph.erode_labels_spherical(labels, radius=1)
 
-## Operations
+# Apply morphological dilation with a radius of 1
+dilated_labels = nbmorph.dilate_labels_spherical(labels, radius=1)
 
-The core functions of the library are:
+# Apply morphological opening with a radius of 1
+opened_labels = nbmorph.open_labels_spherical(labels, radius=1)
 
-* `nbmorph.dilate_labels_spherical(labels, radius=1)`
+# Apply morphological closing with a radius of 1
+closed_labels = nbmorph.close_labels_spherical(labels, radius=1)
 
-* `nbmorph.erode_labels_spherical(labels, radius=1)`
-
-* `nbmorph.open_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.close_labels_spherical(labels, radius=1, iterations=1)`
-
-* `nbmorph.smooth_labels_spherical(labels, radius=1, iterations=1)`
+# Apply morphological smoothing with a radius of 1
+smoothed_labels = nbmorph.smooth_labels_spherical(labels, radius=1)
+```
 
 ## Testing
 

nbmorph-0.1.0/src/nbmorph/minmax.py

@@ -1,22 +0,0 @@
-import numpy as np
-import numba
-from .diamond_kernel import diamond_loop_padded 
-from .box_kernel import kernel3x3x3
-
-@numba.njit(cache=True)
-def minimum_box(a, out=None,onlyzero=False):
-    return kernel3x3x3(a, opname="min", out=out, onlyzero=onlyzero)
-
-@numba.njit(cache=True)
-def maximum_box(a, out=None,onlyzero=False):
-    return kernel3x3x3(a, opname="max", out=out, onlyzero=onlyzero)
-
-@numba.njit(cache=True)
-def minimum_diamond(data, out=None, onlyzero=False):
-    return diamond_loop_padded(data, opname="min", out=out, onlyzero=onlyzero)
-
-@numba.njit(cache=True)
-def maximum_diamond(data, out=None, onlyzero=False):
-    return diamond_loop_padded(data, opname="max", out=out, onlyzero=onlyzero)
-
-

nbmorph-0.1.0/src/nbmorph/ops.py

@@ -1,16 +0,0 @@
-import numba
-
-@numba.njit(inline="always")
-def zero_if_not_allequal(nbs):
-    if max(nbs) == min(nbs):
-        return nbs[0]
-    else:
-        return 0
-
-@numba.njit(inline="always")
-def choose_op(opname, nbs, onlyzero):
-    if onlyzero and nbs[0]>0: return nbs[0]
-    match opname:
-        case "min": return min(nbs)
-        case "max": return max(nbs)
-        case "zeroedges": return zero_if_not_allequal(nbs)