cloudanalyzer 0.2.0__tar.gz → 0.3.0__tar.gz

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudanalyzer
-Version: 0.2.0
+Version: 0.3.0
 Summary: CLI-first QA toolkit for point cloud, trajectory, and 3D perception outputs
 Author: rsasaki0109
 License-Expression: MIT

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/ca/__init__.py

@@ -1,3 +1,3 @@
 """CloudAnalyzer - AI-friendly CLI tool for point cloud analysis."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/ca/core/ground_evaluate.py

@@ -47,12 +47,34 @@ class GroundEvaluateStrategy(Protocol):
         """Evaluate ground segmentation quality."""
 
 
-def _voxel_keys(points: np.ndarray, voxel_size: float) -> set[tuple[int, int, int]]:
-    """Compute voxel grid keys for an Nx3 point array."""
+def _voxel_keys(points: np.ndarray, voxel_size: float) -> np.ndarray:
+    """Compute unique voxel grid keys for an Nx3 point array.
+
+    Returns an (M, 3) int64 array of unique (i, j, k) voxel indices, sorted
+    lexicographically. The original implementation built a ``set`` of Python
+    tuples via a per-row generator, which dominated runtime on city-scale
+    inputs (millions of points × 4 calls per evaluation).
+    """
     if points.shape[0] == 0:
-        return set()
+        return np.empty((0, 3), dtype=np.int64)
     indices = np.floor(points / voxel_size).astype(np.int64)
-    return {(int(row[0]), int(row[1]), int(row[2])) for row in indices}
+    return np.unique(indices, axis=0)
+
+
+def _voxel_intersection_size(a: np.ndarray, b: np.ndarray) -> int:
+    """Count voxel keys present in both ``a`` and ``b``.
+
+    Both inputs are expected to be the unique (M, 3) int64 output of
+    :func:`_voxel_keys`. Packs each row into a single ``np.void`` of the row's
+    byte length so ``np.intersect1d`` can run in C.
+    """
+    if a.size == 0 or b.size == 0:
+        return 0
+    item_size = a.dtype.itemsize * a.shape[1]
+    void_dtype = np.dtype((np.void, item_size))
+    a_view = np.ascontiguousarray(a).view(void_dtype).ravel()
+    b_view = np.ascontiguousarray(b).view(void_dtype).ravel()
+    return int(np.intersect1d(a_view, b_view, assume_unique=True).size)
 
 
 def confusion_metrics(tp: int, fp: int, fn: int, tn: int) -> dict[str, float]:
@@ -83,10 +105,10 @@ class VoxelConfusionGroundEvaluateStrategy:
         ref_ground_voxels = _voxel_keys(request.reference_ground, request.voxel_size)
         ref_nonground_voxels = _voxel_keys(request.reference_nonground, request.voxel_size)
 
-        tp = len(est_ground_voxels & ref_ground_voxels)
-        fp = len(est_ground_voxels & ref_nonground_voxels)
-        fn = len(est_nonground_voxels & ref_ground_voxels)
-        tn = len(est_nonground_voxels & ref_nonground_voxels)
+        tp = _voxel_intersection_size(est_ground_voxels, ref_ground_voxels)
+        fp = _voxel_intersection_size(est_ground_voxels, ref_nonground_voxels)
+        fn = _voxel_intersection_size(est_nonground_voxels, ref_ground_voxels)
+        tn = _voxel_intersection_size(est_nonground_voxels, ref_nonground_voxels)
         metrics = confusion_metrics(tp, fp, fn, tn)
 
         return GroundEvaluateResult(

cloudanalyzer-0.3.0/ca/core/map_evaluate.py

@@ -0,0 +1,302 @@
+"""Stable, minimal interface for point-cloud map evaluation.
+
+This slice started as ``ca/experiments/map_evaluate/`` with two
+non-comparable strategies on separate metric-family lanes:
+
+- ``nn_thresholds`` — reference-based (GT-aware) MapEval-style accuracy and
+  completeness@τ via per-point nearest-neighbor distances (scipy cKDTree).
+- ``voxel_entropy`` — reference-free self-consistency proxy via voxelized
+  neighborhood occupancy entropy.
+
+Because the two strategies do not compete head-to-head, "promoting to core"
+means lifting the **request/result contract plus the adopted reference-based
+strategy** here, leaving ``voxel_entropy`` in ``ca/experiments/map_evaluate``
+as the orthogonal reference-free option. Callers that just want GT-based
+metrics can now depend on ``ca.core.map_evaluate`` directly and the CLI
+no longer reaches into ``ca.experiments``.
+
+The reference-free lane remains experimental until we settle on a single
+GT-free metric — anyone needing it for now imports from
+``ca.experiments.map_evaluate.voxel_entropy`` explicitly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+import numpy as np
+
+
+# ---------------------------------------------------------------- contract
+
+
+@dataclass(slots=True)
+class MapEvaluateRequest:
+    """Compare an estimated point cloud map to a reference (optional).
+
+    Strategies with ``reference_required=True`` raise on ``reference_points=None``;
+    reference-free strategies treat the same field as unused.
+    """
+
+    estimated_points: np.ndarray  # (N, 3)
+    reference_points: np.ndarray | None = None  # (M, 3) when present
+    # MapEval-inspired: allow using an external coarse alignment.
+    initial_transform_4x4: np.ndarray | None = None  # shape (4, 4)
+    # "none" = use estimated_points as-is, "initial" = pre-apply initial_transform_4x4.
+    align_mode: str = "none"
+    downsample_voxel_size: float = 0.0
+    # Optional output dir for strategy-specific artifacts (colored PLYs, etc.)
+    artifact_dir: str | None = None
+    # MapEval "accuracy_level" thresholds for inlier ratios.
+    thresholds_m: tuple[float, ...] = (0.2, 0.1, 0.08, 0.05, 0.01)
+    # A coarse voxel size useful for structure-aware proxies.
+    structure_voxel_size: float = 0.5
+
+
+@dataclass(slots=True)
+class MapEvaluateResult:
+    """Common output for all strategies.
+
+    Classification fields (``metric_family``, ``reference_required``, ``mode``,
+    ``sampling_policy``) describe *how* the metrics were computed so consumers
+    (CI gates, reports, batch aggregators) can keep reference-based and
+    reference-free metrics in separate lanes without parsing metric names.
+    """
+
+    strategy: str
+    design: str
+    metrics: dict[str, float]
+    artifacts: dict[str, Any]
+    metric_family: str = "unspecified"
+    reference_required: bool = False
+    mode: str = "exact"
+    sampling_policy: dict[str, Any] = field(default_factory=dict)
+
+
+class MapEvaluateStrategy(Protocol):
+    """Protocol kept in core after promoting the reference-based strategy."""
+
+    name: str
+    design: str
+
+    def evaluate(self, request: MapEvaluateRequest) -> MapEvaluateResult:
+        """Evaluate a map and return classified metrics."""
+
+
+# ---------------------------------------------------------------- helpers
+
+
+def _require_xyz(points: np.ndarray, name: str) -> np.ndarray:
+    arr = np.asarray(points, dtype=np.float64)
+    if arr.ndim != 2 or arr.shape[1] != 3:
+        raise ValueError(f"{name} must be shape (N, 3); got {arr.shape}")
+    return arr
+
+
+def _require_transform_4x4(matrix: np.ndarray, name: str) -> np.ndarray:
+    mat = np.asarray(matrix, dtype=np.float64)
+    if mat.shape != (4, 4):
+        raise ValueError(f"{name} must be shape (4, 4); got {mat.shape}")
+    return mat
+
+
+def apply_transform(points: np.ndarray, transform_4x4: np.ndarray) -> np.ndarray:
+    pts = _require_xyz(points, "points")
+    t = _require_transform_4x4(transform_4x4, "transform_4x4")
+    if pts.shape[0] == 0:
+        return pts
+    hom = np.concatenate([pts, np.ones((pts.shape[0], 1), dtype=np.float64)], axis=1)
+    out = (hom @ t.T)[:, :3]
+    return np.asarray(out, dtype=np.float64)
+
+
+def aligned_estimated_points(request: MapEvaluateRequest) -> np.ndarray:
+    est = _require_xyz(request.estimated_points, "estimated_points")
+    mode = (request.align_mode or "none").strip().lower()
+    if mode == "none":
+        return est
+    if mode == "initial":
+        if request.initial_transform_4x4 is None:
+            raise ValueError("align_mode='initial' requires initial_transform_4x4.")
+        return apply_transform(est, request.initial_transform_4x4)
+    raise ValueError(f"Unsupported align_mode: {request.align_mode!r}. Use 'none' or 'initial'.")
+
+
+def ensure_artifact_dir(request: MapEvaluateRequest, subdir: str) -> Path | None:
+    """Return an ensured artifact directory path or None if disabled."""
+    if request.artifact_dir is None:
+        return None
+    root = Path(request.artifact_dir)
+    out = root / subdir
+    out.mkdir(parents=True, exist_ok=True)
+    return out
+
+
+def voxel_downsample(points: np.ndarray, voxel_size: float) -> np.ndarray:
+    """Deterministic voxel downsample by centroid per voxel."""
+    pts = _require_xyz(points, "points")
+    if pts.shape[0] == 0 or voxel_size <= 0:
+        return pts
+    keys = np.floor(pts / voxel_size).astype(np.int64)
+    order = np.lexsort((keys[:, 2], keys[:, 1], keys[:, 0]))
+    keys_sorted = keys[order]
+    pts_sorted = pts[order]
+    unique, start_idx = np.unique(keys_sorted, axis=0, return_index=True)
+    centroids: list[np.ndarray] = []
+    for i, s in enumerate(start_idx):
+        e = start_idx[i + 1] if i + 1 < len(start_idx) else pts_sorted.shape[0]
+        centroids.append(pts_sorted[s:e].mean(axis=0))
+    out = np.vstack(centroids) if centroids else np.zeros((0, 3), dtype=np.float64)
+    _ = unique  # kept to mirror the index ordering for documentation
+    return np.asarray(out)
+
+
+# ------------------------------------------------------- adopted strategy
+
+
+def _min_distances_kdtree(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """Per-point min Euclidean distance from ``a`` to ``b`` via scipy cKDTree."""
+    if a.shape[0] == 0:
+        return np.zeros((0,), dtype=np.float64)
+    if b.shape[0] == 0:
+        return np.full((a.shape[0],), np.inf, dtype=np.float64)
+
+    from scipy.spatial import cKDTree
+
+    tree = cKDTree(np.asarray(b, dtype=np.float64))
+    distances, _ = tree.query(np.asarray(a, dtype=np.float64), k=1)
+    return np.asarray(distances, dtype=np.float64)
+
+
+def _error_colors(dist_m: np.ndarray, vmax_m: float) -> np.ndarray:
+    """Green→red ramp for distance visualization."""
+    vmax = float(max(vmax_m, 1e-12))
+    x = np.clip(dist_m / vmax, 0.0, 1.0)
+    r = x
+    g = 1.0 - x
+    b = np.zeros_like(x)
+    return np.column_stack([r, g, b]).astype(np.float64)
+
+
+def _write_colored_ply(points: np.ndarray, colors: np.ndarray, path: str) -> None:
+    import open3d as o3d
+
+    pcd = o3d.geometry.PointCloud()
+    pcd.points = o3d.utility.Vector3dVector(np.asarray(points, dtype=np.float64))
+    pcd.colors = o3d.utility.Vector3dVector(np.asarray(colors, dtype=np.float64))
+    o3d.io.write_point_cloud(path, pcd, write_ascii=False)
+
+
+@dataclass(slots=True)
+class NNThresholdMapEvaluateStrategy:
+    """MapEval-style accuracy@τ / completeness@τ via per-point NN distances.
+
+    Promoted from ``ca/experiments/map_evaluate/nn_thresholds.py`` as the
+    adopted reference-based map evaluation strategy. The reference-free
+    ``voxel_entropy`` lane stays under ``ca.experiments`` because the two
+    strategies do not compete on the same metric family.
+    """
+
+    name: str = "nn_thresholds"
+    design: str = "functional"
+
+    def evaluate(self, request: MapEvaluateRequest) -> MapEvaluateResult:
+        est_aligned = aligned_estimated_points(request)
+        est = voxel_downsample(_require_xyz(est_aligned, "estimated_points"), request.downsample_voxel_size)
+        if request.reference_points is None:
+            raise ValueError("nn_thresholds requires reference_points (GT).")
+        ref = voxel_downsample(_require_xyz(request.reference_points, "reference_points"), request.downsample_voxel_size)
+
+        est_to_ref = _min_distances_kdtree(est, ref)
+        ref_to_est = _min_distances_kdtree(ref, est)
+
+        thresholds = tuple(float(x) for x in request.thresholds_m)
+        metrics: dict[str, float] = {
+            "n_est": float(est.shape[0]),
+            "n_ref": float(ref.shape[0]),
+            "mean_est_to_ref_m": float(np.mean(est_to_ref)) if est_to_ref.size else float("inf"),
+            "mean_ref_to_est_m": float(np.mean(ref_to_est)) if ref_to_est.size else float("inf"),
+            "chamfer_m": (
+                float(np.mean(est_to_ref)) + float(np.mean(ref_to_est))
+                if (est_to_ref.size and ref_to_est.size)
+                else float("inf")
+            ),
+        }
+
+        for t in thresholds:
+            metrics[f"accuracy@{t:.3f}m"] = float(np.mean(est_to_ref <= t)) if est_to_ref.size else 0.0
+            metrics[f"completeness@{t:.3f}m"] = float(np.mean(ref_to_est <= t)) if ref_to_est.size else 0.0
+
+        # One scalar summary (F-score) using the first threshold.
+        t0 = thresholds[0] if thresholds else 0.2
+        acc = metrics.get(f"accuracy@{t0:.3f}m", 0.0)
+        com = metrics.get(f"completeness@{t0:.3f}m", 0.0)
+        fscore = (2 * acc * com / (acc + com)) if (acc + com) > 0 else 0.0
+        metrics[f"fscore@{t0:.3f}m"] = float(fscore)
+
+        artifacts: dict[str, object] = {
+            "thresholds_m": thresholds,
+            "downsample_voxel_size": float(request.downsample_voxel_size),
+            "align_mode": request.align_mode,
+        }
+
+        # Optional: MapEval-style raw/inlier error visualization PLYs.
+        out_dir = ensure_artifact_dir(request, "map_evaluate/nn_thresholds")
+        if out_dir is not None and est.shape[0] > 0:
+            vmax = thresholds[0] if thresholds else 0.2
+            raw_colors = _error_colors(est_to_ref, vmax_m=vmax)
+            raw_path = str(out_dir / "estimated_error_raw.ply")
+            _write_colored_ply(est, raw_colors, raw_path)
+
+            inlier_mask = est_to_ref <= vmax
+            inlier_points = est[inlier_mask]
+            inlier_colors = raw_colors[inlier_mask]
+            inlier_path = str(out_dir / f"estimated_error_inlier_{vmax:.3f}m.ply")
+            _write_colored_ply(inlier_points, inlier_colors, inlier_path)
+
+            artifacts["estimated_error_raw_ply"] = raw_path
+            artifacts[f"estimated_error_inlier_{vmax:.3f}m_ply"] = inlier_path
+
+        downsample_voxel = float(request.downsample_voxel_size)
+        mode = "voxelized" if downsample_voxel > 0 else "exact"
+        sampling_policy: dict[str, object] = {
+            "downsample_voxel_size_m": downsample_voxel,
+            "thresholds_m": list(thresholds),
+            "align_mode": request.align_mode,
+            "nn_backend": "scipy_ckdtree",
+        }
+
+        return MapEvaluateResult(
+            strategy=self.name,
+            design=self.design,
+            metrics=metrics,
+            artifacts=artifacts,
+            metric_family="reference_based_nn_thresholds",
+            reference_required=True,
+            mode=mode,
+            sampling_policy=sampling_policy,
+        )
+
+
+def evaluate_map(
+    request: MapEvaluateRequest,
+    strategy: MapEvaluateStrategy | None = None,
+) -> MapEvaluateResult:
+    """Evaluate a map using the stabilized strategy (defaults to NNThreshold)."""
+    eval_strategy = strategy or NNThresholdMapEvaluateStrategy()
+    return eval_strategy.evaluate(request)
+
+
+__all__ = [
+    "MapEvaluateRequest",
+    "MapEvaluateResult",
+    "MapEvaluateStrategy",
+    "NNThresholdMapEvaluateStrategy",
+    "aligned_estimated_points",
+    "apply_transform",
+    "ensure_artifact_dir",
+    "evaluate_map",
+    "voxel_downsample",
+]

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/ca/experiments/ground_evaluate/height_band.py

@@ -33,7 +33,7 @@ def _per_band_confusion(
     voxel_size: float,
 ) -> list[dict]:
     """Compute confusion matrix per height band using voxel matching."""
-    from ca.core.ground_evaluate import _voxel_keys
+    from ca.core.ground_evaluate import _voxel_intersection_size, _voxel_keys
 
     num_bands = len(band_edges) - 1
     bands: list[dict] = []
@@ -51,10 +51,10 @@ def _per_band_confusion(
         rg = _voxel_keys(_filter(reference_ground), voxel_size)
         rn = _voxel_keys(_filter(reference_nonground), voxel_size)
 
-        tp = len(eg & rg)
-        fp = len(eg & rn)
-        fn = len(en & rg)
-        tn = len(en & rn)
+        tp = _voxel_intersection_size(eg, rg)
+        fp = _voxel_intersection_size(eg, rn)
+        fn = _voxel_intersection_size(en, rg)
+        tn = _voxel_intersection_size(en, rn)
         metrics = confusion_metrics(tp, fp, fn, tn)
         bands.append({
             "band": band_idx,

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/ca/experiments/ground_evaluate/voxel_confusion.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from ca.core.ground_evaluate import (
     GroundEvaluateRequest,
     GroundEvaluateResult,
+    _voxel_intersection_size,
     _voxel_keys,
     confusion_metrics,
 )
@@ -22,10 +23,10 @@ class VoxelConfusionExperimentalStrategy:
         ref_ground_voxels = _voxel_keys(request.reference_ground, request.voxel_size)
         ref_nonground_voxels = _voxel_keys(request.reference_nonground, request.voxel_size)
 
-        tp = len(est_ground_voxels & ref_ground_voxels)
-        fp = len(est_ground_voxels & ref_nonground_voxels)
-        fn = len(est_nonground_voxels & ref_ground_voxels)
-        tn = len(est_nonground_voxels & ref_nonground_voxels)
+        tp = _voxel_intersection_size(est_ground_voxels, ref_ground_voxels)
+        fp = _voxel_intersection_size(est_ground_voxels, ref_nonground_voxels)
+        fn = _voxel_intersection_size(est_nonground_voxels, ref_ground_voxels)
+        tn = _voxel_intersection_size(est_nonground_voxels, ref_nonground_voxels)
         metrics = confusion_metrics(tp, fp, fn, tn)
 
         return GroundEvaluateResult(

cloudanalyzer-0.3.0/ca/experiments/map_evaluate/common.py

@@ -0,0 +1,99 @@
+"""Re-exports for backward compatibility after the core promotion.
+
+The map_evaluate request/result contract and helpers are now owned by
+``ca.core.map_evaluate``. The experiment slice keeps this module as a thin
+re-export so the remaining experimental strategies
+(``voxel_entropy.VoxelEntropyMapEvaluateStrategy``) and any external callers
+still work via the old import path.
+"""
+
+from __future__ import annotations
+
+from ca.core.map_evaluate import (
+    MapEvaluateRequest,
+    MapEvaluateResult,
+    _require_xyz,
+    _require_transform_4x4,
+    aligned_estimated_points,
+    apply_transform,
+    ensure_artifact_dir,
+    voxel_downsample,
+)
+
+import numpy as np
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class MapEvaluateDatasetCase:
+    """Small fixture: human-readable name + the request to score."""
+
+    name: str
+    description: str
+    request: MapEvaluateRequest
+
+
+def build_default_datasets() -> list[MapEvaluateDatasetCase]:
+    """Small deterministic point-cloud scenarios for quick strategy comparison."""
+    rng = np.random.default_rng(7)
+
+    ref = rng.uniform([-5, -5, -1], [5, 5, 1], size=(400, 3))
+
+    est_drift = ref + np.array([0.15, -0.05, 0.0]) + rng.normal(0, 0.02, size=ref.shape)
+
+    mask = ref[:, 0] > -1.0
+    est_incomplete = ref[mask] + rng.normal(0, 0.02, size=(mask.sum(), 3))
+
+    scan_a = rng.uniform([-6, -6, -1], [6, 6, 1], size=(250, 3))
+    scan_b = scan_a + rng.normal(0, 0.03, size=scan_a.shape)
+    est_self = np.vstack([scan_a, scan_b])
+
+    return [
+        MapEvaluateDatasetCase(
+            name="gt_drift",
+            description="Estimated map has small rigid drift relative to reference.",
+            request=MapEvaluateRequest(
+                estimated_points=est_drift,
+                reference_points=ref,
+                downsample_voxel_size=0.0,
+                thresholds_m=(0.2, 0.1, 0.08, 0.05, 0.01),
+                structure_voxel_size=0.5,
+            ),
+        ),
+        MapEvaluateDatasetCase(
+            name="gt_incomplete",
+            description="Estimated map misses a region; completeness should drop.",
+            request=MapEvaluateRequest(
+                estimated_points=est_incomplete,
+                reference_points=ref,
+                downsample_voxel_size=0.0,
+                thresholds_m=(0.2, 0.1, 0.08, 0.05, 0.01),
+                structure_voxel_size=0.5,
+            ),
+        ),
+        MapEvaluateDatasetCase(
+            name="no_gt_self_consistency",
+            description="No GT; fused map from two noisy overlapping scans.",
+            request=MapEvaluateRequest(
+                estimated_points=est_self,
+                reference_points=None,
+                downsample_voxel_size=0.0,
+                thresholds_m=(0.2, 0.1, 0.08, 0.05, 0.01),
+                structure_voxel_size=0.5,
+            ),
+        ),
+    ]
+
+
+__all__ = [
+    "MapEvaluateDatasetCase",
+    "MapEvaluateRequest",
+    "MapEvaluateResult",
+    "_require_xyz",
+    "_require_transform_4x4",
+    "aligned_estimated_points",
+    "apply_transform",
+    "build_default_datasets",
+    "ensure_artifact_dir",
+    "voxel_downsample",
+]

{cloudanalyzer-0.2.0 → cloudanalyzer-0.3.0}/ca/experiments/map_evaluate/evaluate.py

@@ -79,9 +79,14 @@ def run_map_evaluate_experiment(
         ],
         "results": rows,
         "decision": {
-            "selected_experiment": None,
-            "stabilized_core_strategy": None,
-            "reason": "Not yet promoted to core; keep iterating on metrics and IO formats.",
+            "selected_experiment": "nn_thresholds",
+            "stabilized_core_strategy": "nn_thresholds",
+            "reason": (
+                "Promoted to ca.core.map_evaluate as the reference-based "
+                "(GT-aware) MapEval-style nearest-neighbor threshold strategy. "
+                "voxel_entropy remains experimental as the orthogonal "
+                "reference-free lane until a single GT-free metric is settled."
+            ),
         },
     }
 
@@ -136,16 +141,18 @@ def render_decision_section(report: dict) -> str:
             "",
             "### Adopted",
             "",
-            "No strategy is adopted yet (still experimental).",
+            "- `nn_thresholds` (reference-based, GT-aware MapEval-style accuracy/completeness@τ).",
+            "  Promoted to `ca/core/map_evaluate.py` as `NNThresholdMapEvaluateStrategy`.",
             "",
             "### Not Adopted",
             "",
-            "- All strategies remain experimental until we settle IO formats and performance constraints.",
+            "- `voxel_entropy` (reference-free self-consistency proxy) stays under `ca/experiments`",
+            "  as the orthogonal GT-free lane until a single reference-free metric is settled.",
             "",
-            "### Trigger To Promote",
+            "### Trigger To Promote `voxel_entropy`",
             "",
-            "- A stable request/result contract is needed by the CLI or library callers.",
-            "- We have at least two strategies with clear trade-offs and representative datasets.",
+            "- Pick one GT-free metric (entropy / structure / MME) as the canonical lane.",
+            "- Define a stable failure-mode contract (when does a GT-free score block CI?).",
         ]
     )
 
@@ -155,10 +162,11 @@ def render_interface_section(report: dict) -> str:
         [
             "## map_evaluate",
             "",
-            "### Current Minimal Interface (experimental)",
+            "### Current Minimal Interface",
             "",
-            "Not promoted to `ca/core` yet. Current request/result shapes live in "
-            "`cloudanalyzer/ca/experiments/map_evaluate/common.py`.",
+            "Promoted to `ca/core/map_evaluate.py`. The request/result contract,",
+            "shared helpers, and adopted `NNThresholdMapEvaluateStrategy` all live there.",
+            "`ca/experiments/map_evaluate/{common,nn_thresholds}.py` re-export from core for back-compat.",
             "",
             "Result objects carry classification fields so reference-based and reference-free metrics stay in separate lanes:",
             "",

cloudanalyzer-0.3.0/ca/experiments/map_evaluate/nn_thresholds.py

@@ -0,0 +1,16 @@
+"""Backward-compatible re-export of the now-promoted nn_thresholds strategy.
+
+The MapEval-style nearest-neighbor threshold strategy has been promoted to
+``ca.core.map_evaluate`` as ``NNThresholdMapEvaluateStrategy``. This module
+stays as a thin re-export so any existing imports (and the experimental
+``map_evaluate`` registry) keep working.
+"""
+
+from __future__ import annotations
+
+from ca.core.map_evaluate import (
+    NNThresholdMapEvaluateStrategy,
+    _min_distances_kdtree,
+)
+
+__all__ = ["NNThresholdMapEvaluateStrategy", "_min_distances_kdtree"]