grainmorph 0.2.0__tar.gz

grainmorph-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GrainMorph Contributors
+
+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.

grainmorph-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: grainmorph
+Version: 0.2.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
+
+# GrainMorph
+
+GrainMorph analyzes a single 2D binary particle mask and returns geometric shape metrics.
+
+| Metric | Meaning |
+|---|---|
+| Wadell roundness | Corner curvature-based roundness |
+| 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 |
+
+Roundness, circularity, and sphericity are clipped to `0..1`. Aspect ratio is `>= 1`.
+
+## Installation
+
+GrainMorph requires Python `3.12+`.
+
+```bash
+pip install grainmorph
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the tests and code checks with the same Python environment:
+
+```bash
+python -m pytest -q
+python -m ruff check --isolated .
+python -m ruff format --isolated --check src tests
+```
+
+## Quick Start
+
+```python
+import grainmorph as pm
+
+mask = pm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = pm.analyze_mask(mask)
+
+if results is None:
+    raise ValueError("mask has no foreground pixels")
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+Visualize the results:
+
+```python
+pm.utils.plot_analysis_results(mask, results)
+```
+
+## API
+
+```python
+pm.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,
+)
+```
+
+| Parameter | Description |
+|---|---|
+| `mask` | 2D `numpy.ndarray` with `bool` or `{0, 1}` values |
+| `use_*` | Toggle individual metrics on/off |
+| `roundness_params` | Optional dict to override Wadell roundness parameters |
+| `eps` | Tolerance for geometric computations |
+| `target_dim` | Particle bounds larger than this are downscaled for speed, then coordinates are restored |
+
+`roundness_params` accepts these Wadell options. Defaults are defined in
+`wadell/roundness.py` and also apply to synthetic particle calibration:
+
+| Option | Default | Stage |
+|---|---|---|
+| `max_dev_thresh` | `0.3` | Boundary discretization |
+| `circle_fit_thresh` | `0.98` | Corner circle fitting |
+| `alpha_ratio` | `0.05` | Boundary smoothing |
+| `beta_ratio` | `0.001` | Boundary smoothing |
+
+Returns `None` for an empty mask. Otherwise, returns an `AnalysisResult` dict. Disabled metrics are omitted; enabled metrics are present and may be `None` when the geometry cannot be measured.
+
+## Result Shape
+
+```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,
+}
+```
+
+## Input Rules
+
+- `mask` must be a 2D `numpy.ndarray`
+- Allowed values are `bool` or numeric `{0, 1}`
+- Floating masks must not contain `NaN` or `inf`
+- Empty mask returns `None`
+- The largest 4-connected foreground component is selected and holes are filled
+- Surrounding zero padding does not change the measured shape
+- Downscaling is skipped if its output would have a one-pixel axis
+- Shape, center, and rectangle corner arguments use image order: `(height, width)` and `(y, x)`
+- Triangle vertices use Cartesian order `(x, y)`, matching polygon coordinates
+
+## Project Layout
+
+- `analyzer.py`: public analysis workflow and metric selection
+- `validation.py`: public input normalization and analysis-option validation
+- `mask_ops.py`: component selection, contours, and `PreparedMask` crop/resize transforms with result-coordinate restoration
+- `metrics.py`: metric formulas and public result payloads
+- `fitting.py`: circle and ellipse fitting plus oriented bounding boxes
+- `wadell/roundness.py`: roundness options and the boundary-to-radius workflow
+- `wadell/boundary.py` and `smoothing.py`: closed boundary extraction and periodic smoothing
+- `wadell/discretize.py`: boundary approximation with `(x, y)` point arrays
+- `wadell/corner.py`: convex corner selection, circle fitting, and accepted corner radii
+- `utils/`: basic mask construction, parametric particle calibration and reporting, and visualization
+
+## Utilities
+
+Mask constructors:
+
+- `pm.utils.create_circle_mask(...)`
+- `pm.utils.create_ellipse_mask(...)`
+- `pm.utils.create_rectangle_mask(...)`
+- `pm.utils.create_square_mask(...)`
+- `pm.utils.create_triangle_mask(...)`
+- `pm.utils.create_pentagon_mask(...)`
+- `pm.utils.create_star_mask(...)`
+- `pm.utils.create_particle_mask(...)`
+
+For example, a triangle in a non-square image uses `(x, y)` vertices:
+
+```python
+mask = pm.utils.create_triangle_mask((20, 60), (30, 2), (40, 2), (30, 8))
+```
+
+`create_particle_mask` attempts to reach the requested roundness by calibrating
+surface roughness. Set `seed` for reproducible masks and `return_info=True` to
+receive `(mask, info)`. The report measures the returned mask, including any
+clipping at the image bounds; `target_met` compares its roundness error with
+`report_tol`. A zero-radius particle reports roundness `0.0`.
+
+Visualization:
+
+- `pm.utils.plot_analysis_results(mask, results)`
+
+## Changes in 0.2.0
+
+- Renamed the package from `partimorph` to `grainmorph`: install with `pip install grainmorph` and import with `import grainmorph`. The API is otherwise unchanged from 0.1.9.
+
+## Changes in 0.1.9
+
+- Wadell roundness is several times faster: corner circle fits are vectorized and boundary discretization does less per-step work. Results are unchanged.
+- `create_particle_mask` calibrates roughness with 12 bisection steps by default instead of 20, about 1.5x faster. Generated masks can differ slightly; on a 108-case grid the roundness error changed by at most 0.012 and its mean was unchanged.
+- Component selection, hole filling, and the Crofton perimeter now use OpenCV and NumPy, so `scipy` and `scikit-image` are no longer dependencies. Results are unchanged.
+
+## Changes in 0.1.8
+
+- Corrected the fitted ellipse overlay orientation for rotated particles.
+- Unified inscribed-circle fitting used by sphericity and Wadell roundness.
+- Simplified ellipse fitting and bounding-box coordinate transforms while preserving the public API and analysis results.
+
+## License
+
+MIT

grainmorph-0.2.0/README.md

@@ -0,0 +1,188 @@
+# GrainMorph
+
+GrainMorph analyzes a single 2D binary particle mask and returns geometric shape metrics.
+
+| Metric | Meaning |
+|---|---|
+| Wadell roundness | Corner curvature-based roundness |
+| 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 |
+
+Roundness, circularity, and sphericity are clipped to `0..1`. Aspect ratio is `>= 1`.
+
+## Installation
+
+GrainMorph requires Python `3.12+`.
+
+```bash
+pip install grainmorph
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the tests and code checks with the same Python environment:
+
+```bash
+python -m pytest -q
+python -m ruff check --isolated .
+python -m ruff format --isolated --check src tests
+```
+
+## Quick Start
+
+```python
+import grainmorph as pm
+
+mask = pm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = pm.analyze_mask(mask)
+
+if results is None:
+    raise ValueError("mask has no foreground pixels")
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+Visualize the results:
+
+```python
+pm.utils.plot_analysis_results(mask, results)
+```
+
+## API
+
+```python
+pm.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,
+)
+```
+
+| Parameter | Description |
+|---|---|
+| `mask` | 2D `numpy.ndarray` with `bool` or `{0, 1}` values |
+| `use_*` | Toggle individual metrics on/off |
+| `roundness_params` | Optional dict to override Wadell roundness parameters |
+| `eps` | Tolerance for geometric computations |
+| `target_dim` | Particle bounds larger than this are downscaled for speed, then coordinates are restored |
+
+`roundness_params` accepts these Wadell options. Defaults are defined in
+`wadell/roundness.py` and also apply to synthetic particle calibration:
+
+| Option | Default | Stage |
+|---|---|---|
+| `max_dev_thresh` | `0.3` | Boundary discretization |
+| `circle_fit_thresh` | `0.98` | Corner circle fitting |
+| `alpha_ratio` | `0.05` | Boundary smoothing |
+| `beta_ratio` | `0.001` | Boundary smoothing |
+
+Returns `None` for an empty mask. Otherwise, returns an `AnalysisResult` dict. Disabled metrics are omitted; enabled metrics are present and may be `None` when the geometry cannot be measured.
+
+## Result Shape
+
+```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,
+}
+```
+
+## Input Rules
+
+- `mask` must be a 2D `numpy.ndarray`
+- Allowed values are `bool` or numeric `{0, 1}`
+- Floating masks must not contain `NaN` or `inf`
+- Empty mask returns `None`
+- The largest 4-connected foreground component is selected and holes are filled
+- Surrounding zero padding does not change the measured shape
+- Downscaling is skipped if its output would have a one-pixel axis
+- Shape, center, and rectangle corner arguments use image order: `(height, width)` and `(y, x)`
+- Triangle vertices use Cartesian order `(x, y)`, matching polygon coordinates
+
+## Project Layout
+
+- `analyzer.py`: public analysis workflow and metric selection
+- `validation.py`: public input normalization and analysis-option validation
+- `mask_ops.py`: component selection, contours, and `PreparedMask` crop/resize transforms with result-coordinate restoration
+- `metrics.py`: metric formulas and public result payloads
+- `fitting.py`: circle and ellipse fitting plus oriented bounding boxes
+- `wadell/roundness.py`: roundness options and the boundary-to-radius workflow
+- `wadell/boundary.py` and `smoothing.py`: closed boundary extraction and periodic smoothing
+- `wadell/discretize.py`: boundary approximation with `(x, y)` point arrays
+- `wadell/corner.py`: convex corner selection, circle fitting, and accepted corner radii
+- `utils/`: basic mask construction, parametric particle calibration and reporting, and visualization
+
+## Utilities
+
+Mask constructors:
+
+- `pm.utils.create_circle_mask(...)`
+- `pm.utils.create_ellipse_mask(...)`
+- `pm.utils.create_rectangle_mask(...)`
+- `pm.utils.create_square_mask(...)`
+- `pm.utils.create_triangle_mask(...)`
+- `pm.utils.create_pentagon_mask(...)`
+- `pm.utils.create_star_mask(...)`
+- `pm.utils.create_particle_mask(...)`
+
+For example, a triangle in a non-square image uses `(x, y)` vertices:
+
+```python
+mask = pm.utils.create_triangle_mask((20, 60), (30, 2), (40, 2), (30, 8))
+```
+
+`create_particle_mask` attempts to reach the requested roundness by calibrating
+surface roughness. Set `seed` for reproducible masks and `return_info=True` to
+receive `(mask, info)`. The report measures the returned mask, including any
+clipping at the image bounds; `target_met` compares its roundness error with
+`report_tol`. A zero-radius particle reports roundness `0.0`.
+
+Visualization:
+
+- `pm.utils.plot_analysis_results(mask, results)`
+
+## Changes in 0.2.0
+
+- Renamed the package from `partimorph` to `grainmorph`: install with `pip install grainmorph` and import with `import grainmorph`. The API is otherwise unchanged from 0.1.9.
+
+## Changes in 0.1.9
+
+- Wadell roundness is several times faster: corner circle fits are vectorized and boundary discretization does less per-step work. Results are unchanged.
+- `create_particle_mask` calibrates roughness with 12 bisection steps by default instead of 20, about 1.5x faster. Generated masks can differ slightly; on a 108-case grid the roundness error changed by at most 0.012 and its mean was unchanged.
+- Component selection, hole filling, and the Crofton perimeter now use OpenCV and NumPy, so `scipy` and `scikit-image` are no longer dependencies. Results are unchanged.
+
+## Changes in 0.1.8
+
+- Corrected the fitted ellipse overlay orientation for rotated particles.
+- Unified inscribed-circle fitting used by sphericity and Wadell roundness.
+- Simplified ellipse fitting and bounding-box coordinate transforms while preserving the public API and analysis results.
+
+## License
+
+MIT

grainmorph-0.2.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grainmorph"
+version = "0.2.0"
+authors = [
+    { name = "GrainMorph Contributors" }
+]
+description = "Particle shape analysis and visualization library."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "numpy",
+    "opencv-python",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/phykn/grainmorph"
+Repository = "https://github.com/phykn/grainmorph"
+Issues = "https://github.com/phykn/grainmorph/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["grainmorph*"]

grainmorph-0.2.0/setup.cfg

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

grainmorph-0.2.0/src/grainmorph/__init__.py

@@ -0,0 +1,5 @@
+from . import utils
+from .analyzer import analyze_mask
+
+__version__ = "0.2.0"
+__all__ = ["analyze_mask", "utils"]

grainmorph-0.2.0/src/grainmorph/analyzer.py

@@ -0,0 +1,49 @@
+import numpy as np
+
+from .mask_ops import prepare_mask
+from .metrics import (
+    compute_aspect_ratio,
+    compute_circularity,
+    compute_roundness,
+    compute_sphericity,
+)
+from .schema import AnalysisResult
+from .validation import to_binary, validate_analysis_params
+
+
+def analyze_mask(
+    mask: np.ndarray,
+    *,
+    use_aspect_ratio: bool = True,
+    use_roundness: bool = True,
+    use_circularity: bool = True,
+    use_sphericity: bool = True,
+    roundness_params: dict[str, float] | None = None,
+    eps: float = 0.001,
+    target_dim: int = 384,
+) -> AnalysisResult | None:
+    eps, target_dim = validate_analysis_params(eps, target_dim)
+
+    mask_binary = to_binary(mask)
+    if not np.any(mask_binary):
+        return None
+
+    if not (use_aspect_ratio or use_roundness or use_circularity or use_sphericity):
+        return {}
+
+    prepared = prepare_mask(mask_binary, target_dim=target_dim)
+    final_mask = prepared.mask
+
+    results: AnalysisResult = {}
+    if use_aspect_ratio:
+        results["aspect_ratio"] = compute_aspect_ratio(final_mask, eps=eps)
+    if use_roundness:
+        results["roundness"] = compute_roundness(final_mask, **(roundness_params or {}))
+    if use_circularity:
+        results["circularity"] = compute_circularity(final_mask, eps=eps)
+    if use_sphericity:
+        results["sphericity"] = compute_sphericity(final_mask, eps=eps)
+
+    prepared.restore_results(results)
+
+    return results

grainmorph-0.2.0/src/grainmorph/fitting.py

@@ -0,0 +1,79 @@
+import cv2
+import numpy as np
+
+from .mask_ops import crop_mask, get_contours
+from .schema import Bbox, CircleData, EllipseData, Mask, Points
+
+
+def find_inscribed_circle(mask: Mask) -> CircleData | None:
+    cropped_mask, pad_x0, pad_y0 = crop_mask(mask, pad=1)
+
+    if cropped_mask.size == 0:
+        return None
+
+    distance_transform = cv2.distanceTransform(
+        cropped_mask.astype(np.uint8, copy=False), cv2.DIST_L2, cv2.DIST_MASK_PRECISE
+    )
+
+    max_idx = np.argmax(distance_transform)
+    crop_center_y, crop_center_x = np.unravel_index(max_idx, distance_transform.shape)
+
+    center_x = float(int(crop_center_x) + pad_x0)
+    center_y = float(int(crop_center_y) + pad_y0)
+    radius = float(distance_transform[crop_center_y, crop_center_x])
+
+    return {"x": center_x, "y": center_y, "r": radius}
+
+
+def find_enclosing_circle(mask: Mask) -> CircleData | None:
+    contours = get_contours(mask)
+    if not contours:
+        return None
+
+    points = np.concatenate(contours)
+    hull = cv2.convexHull(points)
+
+    (center_x, center_y), radius = cv2.minEnclosingCircle(hull)
+
+    return {"x": float(center_x), "y": float(center_y), "r": float(radius)}
+
+
+def fit_ellipse(mask: Mask) -> EllipseData | None:
+    contours = get_contours(mask)
+    if not contours:
+        return None
+
+    points: Points = np.concatenate(contours).reshape(-1, 2).astype(np.float32)
+    if len(points) < 5:
+        rect = cv2.minAreaRect(points)
+        (center_x, center_y), (width, height), angle = rect
+
+        if width <= 1e-06 or height <= 1e-06:
+            return None
+
+        bbox = cv2.boxPoints(rect).tolist()
+    else:
+        (center_x, center_y), (width, height), angle = cv2.fitEllipse(points)
+        bbox = _oriented_bbox_from_angle(points, angle)
+
+    return {
+        "major": float(max(width, height)),
+        "minor": float(min(width, height)),
+        "x": float(center_x),
+        "y": float(center_y),
+        "angle": float(angle),
+        "w": float(width),
+        "h": float(height),
+        "bbox": bbox,
+    }
+
+
+def _oriented_bbox_from_angle(points: Points, angle: float) -> Bbox:
+    radians = np.deg2rad(angle)
+    cos_a, sin_a = np.cos(radians), np.sin(radians)
+    axes = np.array([[cos_a, -sin_a], [sin_a, cos_a]])
+    projected = points @ axes
+    min_x, min_y = projected.min(axis=0)
+    max_x, max_y = projected.max(axis=0)
+    corners = np.array([[min_x, min_y], [max_x, min_y], [max_x, max_y], [min_x, max_y]])
+    return (corners @ axes.T).tolist()