grainmorph 0.2.1__tar.gz → 0.3.0__tar.gz

grainmorph-0.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: grainmorph
+Version: 0.3.0
+Summary: Particle shape analysis and visualization library.
+Author: GrainMorph Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/phykn/grainmorph
+Project-URL: Repository, https://github.com/phykn/grainmorph
+Project-URL: Issues, https://github.com/phykn/grainmorph/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">GrainMorph</h1>
+
+<p align="center">Shape metrics for a single 2D binary particle mask.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/grainmorph/"><img src="https://img.shields.io/pypi/v/grainmorph" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license">
+</p>
+
+- **Wadell roundness**: mean corner radius divided by the inscribed circle radius [1, 2]
+- **Circularity**: `4 * pi * area / perimeter^2`
+- **Sphericity**: inscribed circle radius divided by enclosing circle radius
+- **Aspect ratio**: fitted ellipse major axis divided by minor axis
+- Synthetic test masks and a plot of the fitted circles and ellipse
+
+## Install
+
+```bash
+pip install grainmorph
+```
+
+## Analyze a mask
+
+```python
+import grainmorph as gm
+
+mask = gm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = gm.analyze_mask(mask)
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+`mask` is a 2D `numpy.ndarray` of `bool` or numeric `{0, 1}` values. The largest
+4-connected component is measured with its holes filled, and an empty mask
+returns `None`.
+
+```python
+{
+  "roundness": {"val": float} | None,
+  "circularity": {"val": float} | None,
+  "sphericity": {
+    "val": float,
+    "inscribed": {"x": float, "y": float, "r": float},
+    "enclosing": {"x": float, "y": float, "r": float},
+  } | None,
+  "aspect_ratio": {
+    "val": float,
+    "ellipse": {
+      "major": float, "minor": float,
+      "x": float, "y": float, "angle": float,
+      "w": float, "h": float, "bbox": list[list[float]],
+    },
+  } | None,
+}
+```
+
+Roundness, circularity, and sphericity lie in `0..1`, and aspect ratio is `>= 1`.
+A metric is `None` when the geometry cannot be measured. Coordinates are in
+pixels of the input mask.
+
+## Options
+
+```python
+results = gm.analyze_mask(
+    mask,
+    use_aspect_ratio=False,
+    roundness_params={"max_dev_thresh": 0.5, "circle_fit_thresh": 0.9},
+    eps=0.001,
+    target_dim=384,
+)
+```
+
+- `use_aspect_ratio`, `use_roundness`, `use_circularity`, `use_sphericity`: a metric set to `False` is left out of the result.
+- `roundness_params`: overrides `max_dev_thresh` (0.3, boundary discretization), `circle_fit_thresh` (0.98, corner circle fitting), `alpha_ratio` (0.05) and `beta_ratio` (0.001, boundary smoothing).
+- `eps`: a metric whose denominator is below this is `None`.
+- `target_dim`: a particle larger than this is downscaled for speed, unless that would split or erase thin parts. Coordinates stay in input pixels.
+
+## Plot the result
+
+```python
+gm.utils.plot_analysis_results(mask, results)
+```
+
+## Create test masks
+
+```python
+shape = (256, 256)
+circle = gm.utils.create_circle_mask(shape, (128, 128), 60)
+ellipse = gm.utils.create_ellipse_mask(shape, (128, 128), 90, 50)
+rectangle = gm.utils.create_rectangle_mask(shape, (60, 40), (200, 220))
+square = gm.utils.create_square_mask(shape, (60, 60), 120)
+pentagon = gm.utils.create_pentagon_mask(shape, (128, 128), 90)
+star = gm.utils.create_star_mask(shape, (128, 128), 100, 40, num_points=5)
+triangle = gm.utils.create_triangle_mask(shape, (30, 200), (220, 200), (128, 40))
+```
+
+Shapes are `(height, width)`, and centers and rectangle corners are `(y, x)`.
+Triangle vertices are `(x, y)`.
+
+```python
+mask, info = gm.utils.create_particle_mask(
+    (256, 256), (128, 128), radius=60, sphericity=0.85, roundness=0.5,
+    seed=42, return_info=True,
+)
+print(info["roundness_achieved"], info["target_met"])
+```
+
+`create_particle_mask` roughens an ellipse until its measured roundness
+approaches the target. `info["roundness_achieved"]` is the roundness
+`analyze_mask` gives for the returned mask.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+```
+
+```bash
+python -m pytest -q
+```
+
+```bash
+python -m ruff check --isolated .
+```
+
+```bash
+python -m ruff format --isolated --check src tests
+```
+
+Pushing a `vX.Y.Z` tag publishes to PyPI. The tag must match the version in
+`pyproject.toml`.
+
+## License
+
+MIT
+
+## References
+
+1. H. Wadell, "Volume, shape, and roundness of rock particles," The Journal of Geology, 40(5), 443-451, 1932.
+2. J. Zheng and R. D. Hryciw, "Traditional soil particle sphericity, roundness and surface roughness by computational geometry," Géotechnique, 65(6), 494-506, 2015.

grainmorph-0.3.0/README.md

@@ -0,0 +1,144 @@
+<h1 align="center">GrainMorph</h1>
+
+<p align="center">Shape metrics for a single 2D binary particle mask.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/grainmorph/"><img src="https://img.shields.io/pypi/v/grainmorph" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license">
+</p>
+
+- **Wadell roundness**: mean corner radius divided by the inscribed circle radius [1, 2]
+- **Circularity**: `4 * pi * area / perimeter^2`
+- **Sphericity**: inscribed circle radius divided by enclosing circle radius
+- **Aspect ratio**: fitted ellipse major axis divided by minor axis
+- Synthetic test masks and a plot of the fitted circles and ellipse
+
+## Install
+
+```bash
+pip install grainmorph
+```
+
+## Analyze a mask
+
+```python
+import grainmorph as gm
+
+mask = gm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = gm.analyze_mask(mask)
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+`mask` is a 2D `numpy.ndarray` of `bool` or numeric `{0, 1}` values. The largest
+4-connected component is measured with its holes filled, and an empty mask
+returns `None`.
+
+```python
+{
+  "roundness": {"val": float} | None,
+  "circularity": {"val": float} | None,
+  "sphericity": {
+    "val": float,
+    "inscribed": {"x": float, "y": float, "r": float},
+    "enclosing": {"x": float, "y": float, "r": float},
+  } | None,
+  "aspect_ratio": {
+    "val": float,
+    "ellipse": {
+      "major": float, "minor": float,
+      "x": float, "y": float, "angle": float,
+      "w": float, "h": float, "bbox": list[list[float]],
+    },
+  } | None,
+}
+```
+
+Roundness, circularity, and sphericity lie in `0..1`, and aspect ratio is `>= 1`.
+A metric is `None` when the geometry cannot be measured. Coordinates are in
+pixels of the input mask.
+
+## Options
+
+```python
+results = gm.analyze_mask(
+    mask,
+    use_aspect_ratio=False,
+    roundness_params={"max_dev_thresh": 0.5, "circle_fit_thresh": 0.9},
+    eps=0.001,
+    target_dim=384,
+)
+```
+
+- `use_aspect_ratio`, `use_roundness`, `use_circularity`, `use_sphericity`: a metric set to `False` is left out of the result.
+- `roundness_params`: overrides `max_dev_thresh` (0.3, boundary discretization), `circle_fit_thresh` (0.98, corner circle fitting), `alpha_ratio` (0.05) and `beta_ratio` (0.001, boundary smoothing).
+- `eps`: a metric whose denominator is below this is `None`.
+- `target_dim`: a particle larger than this is downscaled for speed, unless that would split or erase thin parts. Coordinates stay in input pixels.
+
+## Plot the result
+
+```python
+gm.utils.plot_analysis_results(mask, results)
+```
+
+## Create test masks
+
+```python
+shape = (256, 256)
+circle = gm.utils.create_circle_mask(shape, (128, 128), 60)
+ellipse = gm.utils.create_ellipse_mask(shape, (128, 128), 90, 50)
+rectangle = gm.utils.create_rectangle_mask(shape, (60, 40), (200, 220))
+square = gm.utils.create_square_mask(shape, (60, 60), 120)
+pentagon = gm.utils.create_pentagon_mask(shape, (128, 128), 90)
+star = gm.utils.create_star_mask(shape, (128, 128), 100, 40, num_points=5)
+triangle = gm.utils.create_triangle_mask(shape, (30, 200), (220, 200), (128, 40))
+```
+
+Shapes are `(height, width)`, and centers and rectangle corners are `(y, x)`.
+Triangle vertices are `(x, y)`.
+
+```python
+mask, info = gm.utils.create_particle_mask(
+    (256, 256), (128, 128), radius=60, sphericity=0.85, roundness=0.5,
+    seed=42, return_info=True,
+)
+print(info["roundness_achieved"], info["target_met"])
+```
+
+`create_particle_mask` roughens an ellipse until its measured roundness
+approaches the target. `info["roundness_achieved"]` is the roundness
+`analyze_mask` gives for the returned mask.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+```
+
+```bash
+python -m pytest -q
+```
+
+```bash
+python -m ruff check --isolated .
+```
+
+```bash
+python -m ruff format --isolated --check src tests
+```
+
+Pushing a `vX.Y.Z` tag publishes to PyPI. The tag must match the version in
+`pyproject.toml`.
+
+## License
+
+MIT
+
+## References
+
+1. H. Wadell, "Volume, shape, and roundness of rock particles," The Journal of Geology, 40(5), 443-451, 1932.
+2. J. Zheng and R. D. Hryciw, "Traditional soil particle sphericity, roundness and surface roughness by computational geometry," Géotechnique, 65(6), 494-506, 2015.

{grainmorph-0.2.1 → grainmorph-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "grainmorph"
-version = "0.2.1"
+version = "0.3.0"
 authors = [
     { name = "GrainMorph Contributors" }
 ]

{grainmorph-0.2.1 → grainmorph-0.3.0}/src/grainmorph/__init__.py

@@ -1,5 +1,7 @@
+from importlib.metadata import version
+
 from . import utils
 from .analyzer import analyze_mask
 
-__version__ = "0.2.1"
+__version__ = version("grainmorph")
 __all__ = ["analyze_mask", "utils"]

grainmorph-0.3.0/src/grainmorph/analyzer.py

@@ -0,0 +1,55 @@
+from numbers import Integral
+
+import numpy as np
+
+from .mask import prepare_mask, restore_coordinates
+from .metrics import (
+    compute_aspect_ratio,
+    compute_circularity,
+    compute_roundness,
+    compute_sphericity,
+)
+
+
+def analyze_mask(
+    mask,
+    *,
+    use_aspect_ratio=True,
+    use_roundness=True,
+    use_circularity=True,
+    use_sphericity=True,
+    roundness_params=None,
+    eps=0.001,
+    target_dim=384,
+):
+    if not (np.isfinite(eps) and eps > 0):
+        raise ValueError("eps must be > 0 and finite.")
+    if isinstance(target_dim, bool) or not isinstance(target_dim, Integral):
+        raise TypeError("target_dim must be an integer.")
+    if target_dim <= 0:
+        raise ValueError("target_dim must be > 0.")
+    if not isinstance(mask, np.ndarray):
+        raise TypeError("mask must be a numpy.ndarray.")
+    if mask.ndim != 2:
+        raise ValueError(f"mask must be 2D, got {mask.ndim}D.")
+    if mask.dtype.kind not in "biuf" or not ((mask == 0) | (mask == 1)).all():
+        raise ValueError("mask must be binary with values in {0, 1}.")
+
+    mask = mask.astype(np.uint8)
+    if not mask.any():
+        return None
+
+    mask, scale, offset_x, offset_y = prepare_mask(mask, target_dim)
+
+    results = {}
+    if use_aspect_ratio:
+        results["aspect_ratio"] = compute_aspect_ratio(mask, eps)
+    if use_roundness:
+        results["roundness"] = compute_roundness(mask, **(roundness_params or {}))
+    if use_circularity:
+        results["circularity"] = compute_circularity(mask, eps)
+    if use_sphericity:
+        results["sphericity"] = compute_sphericity(mask, eps)
+
+    restore_coordinates(results, scale, offset_x, offset_y)
+    return results

grainmorph-0.3.0/src/grainmorph/mask.py

@@ -0,0 +1,60 @@
+import cv2
+import numpy as np
+
+
+def prepare_mask(mask, target_dim):
+    x0, y0, w, h = cv2.boundingRect(mask)
+    mask = mask[y0 : y0 + h, x0 : x0 + w]
+
+    _, labels, stats, _ = cv2.connectedComponentsWithStats(mask, connectivity=4)
+    largest = 1 + np.argmax(stats[1:, cv2.CC_STAT_AREA])
+    x1, y1, w, h = stats[largest, :4]
+    mask = (labels[y1 : y1 + h, x1 : x1 + w] == largest).astype(np.uint8)
+
+    # Background 4-connected to the padded border stays empty; the rest are holes.
+    flooded = np.pad(mask, 1)
+    cv2.floodFill(flooded, None, (0, 0), 2, flags=4)
+    mask = (flooded[1:-1, 1:-1] != 2).astype(np.uint8)
+
+    scale = 1.0
+    ratio = target_dim / max(w, h)
+    width, height = round(w * ratio), round(h * ratio)
+    if ratio < 1 and min(width, height) > 1:
+        shift = (ratio - 1.0) / 2.0
+        small = cv2.warpAffine(
+            mask,
+            np.array([[ratio, 0.0, shift], [0.0, ratio, shift]]),
+            (width, height),
+            flags=cv2.INTER_NEAREST,
+        )
+        # Downscaling can erase or split thin parts; such a mask keeps its size.
+        if cv2.connectedComponents(small, connectivity=4)[0] == 2:
+            mask = small
+            scale = 1.0 / ratio
+
+    # OpenCV maps pixel centers, so the half-pixel term is part of the inverse map.
+    offset_x = x0 + x1 + (scale - 1.0) / 2.0
+    offset_y = y0 + y1 + (scale - 1.0) / 2.0
+    return mask, scale, offset_x, offset_y
+
+
+def restore_coordinates(results, scale, offset_x, offset_y):
+    sphericity = results.get("sphericity")
+    if sphericity:
+        for key in ("inscribed", "enclosing"):
+            circle = sphericity[key]
+            circle["x"] = float(circle["x"] * scale + offset_x)
+            circle["y"] = float(circle["y"] * scale + offset_y)
+            circle["r"] = float(circle["r"] * scale)
+
+    aspect_ratio = results.get("aspect_ratio")
+    if aspect_ratio:
+        ellipse = aspect_ratio["ellipse"]
+        ellipse["x"] = float(ellipse["x"] * scale + offset_x)
+        ellipse["y"] = float(ellipse["y"] * scale + offset_y)
+        for key in ("major", "minor", "w", "h"):
+            ellipse[key] = float(ellipse[key] * scale)
+        ellipse["bbox"] = [
+            [float(x * scale + offset_x), float(y * scale + offset_y)]
+            for x, y in ellipse["bbox"]
+        ]

grainmorph-0.3.0/src/grainmorph/metrics.py

@@ -0,0 +1,133 @@
+import cv2
+import numpy as np
+
+from .wadell.corner import compute_corner_radii
+from .wadell.discretize import discretize_boundary
+from .wadell.smoothing import smooth_boundary
+
+
+def compute_aspect_ratio(mask, eps):
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    points = contours[0].reshape(-1, 2).astype(np.float32)
+
+    if len(points) < 5:
+        rect = cv2.minAreaRect(points)
+        (x, y), (w, h), angle = rect
+        bbox = cv2.boxPoints(rect).tolist()
+    else:
+        (x, y), (w, h), angle = cv2.fitEllipse(points)
+        theta = np.deg2rad(angle)
+        axes = np.array(
+            [[np.cos(theta), -np.sin(theta)], [np.sin(theta), np.cos(theta)]]
+        )
+        projected = points @ axes
+        x_min, y_min = projected.min(axis=0)
+        x_max, y_max = projected.max(axis=0)
+        corners = [[x_min, y_min], [x_max, y_min], [x_max, y_max], [x_min, y_max]]
+        bbox = (np.array(corners) @ axes.T).tolist()
+
+    if min(w, h) < eps:
+        return None
+
+    return {
+        "val": max(w, h) / min(w, h),
+        "ellipse": {
+            "major": max(w, h),
+            "minor": min(w, h),
+            "x": x,
+            "y": y,
+            "angle": angle,
+            "w": w,
+            "h": h,
+            "bbox": bbox,
+        },
+    }
+
+
+def compute_roundness(
+    mask,
+    max_dev_thresh=0.3,
+    circle_fit_thresh=0.98,
+    alpha_ratio=0.05,
+    beta_ratio=0.001,
+):
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+    boundary = contours[0].reshape(-1, 2).astype(np.float64)
+    if len(boundary) < 3:
+        return None
+
+    smoothed = smooth_boundary(boundary, alpha_ratio, beta_ratio)
+    keypoints = discretize_boundary(smoothed, max_dev_thresh)
+    if len(keypoints) < 3:
+        return None
+
+    inscribed = find_inscribed_circle(mask)
+    radii = compute_corner_radii(
+        keypoints,
+        inscribed["r"],
+        np.array([inscribed["x"], inscribed["y"]]),
+        circle_fit_thresh,
+    )
+    if len(radii) == 0:
+        return None
+
+    return {"val": float(np.clip(np.mean(radii) / inscribed["r"], 0.0, 1.0))}
+
+
+def compute_circularity(mask, eps):
+    # Four-direction Crofton weights indexed by 2x2 pixel pattern, matching
+    # skimage.measure.perimeter_crofton(image, directions=4).
+    weights = np.array(
+        [
+            0,
+            np.pi / 4 * (1 + 1 / np.sqrt(2)),
+            np.pi / (4 * np.sqrt(2)),
+            np.pi / (2 * np.sqrt(2)),
+            0,
+            np.pi / 4 * (1 + 1 / np.sqrt(2)),
+            0,
+            np.pi / (4 * np.sqrt(2)),
+            np.pi / 4,
+            np.pi / 2,
+            np.pi / (4 * np.sqrt(2)),
+            np.pi / (4 * np.sqrt(2)),
+            np.pi / 4,
+            np.pi / 2,
+            0,
+            0,
+        ]
+    )
+    padded = np.pad(mask, 1)
+    patterns = (
+        padded[1:, 1:]
+        + 2 * padded[:-1, 1:]
+        + 4 * padded[1:, :-1]
+        + 8 * padded[:-1, :-1]
+    )
+    perimeter = float(weights @ np.bincount(patterns.ravel(), minlength=16))
+    if perimeter < eps:
+        return None
+
+    area = np.count_nonzero(mask)
+    return {"val": float(np.clip(4.0 * np.pi * area / perimeter**2, 0.0, 1.0))}
+
+
+def compute_sphericity(mask, eps):
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    (x, y), r = cv2.minEnclosingCircle(cv2.convexHull(contours[0]))
+    if r < eps:
+        return None
+
+    inscribed = find_inscribed_circle(mask)
+    return {
+        "val": float(np.clip(inscribed["r"] / r, 0.0, 1.0)),
+        "inscribed": inscribed,
+        "enclosing": {"x": x, "y": y, "r": r},
+    }
+
+
+def find_inscribed_circle(mask):
+    # Padding makes the image border count as background.
+    dist = cv2.distanceTransform(np.pad(mask, 1), cv2.DIST_L2, cv2.DIST_MASK_PRECISE)
+    y, x = np.unravel_index(np.argmax(dist), dist.shape)
+    return {"x": float(x - 1), "y": float(y - 1), "r": float(dist[y, x])}

{grainmorph-0.2.1 → grainmorph-0.3.0}/src/grainmorph/utils/__init__.py

@@ -1,4 +1,6 @@
-from .create_mask import (
+from .particle import create_particle_mask
+from .plot import plot_analysis_results
+from .shape import (
     create_circle_mask,
     create_ellipse_mask,
     create_pentagon_mask,
@@ -7,14 +9,6 @@ from .create_mask import (
     create_star_mask,
     create_triangle_mask,
 )
-from .parametric_mask import create_particle_mask
-
-
-def plot_analysis_results(*args, **kwargs):
-    from .plot import plot_analysis_results as _plot_analysis_results
-
-    return _plot_analysis_results(*args, **kwargs)
-
 
 __all__ = [
     "create_circle_mask",