deprojpy 0.1.0__py3-none-any.whl

deprojpy/__init__.py

@@ -0,0 +1,44 @@
+"""DeProj's height-map workflow for Python."""
+
+from .core import from_heightmap, from_labels
+from .heightmap import compute_curvatures, get_z, prepare_heightmap
+from .io import load_label_heightmap_pair, load_tiff_pair
+from .labels import labels_to_objects
+from .mask import mask_to_objects
+from .models import DeprojResult, Epicell
+from .plotting import save_plots
+from .surface_distance import (
+    SurfaceDistanceCalculator,
+    SurfaceGraph,
+    build_surface_graph,
+    cell_centers_xy_pixels,
+    heightmap_from_cell_boundaries,
+    sample_height_at_xy,
+    surface_graph_cell_distance,
+    surface_straight_cell_distance,
+    surface_straight_distance,
+)
+
+__all__ = [
+    "DeprojResult",
+    "Epicell",
+    "SurfaceDistanceCalculator",
+    "SurfaceGraph",
+    "build_surface_graph",
+    "cell_centers_xy_pixels",
+    "compute_curvatures",
+    "from_heightmap",
+    "from_labels",
+    "get_z",
+    "labels_to_objects",
+    "load_label_heightmap_pair",
+    "load_tiff_pair",
+    "mask_to_objects",
+    "prepare_heightmap",
+    "heightmap_from_cell_boundaries",
+    "sample_height_at_xy",
+    "save_plots",
+    "surface_graph_cell_distance",
+    "surface_straight_cell_distance",
+    "surface_straight_distance",
+]

deprojpy/cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .core import from_heightmap, from_labels
+from .io import load_label_heightmap_pair, load_tiff_pair
+from .plotting import save_plots
+
+
+def _add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--csv", type=Path)
+    parser.add_argument("--pixel-size", type=float, default=0.183)
+    parser.add_argument("--voxel-depth", type=float, default=1.0)
+    parser.add_argument("--units", default="µm")
+    parser.add_argument("--invert-z", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--plots", type=Path, metavar="DIR", help="save plot PNG files in DIR")
+
+
+def _print_summary(shape, result, frame) -> None:
+    print(f"Input shape: {shape}")
+    print(f"Retained cells: {len(result.epicells)}")
+    print(
+        "Junction graph: "
+        f"{result.junction_graph.number_of_nodes()} nodes, "
+        f"{result.junction_graph.number_of_edges()} edges"
+    )
+    print(f"DataFrame shape: {frame.shape}")
+    summary_columns = ["area", "perimeter", "eccentricity", "n_neighbors"]
+    print(frame[summary_columns].describe().to_string())
+
+
+def _finish(args, segmentation, heightmap, result, *, labels=None) -> None:
+    frame = result.to_dataframe()
+    _print_summary(segmentation.shape, result, frame)
+    if args.csv:
+        args.csv.parent.mkdir(parents=True, exist_ok=True)
+        result.to_csv(args.csv)
+        print(f"Wrote CSV: {args.csv}")
+    if args.plots:
+        paths = save_plots(
+            args.plots,
+            None if labels is not None else segmentation,
+            heightmap,
+            result,
+            frame,
+            labels=labels,
+        )
+        for path in paths:
+            print(f"Wrote plot: {path}")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run DeProj-compatible mask/label and height-map analysis"
+    )
+    subparsers = parser.add_subparsers(dest="mode")
+
+    binary = subparsers.add_parser("binary-mask", help="run the binary-ridge mask workflow")
+    binary.add_argument("mask")
+    binary.add_argument("heightmap")
+    _add_common_options(binary)
+
+    labels = subparsers.add_parser("labels", help="run the labeled-image workflow")
+    labels.add_argument("labels")
+    labels.add_argument("heightmap")
+    _add_common_options(labels)
+    labels.add_argument("--background", type=int, default=0)
+    labels.add_argument("--drop-border-cells", action=argparse.BooleanOptionalAction, default=True)
+    labels.add_argument("--junction-background", type=int)
+    labels.add_argument("--min-junction-labels", type=int, default=3)
+    labels.add_argument("--junction-merge-epsilon", type=float, default=0.0)
+    labels.add_argument("--preprocess-labels", action=argparse.BooleanOptionalAction, default=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    if argv is None:
+        argv = sys.argv[1:]
+    if argv and argv[0] not in {"binary-mask", "labels", "-h", "--help"}:
+        # Backward-compatible old form:
+        # deprojpy-smoke Segmentation-2.tif HeightMap-2.tif [options]
+        legacy = argparse.ArgumentParser(
+            description="Run DeProj-compatible binary mask and height-map analysis"
+        )
+        legacy.add_argument("mask")
+        legacy.add_argument("heightmap")
+        _add_common_options(legacy)
+        args = legacy.parse_args(argv)
+        args.mode = "binary-mask"
+    else:
+        parser = _build_parser()
+        args, unknown = parser.parse_known_args(argv)
+        if unknown:
+            parser.error(f"unrecognized arguments: {' '.join(unknown)}")
+
+    if args.mode == "labels":
+        labels, heightmap = load_label_heightmap_pair(
+            args.labels,
+            args.heightmap,
+            background=args.background,
+            preprocess_labels=args.preprocess_labels,
+        )
+        result = from_labels(
+            labels,
+            heightmap,
+            pixel_size=args.pixel_size,
+            voxel_depth=args.voxel_depth,
+            units=args.units,
+            invert_z=args.invert_z,
+            background=args.background,
+            drop_border_cells=args.drop_border_cells,
+            junction_background=args.junction_background,
+            min_junction_labels=args.min_junction_labels,
+            junction_merge_epsilon=args.junction_merge_epsilon,
+        )
+        _finish(args, labels, heightmap, result, labels=labels)
+    else:
+        mask, heightmap = load_tiff_pair(args.mask, args.heightmap)
+        result = from_heightmap(
+            mask,
+            heightmap,
+            pixel_size=args.pixel_size,
+            voxel_depth=args.voxel_depth,
+            units=args.units,
+            invert_z=args.invert_z,
+        )
+        _finish(args, mask, heightmap, result)
+
+
+if __name__ == "__main__":
+    main()

deprojpy/core.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from typing import Literal
+
+import networkx as nx
+import numpy as np
+
+from .geometry import (
+    BOUNDARY_SIMPLIFICATION_TOLERANCE_PX,
+    fit_ellipse_3d,
+    fit_plane,
+    polygon_metrics,
+    simplify_boundary_pixels,
+)
+from .heightmap import compute_curvatures, get_z, prepare_heightmap
+from .labels import labels_to_objects
+from .mask import mask_to_objects
+from .models import DeprojResult, Epicell
+from .objects import MaskObject
+
+
+def _validate_common_inputs(
+    segmentation: np.ndarray,
+    heightmap: np.ndarray,
+    *,
+    segmentation_name: str,
+    pixel_size: float,
+    voxel_depth: float,
+) -> tuple[np.ndarray, np.ndarray]:
+    segmentation = np.asarray(segmentation)
+    heightmap = np.asarray(heightmap)
+    if segmentation.ndim != 2 or heightmap.ndim != 2:
+        raise ValueError(
+            f"{segmentation_name} and heightmap must both be 2-D arrays; "
+            f"received shapes {segmentation.shape} and {heightmap.shape}"
+        )
+    if segmentation.shape != heightmap.shape:
+        raise ValueError(
+            f"{segmentation_name} and heightmap must have identical shapes; "
+            f"got {segmentation.shape} and {heightmap.shape}"
+        )
+    if not np.isfinite(pixel_size) or pixel_size <= 0:
+        raise ValueError("pixel_size must be a positive finite number")
+    if not np.isfinite(voxel_depth) or voxel_depth <= 0:
+        raise ValueError("voxel_depth must be a positive finite number")
+    return segmentation, heightmap
+
+
+def _from_objects_and_graph(
+    objects: list[MaskObject],
+    graph: nx.Graph,
+    heightmap: np.ndarray,
+    *,
+    source_shape: tuple[int, int],
+    pixel_size: float = 1.0,
+    voxel_depth: float = 1.0,
+    units: str = "pixels",
+    invert_z: bool = False,
+    inpaint_zeros: bool = True,
+    prune_zeros: bool = True,
+    cell_id_policy: Literal["sequential", "source_label"] = "sequential",
+) -> DeprojResult:
+    """Run shared height-map deprojection from extracted 2-D objects and graph."""
+    if not objects:
+        raise ValueError("object parsing found no retained cells")
+    median_area = np.median(
+        [polygon_metrics(np.c_[obj.boundary, np.zeros(len(obj.boundary))])[2] for obj in objects]
+    )
+    smooth_scale = 2.0 * np.sqrt(median_area) / np.pi
+    prepared = prepare_heightmap(
+        heightmap, voxel_depth, smooth_scale, invert_z, inpaint_zeros, prune_zeros
+    )
+    if not prune_zeros and not np.all(np.isfinite(prepared)):
+        raise ValueError(
+            "heightmap contains NaN or infinite values after preprocessing; "
+            "enable prune_zeros or provide a finite height map"
+        )
+
+    graph = graph.copy()
+    bad_junctions: set[int] = set()
+    for node_id, data in graph.nodes(data=True):
+        xy = np.asarray(data["centroid"], dtype=float) * pixel_size
+        z = get_z(xy[None, :], prepared, pixel_size)[0]
+        data["centroid"] = np.array([xy[0], xy[1], z])
+        if prune_zeros and (not np.isfinite(z) or z == 0):
+            bad_junctions.add(int(node_id))
+
+    curvatures = compute_curvatures(prepared, smooth_scale, pixel_size)
+    cells: list[Epicell] = []
+    for obj in objects:
+        if bad_junctions.intersection(map(int, obj.junction_ids)):
+            continue
+
+        # Simplify in pixel coordinates before height-map sampling or physical
+        # scaling. This keeps the tolerance independent of pixel_size and avoids
+        # carrying redundant contour vertices into the 3-D geometry path.
+        boundary_px = simplify_boundary_pixels(
+            np.asarray(obj.boundary, dtype=float),
+            tolerance_px=BOUNDARY_SIMPLIFICATION_TOLERANCE_PX,
+        )
+        xy = boundary_px * pixel_size
+        z = get_z(xy, prepared, pixel_size)
+        if prune_zeros and (not np.all(np.isfinite(z)) or np.any(z == 0)):
+            continue
+        boundary = np.c_[xy, z]
+        area, perimeter, area2d, perimeter2d = polygon_metrics(boundary)
+        rotation, euler = fit_plane(boundary)
+        ellipse, eccentricity, direction = fit_ellipse_3d(boundary, rotation)
+        center = boundary.mean(axis=0)
+        px = int(np.clip(np.rint(center[0] / pixel_size), 0, source_shape[1] - 1))
+        py = int(np.clip(np.rint(center[1] / pixel_size), 0, source_shape[0] - 1))
+        local_curvature = np.array([field[py, px] for field in curvatures])
+        source_label = obj.source_label
+        cell_id = (
+            int(source_label)
+            if cell_id_policy == "source_label" and source_label is not None
+            else len(cells) + 1
+        )
+        cells.append(
+            Epicell(
+                id=cell_id,
+                source_label=source_label,
+                boundary=boundary,
+                center=center,
+                junction_ids=obj.junction_ids.copy(),
+                n_neighbors=len(obj.junction_ids),
+                area=area,
+                perimeter=perimeter,
+                euler_angles=euler,
+                curvatures=local_curvature,
+                ellipse_fit=ellipse,
+                eccentricity=eccentricity,
+                proj_direction=direction,
+                uncorrected_area=area2d,
+                uncorrected_perimeter=perimeter2d,
+                area_error=area - area2d,
+                perimeter_error=perimeter - perimeter2d,
+            )
+        )
+    graph.remove_nodes_from(bad_junctions)
+    return DeprojResult(
+        cells,
+        graph,
+        units=units,
+        pixel_size=pixel_size,
+        voxel_depth=voxel_depth,
+        source_shape=source_shape,
+        prepared_heightmap=prepared,
+    )
+
+
+def from_heightmap(
+    mask: np.ndarray,
+    heightmap: np.ndarray,
+    pixel_size: float = 1.0,
+    voxel_depth: float = 1.0,
+    units: str = "pixels",
+    invert_z: bool = False,
+    inpaint_zeros: bool = True,
+    prune_zeros: bool = True,
+) -> DeprojResult:
+    """Deproject binary-ridge segmented cell contours onto a height-map surface."""
+    mask, heightmap = _validate_common_inputs(
+        mask,
+        heightmap,
+        segmentation_name="mask",
+        pixel_size=pixel_size,
+        voxel_depth=voxel_depth,
+    )
+    objects, graph = mask_to_objects(mask)
+    return _from_objects_and_graph(
+        objects,
+        graph,
+        heightmap,
+        source_shape=mask.shape,
+        pixel_size=pixel_size,
+        voxel_depth=voxel_depth,
+        units=units,
+        invert_z=invert_z,
+        inpaint_zeros=inpaint_zeros,
+        prune_zeros=prune_zeros,
+        cell_id_policy="sequential",
+    )
+
+
+def from_labels(
+    labels: np.ndarray,
+    heightmap: np.ndarray,
+    pixel_size: float = 1.0,
+    voxel_depth: float = 1.0,
+    units: str = "pixels",
+    invert_z: bool = False,
+    inpaint_zeros: bool = True,
+    prune_zeros: bool = True,
+    *,
+    background: int = 0,
+    drop_border_cells: bool = True,
+    min_junction_labels: int = 3,
+    junction_background: int | None = None,
+    junction_connectivity: int = 2,
+    junction_merge_epsilon: float = 0.0,
+) -> DeprojResult:
+    """Deproject labeled-image cell contours onto a height-map surface."""
+    labels, heightmap = _validate_common_inputs(
+        labels,
+        heightmap,
+        segmentation_name="labels",
+        pixel_size=pixel_size,
+        voxel_depth=voxel_depth,
+    )
+    objects, graph = labels_to_objects(
+        labels,
+        background=background,
+        drop_border_cells=drop_border_cells,
+        min_junction_labels=min_junction_labels,
+        junction_background=junction_background,
+        junction_connectivity=junction_connectivity,
+        junction_merge_epsilon=junction_merge_epsilon,
+    )
+    return _from_objects_and_graph(
+        objects,
+        graph,
+        heightmap,
+        source_shape=labels.shape,
+        pixel_size=pixel_size,
+        voxel_depth=voxel_depth,
+        units=units,
+        invert_z=invert_z,
+        inpaint_zeros=inpaint_zeros,
+        prune_zeros=prune_zeros,
+        cell_id_policy="source_label",
+    )

deprojpy/geometry.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+from skimage.measure import approximate_polygon
+
+# Boundary simplification happens in pixel coordinates so the tolerance is
+# independent of pixel_size. 0.5 px is intentionally conservative.
+BOUNDARY_SIMPLIFICATION_TOLERANCE_PX = 0.5
+
+
+def simplify_boundary_pixels(
+    boundary_xy: np.ndarray,
+    *,
+    tolerance_px: float = BOUNDARY_SIMPLIFICATION_TOLERANCE_PX,
+) -> np.ndarray:
+    """
+    Simplify an ordered cell boundary in pixel coordinates.
+
+    Parameters
+    ----------
+    boundary_xy : np.ndarray
+        Ordered ``(n, 2)`` boundary coordinates in geometric ``(x, y)`` pixel
+        order. The boundary may be open or explicitly closed.
+    tolerance_px : float, optional
+        Ramer-Douglas-Peucker distance tolerance in pixels. Larger values allow
+        stronger simplification. Default is the internal conservative tolerance
+        ``0.5`` px.
+
+    Returns
+    -------
+    np.ndarray
+        Simplified ordered boundary in ``(x, y)`` pixel coordinates. The output
+        follows the project convention of an open polygon: the first vertex is
+        not repeated at the end.
+    """
+    boundary = np.asarray(boundary_xy, dtype=float)
+    if boundary.ndim != 2 or boundary.shape[1] != 2:
+        raise ValueError("boundary_xy must have shape (n, 2)")
+    if not np.isfinite(tolerance_px) or tolerance_px < 0:
+        raise ValueError("tolerance_px must be a non-negative finite number")
+    if len(boundary) < 4:
+        return boundary.copy()
+
+    # approximate_polygon expects an explicit closed ring for polygonal
+    # boundaries. DeProjPy stores boundaries open and closes them implicitly in
+    # metric calculations, so strip the repeated endpoint after simplification.
+    closed = (
+        boundary
+        if np.allclose(boundary[0], boundary[-1])
+        else np.vstack([boundary, boundary[0]])
+    )
+    reduced = approximate_polygon(closed, tolerance=float(tolerance_px))
+    if len(reduced) > 1 and np.allclose(reduced[0], reduced[-1]):
+        reduced = reduced[:-1]
+
+    # Tiny or highly simplified contours can collapse below a usable polygon.
+    # In that case, keep the detailed boundary rather than fabricating geometry.
+    if len(reduced) < 4:
+        return boundary[:-1].copy() if np.allclose(boundary[0], boundary[-1]) else boundary.copy()
+    return np.asarray(reduced, dtype=float)
+
+
+def polygon_metrics(boundary: np.ndarray) -> tuple[float, float, float, float]:
+    """
+    Compute 3D and 2D area and perimeter of a polygon defined by a boundary using
+    the shoelace formula and cross product. The 3D area is calculated using the
+    cross product of adjacent edges, while the 2D area is computed using the
+    shoelace formula. The perimeter is calculated as the sum of distances between
+    consecutive points in both 3D and 2D.
+    """
+    centered = boundary - boundary.mean(axis=0)
+    nxt = np.roll(centered, -1, axis=0)
+    area3d = 0.5 * np.linalg.norm(np.cross(centered, nxt), axis=1).sum()
+    x, y = centered[:, 0], centered[:, 1]
+    area2d = 0.5 * abs(np.sum(x * np.roll(y, -1) - y * np.roll(x, -1)))
+    perimeter3d = np.linalg.norm(np.roll(centered, -1, axis=0) - centered, axis=1).sum()
+    perimeter2d = np.linalg.norm(
+        np.roll(centered[:, :2], -1, axis=0) - centered[:, :2], axis=1
+    ).sum()
+    return float(area3d), float(perimeter3d), float(area2d), float(perimeter2d)
+
+
+def fit_plane(boundary: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """ 
+    Fit a plane to the given boundary points.
+    """
+    centered = boundary - boundary.mean(axis=0)
+    _, _, rotation = np.linalg.svd(centered, full_matrices=False)
+    rotation = rotation.T
+    if np.linalg.det(rotation) < 0:
+        rotation[:, -1] *= -1
+    return rotation, rot_to_euler_zxz(rotation)
+
+
+def rot_to_euler_zxz(r: np.ndarray) -> np.ndarray:
+    """
+    Convert a rotation matrix to Euler angles in the ZXZ convention.
+    The function computes the Euler angles (alpha, beta, gamma) from the given rotation
+    matrix. The angles are returned in radians and represent rotations about the Z, X,
+    and Z axes, respectively.
+    """
+    beta = np.arccos(np.clip(r[2, 2], -1.0, 1.0))
+    if abs(np.sin(beta)) > 1e-12:
+        alpha = np.arctan2(r[0, 2], -r[1, 2])
+        gamma = np.arctan2(r[2, 0], r[2, 1])
+    elif r[2, 2] > 0:
+        alpha, gamma = np.arctan2(-r[0, 1], r[0, 0]), 0.0
+    else:
+        alpha, gamma = -np.arctan2(-r[0, 1], r[0, 0]), 0.0
+    return np.array([alpha, beta, gamma], dtype=float)
+
+
+def fit_ellipse_3d(boundary: np.ndarray, rotation: np.ndarray) -> tuple[np.ndarray, float, float]:
+    """Fit a moment-equivalent ellipse in the local best-fit plane."""
+    center = boundary.mean(axis=0)
+    local = (boundary - center) @ rotation
+    xy = local[:, :2]
+    try:
+        covariance = np.cov(xy, rowvar=False)
+        values, vectors = np.linalg.eigh(covariance)
+        order = np.argsort(values)[::-1]
+        values, vectors = values[order], vectors[:, order]
+        # For points sampled around an ellipse boundary, variance = axis^2 / 2.
+        axes = np.sqrt(np.maximum(2.0 * values, 0.0))
+        a, b = float(axes[0]), float(axes[1])
+        theta = float(np.arctan2(vectors[1, 0], vectors[0, 0]))
+        major_local = np.array([np.cos(theta), np.sin(theta), 0.0])
+        major_global = major_local @ rotation.T
+        direction = float(np.arctan2(major_global[1], major_global[0]))
+        eccentricity = float(np.sqrt(max(0.0, 1.0 - (b / a) ** 2))) if a > 0 else np.nan
+        return np.array([*center, a, b, theta]), eccentricity, direction
+    except np.linalg.LinAlgError:
+        warnings.warn("ellipse fit failed", RuntimeWarning, stacklevel=2)
+        return np.full(6, np.nan), np.nan, np.nan

deprojpy/heightmap.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage as ndi
+from skimage.restoration import inpaint
+
+
+def _nan_gaussian(image: np.ndarray, sigma: float) -> np.ndarray:
+    valid = np.isfinite(image)
+    values = ndi.gaussian_filter(np.where(valid, image, 0.0), sigma, mode="nearest")
+    weights = ndi.gaussian_filter(valid.astype(float), sigma, mode="nearest")
+    return np.divide(values, weights, out=np.full_like(values, np.nan), where=weights > 1e-12)
+
+
+def prepare_heightmap(
+    heightmap: np.ndarray,
+    voxel_depth: float = 1.0,
+    smooth_scale: float = -1.0,
+    invert_z: bool = False,
+    inpaint_zeros: bool = True,
+    prune_zeros: bool = True,
+) -> np.ndarray:
+    """Prepare a height map and return Z in physical units.
+
+    Zero regions are biharmonically interpolated when requested. Remaining
+    zeros become NaN when pruning is enabled. Inversion happens before unit
+    scaling, as in the MATLAB workflow.
+    """
+    h = np.asarray(heightmap, dtype=float).copy()
+    if h.ndim != 2:
+        raise ValueError(f"heightmap must be a 2-D array; received shape {h.shape}")
+    if h.size == 0:
+        raise ValueError("heightmap must not be empty")
+    if not np.isfinite(voxel_depth) or voxel_depth <= 0:
+        raise ValueError("voxel_depth must be a positive finite number")
+    if not np.any(np.isfinite(h)):
+        raise ValueError("heightmap must contain at least one finite value")
+    zero_mask = h == 0
+    if inpaint_zeros and zero_mask.any():
+        if zero_mask.all():
+            if prune_zeros:
+                raise ValueError(
+                    "heightmap contains only zeros, so no finite surface remains "
+                    "after zero pruning"
+                )
+        else:
+            h = inpaint.inpaint_biharmonic(h, zero_mask, channel_axis=None)
+    if prune_zeros:
+        h[h == 0] = np.nan
+    if smooth_scale > 0:
+        h = _nan_gaussian(h, smooth_scale)
+    if invert_z:
+        finite = h[np.isfinite(h)]
+        if finite.size:
+            h = finite.max() - h
+    h *= float(voxel_depth)
+    if not np.any(np.isfinite(h)):
+        raise ValueError(
+            "heightmap contains no finite values after preprocessing; check zero "
+            "handling and the input image"
+        )
+    return h
+
+
+def get_z(points_xy: np.ndarray, heightmap: np.ndarray, pixel_size: float) -> np.ndarray:
+    """Sample nearest height-map pixels for physical ``(x, y)`` points."""
+    points = np.asarray(points_xy, dtype=float)
+    # Coordinates in this port are zero-based; np.rint is nearest-pixel sampling.
+    pixels = np.rint(points / pixel_size).astype(int)
+    x = np.clip(pixels[:, 0], 0, heightmap.shape[1] - 1)
+    y = np.clip(pixels[:, 1], 0, heightmap.shape[0] - 1)
+    return np.asarray(heightmap[y, x], dtype=float)
+
+
+def compute_curvatures(
+    heightmap: np.ndarray,
+    object_scale: float | None = None,
+    pixel_size: float = 1.0,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Compute mean, Gaussian, and principal curvatures of z=f(x,y)."""
+    h = np.asarray(heightmap, dtype=float)
+    if object_scale is not None and np.isfinite(object_scale) and object_scale > 0:
+        h = _nan_gaussian(h, 3.0 * object_scale)
+    # np.gradient returns derivatives in axis order: y, x.
+    hy, hx = np.gradient(h, pixel_size, pixel_size)
+    hxy, hxx = np.gradient(hx, pixel_size, pixel_size)
+    hyy, _ = np.gradient(hy, pixel_size, pixel_size)
+    norm = 1.0 + hx * hx + hy * hy
+    gaussian = (hxx * hyy - hxy * hxy) / (norm * norm)
+    mean = ((1.0 + hx * hx) * hyy + (1.0 + hy * hy) * hxx - 2.0 * hx * hy * hxy) / (2.0 * norm**1.5)
+    discriminant = np.maximum(mean * mean - gaussian, 0.0)
+    root = np.sqrt(discriminant)
+    return mean, gaussian, mean + root, mean - root