grainmorph 0.2.0__py3-none-any.whl

grainmorph/__init__.py

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

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/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()

grainmorph/mask_ops.py

@@ -0,0 +1,128 @@
+from dataclasses import dataclass
+
+import cv2
+import numpy as np
+
+from .schema import AnalysisResult, Mask
+
+
+@dataclass(frozen=True)
+class PreparedMask:
+    mask: Mask
+    offset_x: float
+    offset_y: float
+    scale: float
+
+    def restore_results(self, results: AnalysisResult) -> None:
+        sphericity = results.get("sphericity")
+        if sphericity:
+            for key in ("inscribed", "enclosing"):
+                circle = sphericity[key]
+                circle["x"] = float(circle["x"] * self.scale + self.offset_x)
+                circle["y"] = float(circle["y"] * self.scale + self.offset_y)
+                circle["r"] = float(circle["r"] * self.scale)
+
+        aspect_ratio = results.get("aspect_ratio")
+        if aspect_ratio:
+            ellipse = aspect_ratio["ellipse"]
+            ellipse["x"] = float(ellipse["x"] * self.scale + self.offset_x)
+            ellipse["y"] = float(ellipse["y"] * self.scale + self.offset_y)
+            for key in ("major", "minor", "w", "h"):
+                ellipse[key] = float(ellipse[key] * self.scale)
+            ellipse["bbox"] = [
+                [
+                    float(x * self.scale + self.offset_x),
+                    float(y * self.scale + self.offset_y),
+                ]
+                for x, y in ellipse["bbox"]
+            ]
+
+
+def prepare_mask(mask: Mask, target_dim: int) -> PreparedMask:
+    cropped, crop_x, crop_y = crop_mask(mask, pad=0)
+
+    num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(
+        cropped, connectivity=4
+    )
+    if num_labels > 2:
+        largest = 1 + np.argmax(stats[1:, cv2.CC_STAT_AREA])
+        cropped = (labels == largest).astype(np.uint8)
+
+    # Background 4-connected to the padded border stays empty; the rest are holes.
+    flooded = np.pad(cropped, 1)
+    cv2.floodFill(flooded, None, (0, 0), 2, flags=4)
+    filled_mask = (flooded[1:-1, 1:-1] != 2).astype(np.uint8)
+    component, component_x, component_y = crop_mask(filled_mask, pad=0)
+
+    source_height, source_width = component.shape
+    scale = 1.0
+    if max(source_height, source_width) > target_dim:
+        resize_scale = target_dim / max(source_height, source_width)
+        target_width = max(1, round(source_width * resize_scale))
+        target_height = max(1, round(source_height * resize_scale))
+        if target_width > 1 and target_height > 1:
+            translation = (resize_scale - 1.0) / 2.0
+            transform = np.array(
+                [
+                    [resize_scale, 0.0, translation],
+                    [0.0, resize_scale, translation],
+                ],
+                dtype=np.float64,
+            )
+            component = cv2.warpAffine(
+                component,
+                transform,
+                (target_width, target_height),
+                flags=cv2.INTER_NEAREST,
+            )
+            scale = 1.0 / resize_scale
+
+    # OpenCV maps pixel centers, so the half-pixel term is part of the inverse map.
+    offset_x = crop_x + component_x + (scale - 1.0) / 2.0
+    offset_y = crop_y + component_y + (scale - 1.0) / 2.0
+
+    return PreparedMask(
+        mask=component,
+        offset_x=float(offset_x),
+        offset_y=float(offset_y),
+        scale=float(scale),
+    )
+
+
+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)

grainmorph/metrics.py

@@ -0,0 +1,112 @@
+import numpy as np
+
+from .fitting import (
+    find_enclosing_circle,
+    find_inscribed_circle,
+    fit_ellipse,
+)
+from .mask_ops import crop_mask
+from .schema import (
+    AspectRatioResult,
+    CircularityResult,
+    Mask,
+    RoundnessResult,
+    SphericityResult,
+)
+from .wadell import compute_roundness as compute_wadell_roundness
+
+# Four-direction Crofton weights indexed by 2x2 pixel pattern, matching
+# skimage.measure.perimeter_crofton(image, directions=4).
+_CROFTON_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,
+    ]
+)
+
+
+def compute_roundness(mask: Mask, **params: float) -> RoundnessResult | None:
+    value = compute_wadell_roundness(mask, **params)
+
+    if value is None:
+        return None
+
+    value = float(np.clip(value, 0.0, 1.0))
+
+    return {"val": value}
+
+
+def compute_circularity(mask: Mask, *, eps: float = 0.001) -> CircularityResult | None:
+    cropped_mask, _, _ = crop_mask(mask, pad=1)
+
+    if cropped_mask.size == 0:
+        return None
+
+    perimeter = _crofton_perimeter(cropped_mask)
+
+    if perimeter < eps:
+        return None
+
+    area = float(np.count_nonzero(mask))
+    value = 4.0 * np.pi * area / perimeter**2
+    value = float(np.clip(value, 0.0, 1.0))
+
+    return {"val": value}
+
+
+def _crofton_perimeter(mask: Mask) -> float:
+    padded = np.pad((mask > 0).astype(np.uint8), ((2, 1), (2, 1)))
+    patterns = (
+        padded[1:, 1:]
+        + 2 * padded[:-1, 1:]
+        + 4 * padded[1:, :-1]
+        + 8 * padded[:-1, :-1]
+    )
+    counts = np.bincount(patterns.ravel(), minlength=16)
+    return float(_CROFTON_WEIGHTS @ counts)
+
+
+def compute_sphericity(mask: Mask, *, eps: float = 0.001) -> SphericityResult | None:
+    inscribed = find_inscribed_circle(mask)
+    enclosing = find_enclosing_circle(mask)
+
+    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: Mask, *, eps: float = 0.001) -> AspectRatioResult | None:
+    ellipse_data = fit_ellipse(mask)
+
+    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}

grainmorph/schema.py

@@ -0,0 +1,50 @@
+from typing import Annotated, TypeAlias, TypedDict
+
+import numpy as np
+
+Bbox: TypeAlias = list[list[float]]
+Mask: TypeAlias = Annotated[np.ndarray, "shape=(H, W), dtype=uint8"]
+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

grainmorph/utils/__init__.py

@@ -0,0 +1,29 @@
+from .create_mask import (
+    create_circle_mask,
+    create_ellipse_mask,
+    create_pentagon_mask,
+    create_rectangle_mask,
+    create_square_mask,
+    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",
+    "create_ellipse_mask",
+    "create_particle_mask",
+    "create_pentagon_mask",
+    "create_rectangle_mask",
+    "create_square_mask",
+    "create_star_mask",
+    "create_triangle_mask",
+    "plot_analysis_results",
+]

grainmorph/utils/create_mask.py

@@ -0,0 +1,115 @@
+import numpy as np
+
+from .geometry import create_poly_mask, polar_vertices
+
+
+def _polygon_mask(shape: tuple[int, int], vertices: np.ndarray) -> np.ndarray:
+    return create_poly_mask(shape, vertices).astype(bool)
+
+
+def create_circle_mask(
+    shape: tuple[int, int], center: tuple[int, int], radius: float
+) -> np.ndarray:
+    if not np.isfinite(radius) or radius < 0:
+        raise ValueError("radius must be finite and >= 0.")
+
+    h, w = shape
+    y, x = np.ogrid[:h, :w]
+    cy, cx = center
+
+    return (x - cx) ** 2 + (y - cy) ** 2 <= radius**2
+
+
+def create_ellipse_mask(
+    shape: tuple[int, int], center: tuple[int, int], radius_x: float, radius_y: float
+) -> np.ndarray:
+    if (
+        not np.isfinite(radius_x)
+        or not np.isfinite(radius_y)
+        or radius_x <= 0
+        or radius_y <= 0
+    ):
+        raise ValueError("radius_x and radius_y must be finite and > 0.")
+
+    h, w = shape
+    y, x = np.ogrid[:h, :w]
+    cy, cx = center
+
+    return ((x - cx) / radius_x) ** 2 + ((y - cy) / radius_y) ** 2 <= 1.0
+
+
+def create_rectangle_mask(
+    shape: tuple[int, int], top_left: tuple[int, int], bottom_right: tuple[int, int]
+) -> np.ndarray:
+    h, w = shape
+    y1, x1 = top_left
+    y2, x2 = bottom_right
+
+    if y1 >= y2 or x1 >= x2:
+        raise ValueError("top_left must be strictly above-left of bottom_right.")
+
+    if y1 < 0 or x1 < 0 or y2 > h or x2 > w:
+        raise ValueError("rectangle coordinates must be within mask bounds.")
+
+    res = np.zeros(shape, dtype=bool)
+    res[y1:y2, x1:x2] = True
+    return res
+
+
+def create_square_mask(
+    shape: tuple[int, int], top_left: tuple[int, int], size: int
+) -> np.ndarray:
+    if size <= 0:
+        raise ValueError("size must be > 0.")
+
+    return create_rectangle_mask(
+        shape=shape,
+        top_left=top_left,
+        bottom_right=(top_left[0] + size, top_left[1] + size),
+    )
+
+
+def create_triangle_mask(
+    shape: tuple[int, int],
+    v1: tuple[int, int],
+    v2: tuple[int, int],
+    v3: tuple[int, int],
+) -> np.ndarray:
+    """Create a triangle from (x, y) vertices in a (height, width) image."""
+    vertices = np.array([v1, v2, v3])
+    return _polygon_mask(shape, vertices)
+
+
+def create_pentagon_mask(
+    shape: tuple[int, int], center: tuple[int, int], radius: float
+) -> np.ndarray:
+    if not np.isfinite(radius) or radius <= 0:
+        raise ValueError("radius must be finite and > 0.")
+
+    angles = np.linspace(0, 2 * np.pi, 5, endpoint=False) - np.pi / 2
+    vertices = polar_vertices(center=center, radii=radius, angles=angles)
+    return _polygon_mask(shape, vertices)
+
+
+def create_star_mask(
+    shape: tuple[int, int],
+    center: tuple[int, int],
+    outer_radius: float,
+    inner_radius: float,
+    num_points: int = 5,
+) -> np.ndarray:
+    if not np.isfinite(outer_radius) or outer_radius <= 0:
+        raise ValueError("outer_radius must be finite and > 0.")
+    if not np.isfinite(inner_radius) or inner_radius <= 0:
+        raise ValueError("inner_radius must be finite and > 0.")
+    if not isinstance(num_points, (int, np.integer)):
+        raise TypeError("num_points must be an integer.")
+    if num_points < 2:
+        raise ValueError("num_points must be >= 2.")
+
+    angles = np.linspace(0, 2 * np.pi, 2 * num_points, endpoint=False) - np.pi / 2
+    radii = np.ones_like(angles) * outer_radius
+    radii[1::2] = inner_radius
+
+    vertices = polar_vertices(center=center, radii=radii, angles=angles)
+    return _polygon_mask(shape, vertices)

grainmorph/utils/geometry.py

@@ -0,0 +1,23 @@
+import cv2
+import numpy as np
+
+
+def create_poly_mask(shape: tuple[int, int], vertices: np.ndarray) -> np.ndarray:
+    mask = np.zeros(shape, dtype=np.uint8)
+    pts = np.asarray(vertices, dtype=np.int32).reshape(-1, 1, 2)
+
+    cv2.fillPoly(mask, [pts], 1)
+    return mask
+
+
+def polar_vertices(
+    center: tuple[float, float],
+    radii: float | np.ndarray,
+    angles: np.ndarray,
+) -> np.ndarray:
+    cy, cx = center
+    radii_arr = np.asarray(radii, dtype=float)
+    return np.stack(
+        [cx + radii_arr * np.cos(angles), cy + radii_arr * np.sin(angles)],
+        axis=1,
+    )