partimorph 0.1.0__tar.gz

partimorph-0.1.0/LICENSE

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

partimorph-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: partimorph
+Version: 0.1.0
+Summary: Particle shape analysis and visualization library.
+Author: PartiMorph Contributors
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: opencv-python
+Requires-Dist: scikit-image
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# PartiMorph
+
+PartiMorph analyzes a 2D binary particle mask and returns:
+- Wadell roundness
+- ISO circularity
+- Riley sphericity
+- Aspect ratio
+
+## Install
+
+Python `3.12+`
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import partimorph as pm
+
+mask = pm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = pm.analyze_mask(mask)
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+## Input Rules
+
+- `mask` must be a 2D `numpy.ndarray`
+- Allowed values: `bool` or `{0, 1}`
+- Empty mask returns `None`
+
+## Main 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,
+)
+```
+
+Notes:
+- Large masks are downscaled automatically (`target_dim`) for speed.
+- `use_* = False` removes that metric from the output keys.
+
+## 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,
+}
+```
+
+## Utilities
+
+- `pm.utils.create_particle_mask(...)`: synthetic mask generator
+- `pm.utils.plot_analysis_results(mask, results)`: quick visualization

partimorph-0.1.0/README.md

@@ -0,0 +1,81 @@
+# PartiMorph
+
+PartiMorph analyzes a 2D binary particle mask and returns:
+- Wadell roundness
+- ISO circularity
+- Riley sphericity
+- Aspect ratio
+
+## Install
+
+Python `3.12+`
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import partimorph as pm
+
+mask = pm.utils.create_circle_mask((256, 256), (128, 128), 60)
+results = pm.analyze_mask(mask)
+
+print(results["roundness"]["val"])
+print(results["circularity"]["val"])
+print(results["sphericity"]["val"])
+print(results["aspect_ratio"]["val"])
+```
+
+## Input Rules
+
+- `mask` must be a 2D `numpy.ndarray`
+- Allowed values: `bool` or `{0, 1}`
+- Empty mask returns `None`
+
+## Main 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,
+)
+```
+
+Notes:
+- Large masks are downscaled automatically (`target_dim`) for speed.
+- `use_* = False` removes that metric from the output keys.
+
+## 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,
+}
+```
+
+## Utilities
+
+- `pm.utils.create_particle_mask(...)`: synthetic mask generator
+- `pm.utils.plot_analysis_results(mask, results)`: quick visualization

partimorph-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "partimorph"
+version = "0.1.0"
+authors = [
+    { name = "PartiMorph Contributors" }
+]
+description = "Particle shape analysis and visualization library."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "numpy",
+    "scipy",
+    "opencv-python",
+    "scikit-image",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["partimorph*"]

partimorph-0.1.0/setup.cfg

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

partimorph-0.1.0/src/partimorph/__init__.py

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

partimorph-0.1.0/src/partimorph/analyzer.py

@@ -0,0 +1,111 @@
+import cv2
+import numpy as np
+from scipy import ndimage
+from .schema import AnalysisResult, Mask
+from .metrics import (
+    compute_aspect_ratio,
+    compute_circularity,
+    compute_roundness,
+    compute_sphericity,
+)
+from .validation import to_binary
+
+
+def _preprocess_mask(mask: Mask, target_dim: int) -> tuple[Mask, bool]:
+    height, width = mask.shape[:2]
+    max_dimension = max(height, width)
+    is_resized = max_dimension > target_dim
+
+    if is_resized:
+        scale = target_dim / max_dimension
+        mask = cv2.resize(
+            mask.astype(np.uint8),
+            (0, 0),
+            fx=scale,
+            fy=scale,
+            interpolation=cv2.INTER_NEAREST,
+        )
+    mask_bool = mask.astype(bool)
+
+    labeled_mask, num_features = ndimage.label(mask_bool)
+    if num_features > 1:
+        sizes = np.bincount(labeled_mask.ravel())
+        sizes[0] = 0
+        mask_bool = labeled_mask == np.argmax(sizes)
+
+    return (ndimage.binary_fill_holes(mask_bool).astype(np.uint8), is_resized)
+
+
+def _rescale_results(
+    results: AnalysisResult,
+    *,
+    scale_x: float,
+    scale_y: float,
+) -> None:
+    mean_scale = (scale_x + scale_y) / 2.0
+
+    if results.get("sphericity"):
+        for key in ["inscribed", "enclosing"]:
+            circle_data = results["sphericity"][key]
+            circle_data["x"] = float(circle_data["x"] * scale_x)
+            circle_data["y"] = float(circle_data["y"] * scale_y)
+            circle_data["r"] = float(circle_data["r"] * mean_scale)
+
+    if results.get("aspect_ratio"):
+        ellipse = results["aspect_ratio"]["ellipse"]
+        ellipse["x"] = float(ellipse["x"] * scale_x)
+        ellipse["y"] = float(ellipse["y"] * scale_y)
+        ellipse["major"] = float(ellipse["major"] * mean_scale)
+        ellipse["minor"] = float(ellipse["minor"] * mean_scale)
+        ellipse["w"] = float(ellipse["w"] * scale_x)
+        ellipse["h"] = float(ellipse["h"] * scale_y)
+        if "bbox" in ellipse:
+            ellipse["bbox"] = [
+                [float(pt[0] * scale_x), float(pt[1] * scale_y)]
+                for pt in ellipse["bbox"]
+            ]
+
+
+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:
+    if eps <= 0:
+        raise ValueError("eps must be > 0.")
+    if target_dim <= 0:
+        raise ValueError("target_dim must be > 0.")
+
+    mask_binary = to_binary(mask)
+    if not np.any(mask_binary):
+        return None
+
+    original_height, original_width = mask_binary.shape
+    final_mask, is_resized = _preprocess_mask(mask_binary, target_dim=target_dim)
+
+    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)
+
+    if is_resized and results:
+        scale_x = original_width / final_mask.shape[1]
+        scale_y = original_height / final_mask.shape[0]
+        _rescale_results(
+            results,
+            scale_x=scale_x,
+            scale_y=scale_y,
+        )
+
+    return results

partimorph-0.1.0/src/partimorph/fitting.py

@@ -0,0 +1,140 @@
+import cv2
+import numpy as np
+from .schema import CircleData, EllipseData, Mask, Points
+from .misc import crop_mask, get_contours
+
+
+def _ellipse_payload(
+    *,
+    center_x: float,
+    center_y: float,
+    angle: float,
+    width: float,
+    height: float,
+    bbox: list[list[float]],
+) -> EllipseData:
+    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 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), 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:
+    if not np.any(mask):
+        return 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)
+
+    x = float(center_x)
+    y = float(center_y)
+    r = float(radius)
+
+    return {"x": x, "y": y, "r": r}
+
+
+def fit_ellipse(mask: Mask) -> EllipseData | None:
+    contours = get_contours(mask)
+    if not contours:
+        return None
+
+    points: Points = np.concatenate(contours).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
+
+        box = cv2.boxPoints(rect)
+        bbox = [[float(x), float(y)] for x, y in box]
+        return _ellipse_payload(
+            center_x=center_x,
+            center_y=center_y,
+            angle=angle,
+            width=width,
+            height=height,
+            bbox=bbox,
+        )
+
+    _, _, angle = cv2.fitEllipse(points)
+    radians = np.deg2rad(angle)
+    cos_a, sin_a = (np.cos(radians), np.sin(radians))
+
+    width_vector = np.array([cos_a, sin_a])
+    height_vector = np.array([-sin_a, cos_a])
+
+    width_projection = points @ width_vector
+    height_projection = points @ height_vector
+
+    min_width, max_width = (width_projection.min(), width_projection.max())
+    min_height, max_height = (height_projection.min(), height_projection.max())
+
+    tight_width = max_width - min_width
+    tight_height = max_height - min_height
+
+    mid_width = (max_width + min_width) / 2.0
+    mid_height = (max_height + min_height) / 2.0
+
+    center_x = mid_width * width_vector[0] + mid_height * height_vector[0]
+    center_y = mid_width * width_vector[1] + mid_height * height_vector[1]
+
+    bbox = [
+        [
+            float(min_width * width_vector[0] + min_height * height_vector[0]),
+            float(min_width * width_vector[1] + min_height * height_vector[1]),
+        ],
+        [
+            float(max_width * width_vector[0] + min_height * height_vector[0]),
+            float(max_width * width_vector[1] + min_height * height_vector[1]),
+        ],
+        [
+            float(max_width * width_vector[0] + max_height * height_vector[0]),
+            float(max_width * width_vector[1] + max_height * height_vector[1]),
+        ],
+        [
+            float(min_width * width_vector[0] + max_height * height_vector[0]),
+            float(min_width * width_vector[1] + max_height * height_vector[1]),
+        ],
+    ]
+
+    return _ellipse_payload(
+        center_x=center_x,
+        center_y=center_y,
+        angle=angle,
+        width=tight_width,
+        height=tight_height,
+        bbox=bbox,
+    )

partimorph-0.1.0/src/partimorph/metrics.py

@@ -0,0 +1,105 @@
+import numpy as np
+import skimage.measure
+from .fitting import (
+    find_enclosing_circle,
+    find_inscribed_circle,
+    fit_ellipse,
+)
+from .wadell import compute_roundness as compute_roundness_wadell
+from .misc import crop_mask
+from .validation import to_binary
+from .schema import (
+    AspectRatioResult,
+    CircularityResult,
+    Mask,
+    RoundnessResult,
+    SphericityResult,
+)
+
+
+def compute_roundness(
+    mask: np.ndarray,
+    *,
+    max_dev_thresh: float = 0.3,
+    circle_fit_thresh: float = 0.98,
+    alpha_ratio: float = 0.05,
+    beta_ratio: float = 0.001,
+) -> RoundnessResult | None:
+    mask_binary: Mask = to_binary(mask)
+
+    value = compute_roundness_wadell(
+        mask_binary,
+        max_dev_thresh=max_dev_thresh,
+        circle_fit_thresh=circle_fit_thresh,
+        alpha_ratio=alpha_ratio,
+        beta_ratio=beta_ratio,
+    )
+
+    if value is None:
+        return None
+
+    value = float(np.clip(value, 0.0, 1.0))
+
+    return {"val": value}
+
+
+def compute_circularity(
+    mask: np.ndarray, *, eps: float = 0.001
+) -> CircularityResult | None:
+    mask_binary: Mask = to_binary(mask)
+
+    cropped_mask, _, _ = crop_mask(mask_binary, pad=1)
+
+    if cropped_mask.size == 0:
+        return None
+
+    perimeter = skimage.measure.perimeter_crofton(cropped_mask, 4)
+
+    if perimeter < eps:
+        return None
+
+    area = float(np.count_nonzero(mask_binary))
+    value = 4.0 * np.pi * area / perimeter**2
+    value = float(np.clip(value, 0.0, 1.0))
+
+    return {"val": value}
+
+
+def compute_sphericity(
+    mask: np.ndarray, *, eps: float = 0.001
+) -> SphericityResult | None:
+    mask_binary: Mask = to_binary(mask)
+
+    inscribed = find_inscribed_circle(mask_binary)
+    enclosing = find_enclosing_circle(mask_binary)
+
+    if inscribed is None or enclosing is None:
+        return None
+
+    inscribed_radius = inscribed["r"]
+    enclosing_radius = enclosing["r"]
+
+    if enclosing_radius < eps:
+        return None
+
+    value = float(np.clip(inscribed_radius / enclosing_radius, 0.0, 1.0))
+
+    return {"val": value, "inscribed": inscribed, "enclosing": enclosing}
+
+
+def compute_aspect_ratio(
+    mask: np.ndarray, *, eps: float = 0.001
+) -> AspectRatioResult | None:
+    mask_binary: Mask = to_binary(mask)
+
+    ellipse_data = fit_ellipse(mask_binary)
+
+    if ellipse_data is None:
+        return None
+
+    if ellipse_data["minor"] < eps:
+        return None
+
+    value = ellipse_data["major"] / ellipse_data["minor"]
+
+    return {"val": value, "ellipse": ellipse_data}

partimorph-0.1.0/src/partimorph/misc.py

@@ -0,0 +1,41 @@
+import cv2
+import numpy as np
+
+
+def get_contours(mask: np.ndarray) -> tuple[np.ndarray, ...]:
+    cropped_mask, offset_x, offset_y = crop_mask(mask, pad=1)
+
+    if cropped_mask.size == 0:
+        return ()
+
+    if cropped_mask.dtype != np.uint8:
+        cropped_mask = cropped_mask.astype(np.uint8)
+
+    contours, _ = cv2.findContours(
+        cropped_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+    )
+
+    offset = np.array([[[offset_x, offset_y]]], dtype=np.int32)
+    return tuple(contour + offset for contour in contours)
+
+
+def crop_mask(mask: np.ndarray, pad: int = 1) -> tuple[np.ndarray, int, int]:
+    if mask.dtype != np.uint8:
+        binary_mask_uint8 = mask.astype(np.uint8)
+    else:
+        binary_mask_uint8 = mask
+
+    x_min, y_min, width, height = cv2.boundingRect(binary_mask_uint8)
+
+    if width == 0 or height == 0:
+        return (np.zeros((0, 0), dtype=mask.dtype), 0, 0)
+
+    cropped = mask[y_min : y_min + height, x_min : x_min + width]
+
+    if pad > 0:
+        cropped = np.pad(cropped, pad_width=pad, mode="constant", constant_values=0)
+
+    offset_y = y_min - pad
+    offset_x = x_min - pad
+
+    return (cropped, offset_x, offset_y)

partimorph-0.1.0/src/partimorph/schema.py

@@ -0,0 +1,52 @@
+import numpy as np
+from typing import Annotated, TypeAlias, TypedDict
+
+
+Bbox: TypeAlias = list[list[float]]
+Mask: TypeAlias = Annotated[np.ndarray, "shape=(H, W), dtype=uint8"]
+Coordinates: TypeAlias = Annotated[np.ndarray, "shape=(N, 2), dtype=float64"]
+Boundary: TypeAlias = Annotated[np.ndarray, "shape=(N, 2), dtype=int32"]
+Points: TypeAlias = Annotated[np.ndarray, "shape=(N, 2), dtype=float32"]
+
+
+class CircleData(TypedDict):
+    x: float
+    y: float
+    r: float
+
+
+class EllipseData(TypedDict):
+    major: float
+    minor: float
+    x: float
+    y: float
+    angle: float
+    w: float
+    h: float
+    bbox: Bbox
+
+
+class RoundnessResult(TypedDict):
+    val: float
+
+
+class CircularityResult(TypedDict):
+    val: float
+
+
+class SphericityResult(TypedDict):
+    val: float
+    inscribed: CircleData
+    enclosing: CircleData
+
+
+class AspectRatioResult(TypedDict):
+    val: float
+    ellipse: EllipseData
+
+
+class AnalysisResult(TypedDict, total=False):
+    roundness: RoundnessResult | None
+    circularity: CircularityResult | None
+    sphericity: SphericityResult | None
+    aspect_ratio: AspectRatioResult | None