landmarkdiff 0.2.3__py3-none-any.whl

landmarkdiff/masking.py

@@ -0,0 +1,316 @@
+"""Surgical mask generation with morphological dilation and Gaussian feathering.
+
+Procedural masks (not SAM2) -- deterministic, no model dependency.
+Feathered boundaries prevent visible seams in ControlNet inpainting.
+Supports clinical edge cases (vitiligo preservation, keloid softening).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import cv2
+import numpy as np
+
+from landmarkdiff.landmarks import FaceLandmarks
+
+if TYPE_CHECKING:
+    from landmarkdiff.clinical import ClinicalFlags
+
+# Boundary noise parameters for seam prevention
+_BOUNDARY_KERNEL_SIZE = 5  # px, morphological kernel for boundary extraction
+_BOUNDARY_NOISE_MAX = 4  # max random noise offset in pixels
+_BOUNDARY_NOISE_SCALE = 64  # intensity multiplier for noise mask
+_GAUSSIAN_KERNEL_FACTOR = 6  # sigma multiplier for Gaussian kernel size
+
+# Procedure-specific mask parameters
+MASK_CONFIG: dict[str, dict] = {
+    "rhinoplasty": {
+        "landmark_indices": [
+            1,
+            2,
+            4,
+            5,
+            6,
+            19,
+            94,
+            141,
+            168,
+            195,
+            197,
+            236,
+            240,
+            274,
+            275,
+            278,
+            279,
+            294,
+            326,
+            327,
+            360,
+            363,
+            370,
+            456,
+            460,
+        ],
+        "dilation_px": 30,
+        "feather_sigma": 15.0,
+    },
+    "blepharoplasty": {
+        "landmark_indices": [
+            33,
+            7,
+            163,
+            144,
+            145,
+            153,
+            154,
+            155,
+            157,
+            158,
+            159,
+            160,
+            161,
+            246,
+            362,
+            382,
+            381,
+            380,
+            374,
+            373,
+            390,
+            249,
+            263,
+            466,
+            388,
+            387,
+            386,
+            385,
+            384,
+            398,
+        ],
+        "dilation_px": 15,
+        "feather_sigma": 10.0,
+    },
+    "rhytidectomy": {
+        "landmark_indices": [
+            10,
+            21,
+            54,
+            58,
+            67,
+            93,
+            103,
+            109,
+            127,
+            132,
+            136,
+            150,
+            162,
+            172,
+            176,
+            187,
+            207,
+            213,
+            234,
+            284,
+            297,
+            323,
+            332,
+            338,
+            356,
+            361,
+            365,
+            379,
+            389,
+            397,
+            400,
+            427,
+            454,
+        ],
+        "dilation_px": 40,
+        "feather_sigma": 20.0,
+    },
+    "orthognathic": {
+        "landmark_indices": [
+            0,
+            17,
+            18,
+            36,
+            37,
+            39,
+            40,
+            57,
+            61,
+            78,
+            80,
+            81,
+            82,
+            84,
+            87,
+            88,
+            91,
+            95,
+            146,
+            167,
+            169,
+            170,
+            175,
+            181,
+            191,
+            200,
+            201,
+            202,
+            204,
+            208,
+            211,
+            212,
+            214,
+        ],
+        "dilation_px": 35,
+        "feather_sigma": 18.0,
+    },
+    "brow_lift": {
+        "landmark_indices": [
+            70,
+            63,
+            105,
+            66,
+            107,  # left brow
+            300,
+            293,
+            334,
+            296,
+            336,  # right brow
+            9,
+            8,
+            10,  # forehead midline
+            109,
+            67,
+            103,  # upper face left
+            338,
+            297,
+            332,  # upper face right
+        ],
+        "dilation_px": 25,
+        "feather_sigma": 15.0,
+    },
+    "mentoplasty": {
+        "landmark_indices": [
+            148,
+            149,
+            150,
+            152,
+            171,
+            175,
+            176,
+            377,
+        ],
+        "dilation_px": 25,
+        "feather_sigma": 12.0,
+    },
+}
+
+
+def generate_surgical_mask(
+    face: FaceLandmarks,
+    procedure: str,
+    width: int | None = None,
+    height: int | None = None,
+    clinical_flags: ClinicalFlags | None = None,
+    image: np.ndarray | None = None,
+) -> np.ndarray:
+    """Generate a feathered surgical mask for a procedure.
+
+    Pipeline:
+    1. Create convex hull from procedure-specific landmarks
+    2. Morphological dilation by N pixels
+    3. Gaussian feathering for smooth alpha gradient
+    4. Add Perlin-style noise at boundary to prevent visible seams
+
+    Args:
+        face: Extracted facial landmarks.
+        procedure: Procedure name (e.g. "rhinoplasty").
+        width: Mask width (defaults to face.image_width).
+        height: Mask height (defaults to face.image_height).
+        clinical_flags: Optional clinical edge-case flags (vitiligo, keloid).
+        image: Original BGR image, required when clinical_flags.vitiligo is set.
+
+    Returns:
+        Float32 mask array [0.0-1.0] with feathered boundaries.
+    """
+    if procedure not in MASK_CONFIG:
+        raise ValueError(f"Unknown procedure: {procedure}. Choose from {list(MASK_CONFIG)}")
+
+    config = MASK_CONFIG[procedure]
+    w = width or face.image_width
+    h = height or face.image_height
+
+    # Get pixel coordinates of procedure landmarks
+    coords = face.landmarks[:, :2].copy()
+    coords[:, 0] *= w
+    coords[:, 1] *= h
+    pts = coords[config["landmark_indices"]].astype(np.int32)
+
+    # Create binary mask from convex hull
+    binary = np.zeros((h, w), dtype=np.uint8)
+    hull = cv2.convexHull(pts)
+    cv2.fillConvexPoly(binary, hull, 255)
+
+    # Morphological dilation
+    dilation = config["dilation_px"]
+    kernel = cv2.getStructuringElement(
+        cv2.MORPH_ELLIPSE,
+        (2 * dilation + 1, 2 * dilation + 1),
+    )
+    dilated = cv2.dilate(binary, kernel)
+
+    # Add slight boundary noise to prevent clean-edge seams
+    # (Spec: Perlin noise 2-4px on boundary before feathering)
+    boundary = cv2.subtract(
+        cv2.dilate(dilated, np.ones((_BOUNDARY_KERNEL_SIZE, _BOUNDARY_KERNEL_SIZE), np.uint8)),
+        cv2.erode(dilated, np.ones((_BOUNDARY_KERNEL_SIZE, _BOUNDARY_KERNEL_SIZE), np.uint8)),
+    )
+    noise = np.random.default_rng().integers(0, _BOUNDARY_NOISE_MAX, size=(h, w), dtype=np.uint8)
+    noise_boundary = cv2.bitwise_and(boundary, noise.astype(np.uint8) * _BOUNDARY_NOISE_SCALE)
+    dilated = cv2.add(dilated, noise_boundary)
+    dilated = np.clip(dilated, 0, 255).astype(np.uint8)
+
+    # Gaussian feathering
+    sigma = config["feather_sigma"]
+    ksize = int(_GAUSSIAN_KERNEL_FACTOR * sigma) | 1  # ensure odd
+    feathered = cv2.GaussianBlur(
+        dilated.astype(np.float32) / 255.0,
+        (ksize, ksize),
+        sigma,
+    )
+
+    mask = np.clip(feathered, 0.0, 1.0)
+
+    # Clinical edge case adjustments
+    if clinical_flags is not None:
+        # Vitiligo: reduce mask over depigmented patches to preserve them
+        if clinical_flags.vitiligo and image is not None:
+            from landmarkdiff.clinical import adjust_mask_for_vitiligo, detect_vitiligo_patches
+
+            patches = detect_vitiligo_patches(image, face)
+            mask = adjust_mask_for_vitiligo(mask, patches)
+
+        # Keloid: soften transitions in keloid-prone regions
+        if clinical_flags.keloid_prone and clinical_flags.keloid_regions:
+            from landmarkdiff.clinical import adjust_mask_for_keloid, get_keloid_exclusion_mask
+
+            keloid_mask = get_keloid_exclusion_mask(
+                face,
+                clinical_flags.keloid_regions,
+                w,
+                h,
+            )
+            mask = adjust_mask_for_keloid(mask, keloid_mask)
+
+    return mask
+
+
+def mask_to_3channel(mask: np.ndarray) -> np.ndarray:
+    """Convert single-channel mask to 3-channel for compositing."""
+    return np.stack([mask, mask, mask], axis=-1)

landmarkdiff/metrics_agg.py

@@ -0,0 +1,313 @@
+"""Metrics aggregation across checkpoints, experiments, and procedures.
+
+Collects evaluation results from multiple sources and computes aggregate
+statistics, confidence intervals, and significance tests for paper reporting.
+
+Usage:
+    from landmarkdiff.metrics_agg import MetricsAggregator
+
+    agg = MetricsAggregator()
+    agg.add("baseline", "rhinoplasty", {"ssim": 0.82, "lpips": 0.18})
+    agg.add("ours", "rhinoplasty", {"ssim": 0.91, "lpips": 0.09})
+    print(agg.summary_table())
+    print(agg.improvement_over("baseline"))
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MetricRecord:
+    """A single evaluation record."""
+
+    experiment: str
+    procedure: str
+    metrics: dict[str, float]
+    checkpoint_step: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class MetricsAggregator:
+    """Aggregate and analyze evaluation metrics.
+
+    Supports multiple experiments, procedures, and per-sample results
+    for computing confidence intervals and significance.
+    """
+
+    HIGHER_BETTER = {
+        "ssim": True,
+        "psnr": True,
+        "identity_sim": True,
+        "lpips": False,
+        "fid": False,
+        "nme": False,
+    }
+
+    def __init__(self) -> None:
+        self.records: list[MetricRecord] = []
+
+    def add(
+        self,
+        experiment: str,
+        procedure: str,
+        metrics: dict[str, float],
+        checkpoint_step: int | None = None,
+        **metadata: Any,
+    ) -> None:
+        """Add a single evaluation record."""
+        self.records.append(
+            MetricRecord(
+                experiment=experiment,
+                procedure=procedure,
+                metrics=metrics,
+                checkpoint_step=checkpoint_step,
+                metadata=metadata,
+            )
+        )
+
+    def add_batch(
+        self,
+        experiment: str,
+        records: list[dict[str, Any]],
+    ) -> None:
+        """Add multiple records for an experiment.
+
+        Each record dict should have 'procedure' and metric keys.
+        """
+        for rec in records:
+            proc = rec.get("procedure", "all")
+            metrics = {
+                k: v for k, v in rec.items() if k != "procedure" and isinstance(v, (int, float))
+            }
+            self.add(experiment, proc, metrics)
+
+    @property
+    def experiments(self) -> list[str]:
+        """Unique experiment names in insertion order."""
+        seen: dict[str, None] = {}
+        for r in self.records:
+            seen.setdefault(r.experiment, None)
+        return list(seen.keys())
+
+    @property
+    def procedures(self) -> list[str]:
+        """Unique procedure names in insertion order."""
+        seen: dict[str, None] = {}
+        for r in self.records:
+            seen.setdefault(r.procedure, None)
+        return list(seen.keys())
+
+    @property
+    def metric_names(self) -> list[str]:
+        """All unique metric names."""
+        names: set[str] = set()
+        for r in self.records:
+            names.update(r.metrics.keys())
+        return sorted(names)
+
+    def filter(
+        self,
+        experiment: str | None = None,
+        procedure: str | None = None,
+    ) -> list[MetricRecord]:
+        """Filter records by experiment and/or procedure."""
+        results = self.records
+        if experiment is not None:
+            results = [r for r in results if r.experiment == experiment]
+        if procedure is not None:
+            results = [r for r in results if r.procedure == procedure]
+        return results
+
+    def mean(
+        self,
+        experiment: str,
+        metric: str,
+        procedure: str | None = None,
+    ) -> float:
+        """Compute mean of a metric for an experiment."""
+        recs = self.filter(experiment=experiment, procedure=procedure)
+        vals = [r.metrics[metric] for r in recs if metric in r.metrics]
+        if not vals:
+            return float("nan")
+        return sum(vals) / len(vals)
+
+    def std(
+        self,
+        experiment: str,
+        metric: str,
+        procedure: str | None = None,
+    ) -> float:
+        """Compute standard deviation of a metric."""
+        recs = self.filter(experiment=experiment, procedure=procedure)
+        vals = [r.metrics[metric] for r in recs if metric in r.metrics]
+        if len(vals) < 2:
+            return 0.0
+        m = sum(vals) / len(vals)
+        var = sum((v - m) ** 2 for v in vals) / (len(vals) - 1)
+        return math.sqrt(var)
+
+    def ci_95(
+        self,
+        experiment: str,
+        metric: str,
+        procedure: str | None = None,
+    ) -> tuple[float, float]:
+        """Compute 95% confidence interval (mean +/- 1.96*SE)."""
+        recs = self.filter(experiment=experiment, procedure=procedure)
+        vals = [r.metrics[metric] for r in recs if metric in r.metrics]
+        if not vals:
+            return (float("nan"), float("nan"))
+        n = len(vals)
+        m = sum(vals) / n
+        if n < 2:
+            return (m, m)
+        var = sum((v - m) ** 2 for v in vals) / (n - 1)
+        se = math.sqrt(var / n)
+        return (m - 1.96 * se, m + 1.96 * se)
+
+    def improvement_over(
+        self,
+        baseline: str,
+        metric: str | None = None,
+    ) -> dict[str, dict[str, float]]:
+        """Compute relative improvement of all experiments over a baseline.
+
+        Returns:
+            {experiment: {metric: relative_improvement_pct}}
+        """
+        metrics = [metric] if metric else self.metric_names
+        result: dict[str, dict[str, float]] = {}
+
+        for exp in self.experiments:
+            if exp == baseline:
+                continue
+            improvements: dict[str, float] = {}
+            for m in metrics:
+                base_val = self.mean(baseline, m)
+                exp_val = self.mean(exp, m)
+                if math.isnan(base_val) or math.isnan(exp_val) or base_val == 0:
+                    continue
+
+                higher_better = self.HIGHER_BETTER.get(m, True)
+                if higher_better:
+                    pct = (exp_val - base_val) / abs(base_val) * 100
+                else:
+                    pct = (base_val - exp_val) / abs(base_val) * 100
+                improvements[m] = round(pct, 2)
+
+            result[exp] = improvements
+
+        return result
+
+    def best_experiment(
+        self,
+        metric: str,
+        procedure: str | None = None,
+    ) -> str | None:
+        """Find the experiment with the best mean for a metric."""
+        higher_better = self.HIGHER_BETTER.get(metric, True)
+        best_exp = None
+        best_val = float("-inf") if higher_better else float("inf")
+
+        for exp in self.experiments:
+            val = self.mean(exp, metric, procedure)
+            if math.isnan(val):
+                continue
+            if (higher_better and val > best_val) or (not higher_better and val < best_val):
+                best_val = val
+                best_exp = exp
+
+        return best_exp
+
+    def summary_table(
+        self,
+        metrics: list[str] | None = None,
+        procedure: str | None = None,
+        include_std: bool = False,
+    ) -> str:
+        """Generate a text summary table.
+
+        Args:
+            metrics: Metrics to include. None = all.
+            procedure: Filter by procedure. None = aggregate.
+            include_std: Show mean +/- std.
+
+        Returns:
+            Formatted text table.
+        """
+        metrics = metrics or self.metric_names
+        exps = self.experiments
+
+        # Header
+        cols = ["Experiment"] + metrics
+        header = " | ".join(f"{c:>16s}" for c in cols)
+        lines = [header, "-" * len(header)]
+
+        for exp in exps:
+            parts = [f"{exp:>16s}"]
+            for m in metrics:
+                val = self.mean(exp, m, procedure)
+                if math.isnan(val):
+                    parts.append(f"{'--':>16s}")
+                elif include_std:
+                    s = self.std(exp, m, procedure)
+                    parts.append(f"{val:>8.4f}±{s:<6.4f}")
+                else:
+                    parts.append(f"{val:>16.4f}")
+            lines.append(" | ".join(parts))
+
+        return "\n".join(lines)
+
+    def to_json(self, path: str | Path | None = None) -> str:
+        """Export all records as JSON.
+
+        Args:
+            path: Optional file path to write to.
+
+        Returns:
+            JSON string.
+        """
+        data = {
+            "experiments": self.experiments,
+            "procedures": self.procedures,
+            "metrics": self.metric_names,
+            "records": [
+                {
+                    "experiment": r.experiment,
+                    "procedure": r.procedure,
+                    "metrics": r.metrics,
+                    "checkpoint_step": r.checkpoint_step,
+                    "metadata": r.metadata,
+                }
+                for r in self.records
+            ],
+        }
+        j = json.dumps(data, indent=2)
+
+        if path is not None:
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_text(j)
+
+        return j
+
+    @staticmethod
+    def from_json(path: str | Path) -> MetricsAggregator:
+        """Load aggregator from JSON."""
+        with open(path) as f:
+            data = json.load(f)
+
+        agg = MetricsAggregator()
+        for rec in data.get("records", []):
+            agg.add(
+                experiment=rec["experiment"],
+                procedure=rec["procedure"],
+                metrics=rec["metrics"],
+                checkpoint_step=rec.get("checkpoint_step"),
+            )
+        return agg