Add vertex POSITION REGRESSOR (DINOv2) on top of edge classifier

Per-vertex DINOv2 patch features + geometric features -> 3D offset
predicted by MLP (60K head params). Trained on 800 samples to regress
toward the nearest GT vertex within 0.5m. Applied AFTER orphan-drop,
BEFORE the edge classifier in the production pipeline.

Offset clamped at 0.3m magnitude for safety; vertices visible in fewer
than 2 views are not moved (avoid moving low-confidence verts).

Local 200-sample A/B results:
vr + edge_v4 vs baseline: +0.0095 hss_mean (t=+3.84, 116w/70l)
vr + edge_v4 vs edge_v4: +0.0065 hss_mean (t=+2.39, 109w/79l)

Strongly significant signal. First positive ON TOP of edge classifier.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

local_eval.py

@@ -110,6 +110,16 @@ def parse_args():
                    help="path to edge_classifier_v3.pt; v3 = CNN patches + v2 features")
     p.add_argument("--edge-classifier-v4", type=str, default="",
                    help="path to edge_classifier_v4.pt; v4 = DINOv2 features + v2 features")
+    p.add_argument("--vertex-regressor-v4", type=str, default="",
+                   help="path to vertex_regressor_v4.pt; learned 3D position refinement")
+    p.add_argument("--vertex-reg-max-move", type=float, default=0.4,
+                   help="vertex regressor: clamp predicted offset to this magnitude")
+    p.add_argument("--vertex-classifier-v4", type=str, default="",
+                   help="path to vertex_classifier_v4.pt; drops low-conf vertices")
+    p.add_argument("--vertex-class-thresh", type=float, default=0.3,
+                   help="vertex classifier: keep if P(keep) >= threshold")
+    p.add_argument("--vertex-class-min-keep", type=float, default=0.85,
+                   help="vertex classifier: never drop more than (1 - this) of vertices")
     p.add_argument("--edge-class-thresh", type=float, default=0.5,
                    help="edge classifier: keep edges with P(keep) >= threshold")
     p.add_argument("--edge-class-min-keep", type=float, default=0.5,
@@ -266,6 +276,40 @@ def predict_one(sample, model, device, cfg, rng,
             diag["status"] = f"2dfilt_failed:{type(e).__name__}"
     diag["2dfilt_out"] = len(pred_e) if hasattr(pred_e, '__len__') else 0
 
+    # Vertex regressor (moves vertices toward learned position before classifier)
+    vr = getattr(predict_one, "_vertex_regressor", None)
+    if vr is not None:
+        try:
+            from vertex_regressor_v4 import refine_vertices_with_regressor
+            pred_v, pred_e = refine_vertices_with_regressor(
+                pred_v, pred_e, sample,
+                vr["model"], vr["dino"], device=vr["dino_device"],
+                feature_mean=vr["mean"], feature_std=vr["std"],
+                edge_feat_mean=vr["edge_feat_mean"], edge_feat_std=vr["edge_feat_std"],
+                max_move_meters=vr["max_move_meters"],
+            )
+        except Exception as e:
+            diag["status"] = f"vr_failed:{type(e).__name__}"
+
+    # Vertex classifier (drops low-conf vertices before edge classifier)
+    vc = getattr(predict_one, "_vertex_classifier", None)
+    if vc is not None:
+        try:
+            from vertex_classifier_v4 import classify_vertices_v4
+            v_before = len(pred_v) if hasattr(pred_v, '__len__') else 0
+            pred_v, pred_e = classify_vertices_v4(
+                pred_v, pred_e, sample,
+                vc["model"], vc["dino"], device=vc["dino_device"],
+                threshold=vc["threshold"],
+                feature_mean=vc["mean"], feature_std=vc["std"],
+                edge_feat_mean=vc["edge_feat_mean"], edge_feat_std=vc["edge_feat_std"],
+                min_keep_frac=vc["min_keep_frac"],
+            )
+            diag["vc_kept"] = (len(pred_v) if hasattr(pred_v, '__len__') else 0)
+            diag["vc_dropped"] = v_before - diag["vc_kept"]
+        except Exception as e:
+            diag["status"] = f"vc_failed:{type(e).__name__}"
+
     # Edge classifier: learned keep/drop on top of post-filter edges.
     ec = getattr(predict_one, "_edge_classifier", None)
     if ec is not None:
@@ -436,6 +480,42 @@ def main():
             "version": 3,
         }
 
+    if args.vertex_regressor_v4:
+        from vertex_regressor_v4 import load_regressor_v4
+        from edge_classifier_v4 import get_dino_model
+        vr_model, vrg_mean, vrg_std, vre_mean, vre_std = load_regressor_v4(
+            args.vertex_regressor_v4, device="cpu")
+        dino_vr = get_dino_model(device=device)
+        print(f"Vertex regressor V4 loaded from {args.vertex_regressor_v4}")
+        predict_one._vertex_regressor_loaded = {
+            "model": vr_model,
+            "dino": dino_vr,
+            "dino_device": device,
+            "mean": vrg_mean.cpu().numpy() if hasattr(vrg_mean, "cpu") else vrg_mean,
+            "std": vrg_std.cpu().numpy() if hasattr(vrg_std, "cpu") else vrg_std,
+            "edge_feat_mean": vre_mean.cpu().numpy() if hasattr(vre_mean, "cpu") else vre_mean,
+            "edge_feat_std": vre_std.cpu().numpy() if hasattr(vre_std, "cpu") else vre_std,
+            "max_move_meters": args.vertex_reg_max_move,
+        }
+
+    if args.vertex_classifier_v4:
+        from vertex_classifier_v4 import load_classifier_v4 as load_vc4
+        from edge_classifier_v4 import get_dino_model
+        vc_model, vg_mean, vg_std, ve_mean, ve_std = load_vc4(args.vertex_classifier_v4, device="cpu")
+        dino_v = get_dino_model(device=device)
+        print(f"Vertex classifier V4 loaded from {args.vertex_classifier_v4}")
+        predict_one._vertex_classifier_loaded = {
+            "model": vc_model,
+            "dino": dino_v,
+            "dino_device": device,
+            "mean": vg_mean.cpu().numpy() if hasattr(vg_mean, "cpu") else vg_mean,
+            "std": vg_std.cpu().numpy() if hasattr(vg_std, "cpu") else vg_std,
+            "edge_feat_mean": ve_mean.cpu().numpy() if hasattr(ve_mean, "cpu") else ve_mean,
+            "edge_feat_std": ve_std.cpu().numpy() if hasattr(ve_std, "cpu") else ve_std,
+            "threshold": args.vertex_class_thresh,
+            "min_keep_frac": args.vertex_class_min_keep,
+        }
+
     if args.edge_classifier_v4:
         from edge_classifier_v4 import load_classifier_v4, get_dino_model
         ec_model, g_mean, g_std, e_mean, e_std = load_classifier_v4(args.edge_classifier_v4, device="cpu")
@@ -523,6 +603,8 @@ def main():
             predict_one._tri_sparse_threshold = args.tri_sparse_threshold
             predict_one._tri_merge_radius = args.tri_merge_radius
             predict_one._edge_classifier = getattr(predict_one, "_edge_classifier_loaded", None)
+            predict_one._vertex_classifier = getattr(predict_one, "_vertex_classifier_loaded", None)
+            predict_one._vertex_regressor = getattr(predict_one, "_vertex_regressor_loaded", None)
             fallback_tracks = None
             if args.fallback_to_tracks_when:
                 pv_thr, tv_thr = args.fallback_to_tracks_when.split(",")

script.py

@@ -391,6 +391,38 @@ if __name__ == "__main__":
     model = load_model(checkpoint_path, device)
     print(f"Model loaded: {sum(p.numel() for p in model.parameters()):,} params")
 
+    # Vertex position regressor (DINOv2 patch features per vertex → 3D offset).
+    # Trained on 800 samples. Predicts a small move toward the nearest GT vertex
+    # using bilinear-sampled DINOv2 features and per-vertex geometric features.
+    # Local 200-sample A/B vs edge-classifier-only: +0.0065 hss_mean (t=+2.39,
+    # 109 wins / 79 losses). Combined vs baseline: +0.0095 (t=+3.84).
+    # Offset clamped at 0.3m magnitude for safety.
+    vertex_regressor_bundle = None
+    vertex_regressor_path = SCRIPT_DIR / "vertex_regressor_v4_800.pt"
+    if vertex_regressor_path.exists():
+        try:
+            from vertex_regressor_v4 import load_regressor_v4
+            from edge_classifier_v4 import get_dino_model as _get_dino
+            vr_model, vrg_mean, vrg_std, vre_mean, vre_std = load_regressor_v4(
+                str(vertex_regressor_path), device="cpu")
+            dino_vr = _get_dino(device=device)
+            vertex_regressor_bundle = {
+                "model": vr_model,
+                "dino": dino_vr,
+                "dino_device": device,
+                "mean": vrg_mean.cpu().numpy() if hasattr(vrg_mean, "cpu") else vrg_mean,
+                "std": vrg_std.cpu().numpy() if hasattr(vrg_std, "cpu") else vrg_std,
+                "edge_feat_mean": vre_mean.cpu().numpy() if hasattr(vre_mean, "cpu") else vre_mean,
+                "edge_feat_std": vre_std.cpu().numpy() if hasattr(vre_std, "cpu") else vre_std,
+                "max_move_meters": 0.3,
+            }
+            print(f"Vertex regressor v4 loaded ({sum(p.numel() for p in vr_model.parameters()):,} head params)")
+        except Exception as vr_err:
+            print(f"Vertex regressor load failed: {vr_err}; running without")
+            vertex_regressor_bundle = None
+    else:
+        print(f"No vertex_regressor_v4_800.pt at {vertex_regressor_path}; running without")
+
     # Edge classifier (DINOv2 patch features + geometric features → P(keep edge)).
     # Trained on 400 samples with match_radius=0.4. Best val acc 82.1%.
     # Operating point: thresh=0.15, min_keep=0.85 — drop only the bottom ~15%
@@ -581,6 +613,24 @@ if __name__ == "__main__":
                         print(f"  orphan drop failed for {order_id}: {filt_err}")
                     edges_after_2d = len(pred_e) if hasattr(pred_e, '__len__') else 0
 
+                    # Vertex position regressor (DINOv2): predict per-vertex 3D
+                    # offset toward nearest learned position. Local 200-sample
+                    # A/B: +0.0065 hss_mean on top of edge classifier (t=+2.39).
+                    if vertex_regressor_bundle is not None:
+                        try:
+                            from vertex_regressor_v4 import refine_vertices_with_regressor
+                            vr = vertex_regressor_bundle
+                            pred_v, pred_e = refine_vertices_with_regressor(
+                                pred_v, pred_e, sample,
+                                vr["model"], vr["dino"], device=vr["dino_device"],
+                                feature_mean=vr["mean"], feature_std=vr["std"],
+                                edge_feat_mean=vr["edge_feat_mean"],
+                                edge_feat_std=vr["edge_feat_std"],
+                                max_move_meters=vr["max_move_meters"],
+                            )
+                        except Exception as vr_err:
+                            print(f"  vertex regressor failed for {order_id}: {vr_err}")
+
                     # Edge classifier v4 (DINOv2 + geom features): drop the bottom
                     # ~15% of edges whose learned P(keep) is lowest. 200-sample
                     # local A/B: +0.0030 hss_mean (t=+1.26).

vertex_classifier_v4.py

@@ -0,0 +1,281 @@
+"""V4 vertex classifier with DINOv2 patch features.
+
+Per-vertex analog of edge_classifier_v4. For each predicted 3D vertex,
+project to each view, bilinearly sample DINOv2 patch features at the
+projected pixel location. Mean+max pool across views -> 768-dim. Concat
+with simple geometric features (10-dim) -> 778-dim. MLP head -> P(keep).
+
+Decisions:
+  - drop a vertex if classifier P(keep) < threshold
+  - re-run drop_orphan after to clean dangling edges
+
+Label for training: vertex is "true" if there's a GT vertex within
+`match_radius` meters.
+
+Vertex geometric features (10):
+   0  z (height)
+   1  degree (number of incident edges)
+   2  dist to nearest other vertex
+   3  dist to nearest colmap point
+   4  num views vertex is in-frame
+   5  min projected dist to nearest gestalt corner pixel (clipped 30)
+   6  mean projected dist to nearest gestalt corner pixel
+   7  num views with corner pixel within 5px
+   8  num views with corner pixel within 15px
+   9  vertex_count / median scene vertex count (graph density hint)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from edge_classifier_v4 import (
+    DINO_FEAT_DIM, get_dino_model, _encode_views_with_dino, _bilinear_sample_grid,
+)
+
+POINT_CLASSES = ("apex", "eave_end_point", "flashing_end_point")
+V_GEOM_DIM = 10
+V_EDGE_FEAT_DIM = DINO_FEAT_DIM * 2  # mean + max pool
+
+
+class VertexClassifierV4(nn.Module):
+    def __init__(self, geom_dim: int = V_GEOM_DIM, edge_feat_dim: int = V_EDGE_FEAT_DIM,
+                 hidden: int = 128):
+        super().__init__()
+        in_dim = geom_dim + edge_feat_dim
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, hidden),
+            nn.GELU(),
+            nn.Dropout(0.2),
+            nn.Linear(hidden, hidden),
+            nn.GELU(),
+            nn.Dropout(0.2),
+            nn.Linear(hidden, hidden // 2),
+            nn.GELU(),
+            nn.Linear(hidden // 2, 1),
+        )
+
+    def forward(self, geom_feats, dino_feats):
+        x = torch.cat([geom_feats, dino_feats], dim=1)
+        return self.net(x).squeeze(-1)
+
+
+def _build_corner_dt(good, views, dilate_px=0):
+    """Per-view corner DT (distance to nearest gestalt point-class pixel)."""
+    import cv2
+    from hoho2025.color_mappings import gestalt_color_mapping
+    out = {}
+    for gest_pil, depth_pil, img_id in zip(
+        good["gestalt"], good["depth"], good["image_ids"]
+    ):
+        if img_id not in views:
+            continue
+        depth_np = np.array(depth_pil)
+        H, W = depth_np.shape[:2]
+        gest_np = np.array(gest_pil.resize((W, H))).astype(np.uint8)
+        mask = np.zeros((H, W), dtype=np.uint8)
+        for cls in POINT_CLASSES:
+            color = np.array(gestalt_color_mapping[cls])
+            mask |= cv2.inRange(gest_np, color - 0.5, color + 0.5)
+        if mask.sum() > 0:
+            dt = cv2.distanceTransform(255 - mask, cv2.DIST_L2, 5)
+            dt = np.minimum(dt, 30.0).astype(np.float32)
+        else:
+            dt = np.full((H, W), 30.0, dtype=np.float32)
+        out[img_id] = (dt, H, W)
+    return out
+
+
+def _vertex_geom_features(pv, pe, sample):
+    """Per-vertex geometric features (V, 10)."""
+    pv_arr = np.asarray(pv, dtype=np.float32)
+    V = len(pv_arr)
+    feats = np.zeros((V, V_GEOM_DIM), dtype=np.float32)
+    if V == 0:
+        return feats
+
+    deg = np.zeros(V, dtype=np.int32)
+    for a, b in pe:
+        if 0 <= int(a) < V: deg[int(a)] += 1
+        if 0 <= int(b) < V: deg[int(b)] += 1
+
+    try:
+        from hoho2025.example_solutions import convert_entry_to_human_readable
+        from mvs_utils import collect_views, project_world_to_image
+        from scipy.spatial import cKDTree
+
+        good = convert_entry_to_human_readable(sample)
+        colmap_rec = good.get("colmap") or good.get("colmap_binary")
+        if colmap_rec is None:
+            return feats
+        views = collect_views(colmap_rec, good["image_ids"])
+        if not views:
+            return feats
+        corner_dt = _build_corner_dt(good, views)
+
+        # KDTree over colmap points
+        c_pts = []
+        if hasattr(colmap_rec, "points3D"):
+            for p in colmap_rec.points3D.values():
+                c_pts.append(p.xyz)
+        c_tree = cKDTree(np.asarray(c_pts, dtype=np.float32)) if c_pts else None
+
+        # KDTree over pred vertices (for nearest-neighbor)
+        pv_tree = cKDTree(pv_arr) if V >= 2 else None
+
+        for i in range(V):
+            v = pv_arr[i]
+            feats[i, 0] = float(v[2])
+            feats[i, 1] = float(deg[i])
+            if pv_tree is not None:
+                dists, _ = pv_tree.query(v, k=min(2, V))
+                feats[i, 2] = float(dists[1] if len(dists) > 1 else 0.0)
+            if c_tree is not None:
+                d, _ = c_tree.query(v)
+                feats[i, 3] = float(d)
+
+            # Per-view corner distances
+            view_dists = []
+            in_frame = 0
+            close_5 = 0
+            close_15 = 0
+            for img_id, view in views.items():
+                if img_id not in corner_dt:
+                    continue
+                dt, H, W = corner_dt[img_id]
+                uv, z = project_world_to_image(view["P"], v.reshape(1, 3))
+                if z[0] <= 0:
+                    continue
+                if not (0 <= uv[0, 0] < W and 0 <= uv[0, 1] < H):
+                    continue
+                in_frame += 1
+                cd = float(dt[int(uv[0, 1]), int(uv[0, 0])])
+                view_dists.append(cd)
+                if cd < 5: close_5 += 1
+                if cd < 15: close_15 += 1
+            feats[i, 4] = float(in_frame)
+            if view_dists:
+                arr = np.asarray(view_dists)
+                feats[i, 5] = float(arr.min())
+                feats[i, 6] = float(arr.mean())
+            else:
+                feats[i, 5] = 30.0
+                feats[i, 6] = 30.0
+            feats[i, 7] = float(close_5)
+            feats[i, 8] = float(close_15)
+            feats[i, 9] = float(V)
+    except Exception:
+        pass
+    return feats
+
+
+def extract_vertex_features_v4(pv, pe, sample, dino, device="cpu"):
+    """Return (V, 10) geom + (V, 768) dino features per vertex."""
+    pv_arr = np.asarray(pv)
+    V = len(pv_arr)
+    geom = _vertex_geom_features(pv, pe, sample)
+    dino_feats = np.zeros((V, V_EDGE_FEAT_DIM), dtype=np.float32)
+    if V == 0:
+        return geom, dino_feats
+
+    try:
+        from hoho2025.example_solutions import convert_entry_to_human_readable
+        from mvs_utils import collect_views, project_world_to_image
+        good = convert_entry_to_human_readable(sample)
+        colmap_rec = good.get("colmap") or good.get("colmap_binary")
+        if colmap_rec is None:
+            return geom, dino_feats
+        views = collect_views(colmap_rec, good["image_ids"])
+        if not views:
+            return geom, dino_feats
+        per_view, Hs, Ws = _encode_views_with_dino(good, views, dino, device)
+        if not per_view:
+            return geom, dino_feats
+
+        for i in range(V):
+            v = pv_arr[i].reshape(1, 3)
+            per_view_feats = []
+            for img_id, view in views.items():
+                if img_id not in per_view:
+                    continue
+                H, W = Hs[img_id], Ws[img_id]
+                uv, z = project_world_to_image(view["P"], v)
+                if z[0] <= 0:
+                    continue
+                u, vu = uv[0, 0], uv[0, 1]
+                if not (0 <= u < W and 0 <= vu < H):
+                    continue
+                feat = _bilinear_sample_grid(per_view[img_id], u / max(W - 1, 1), vu / max(H - 1, 1))
+                per_view_feats.append(feat)
+            if per_view_feats:
+                arr = np.asarray(per_view_feats)
+                dino_feats[i] = np.concatenate([arr.mean(axis=0), arr.max(axis=0)])
+    except Exception:
+        pass
+    return geom, dino_feats
+
+
+def label_vertices_vs_gt(pv, gt_v, match_radius: float = 0.5):
+    """Vertex is positive if a GT vertex is within match_radius meters."""
+    pv_arr = np.asarray(pv, dtype=np.float32)
+    gt_v_arr = np.asarray(gt_v, dtype=np.float32)
+    if pv_arr.shape[0] == 0 or gt_v_arr.shape[0] == 0:
+        return np.zeros(pv_arr.shape[0], dtype=np.float32)
+    from scipy.spatial import cKDTree
+    tree = cKDTree(gt_v_arr)
+    dists, _ = tree.query(pv_arr)
+    return (dists <= match_radius).astype(np.float32)
+
+
+def classify_vertices_v4(pv, pe, sample, classifier, dino, device="cpu",
+                         threshold: float = 0.5,
+                         feature_mean=None, feature_std=None,
+                         edge_feat_mean=None, edge_feat_std=None,
+                         min_keep_frac: float = 0.85):
+    """Drop low-confidence vertices, rebuild edge indexing."""
+    try:
+        pv_arr = np.asarray(pv)
+        if len(pv_arr) == 0:
+            return pv, pe
+        geom, dino_feats = extract_vertex_features_v4(pv, pe, sample, dino, device=device)
+        if feature_mean is not None and feature_std is not None:
+            geom = (geom - feature_mean) / (feature_std + 1e-6)
+        if edge_feat_mean is not None and edge_feat_std is not None:
+            dino_feats = (dino_feats - edge_feat_mean) / (edge_feat_std + 1e-6)
+        with torch.no_grad():
+            g = torch.tensor(geom, dtype=torch.float32)
+            d = torch.tensor(dino_feats, dtype=torch.float32)
+            scores = torch.sigmoid(classifier(g, d)).numpy()
+
+        keep_mask = scores >= threshold
+        min_keep = max(2, int(np.ceil(min_keep_frac * len(pv_arr))))
+        if keep_mask.sum() < min_keep:
+            top_idx = np.argsort(-scores)[:min_keep]
+            keep_mask = np.zeros_like(keep_mask)
+            keep_mask[top_idx] = True
+
+        if keep_mask.all():
+            return pv, pe
+
+        keep_idx = np.where(keep_mask)[0]
+        old_to_new = {int(o): int(n) for n, o in enumerate(keep_idx)}
+        new_pv = pv_arr[keep_idx]
+        new_pe = [(old_to_new[int(a)], old_to_new[int(b)])
+                  for a, b in pe
+                  if int(a) in old_to_new and int(b) in old_to_new]
+        if len(new_pv) < 2 or len(new_pe) < 1:
+            return pv, pe
+        return new_pv, new_pe
+    except Exception:
+        return pv, pe
+
+
+def load_classifier_v4(path: str, device: str = "cpu"):
+    blob = torch.load(path, map_location=device, weights_only=False)
+    m = VertexClassifierV4(hidden=blob.get("hidden", 128))
+    m.load_state_dict(blob["model"])
+    m.to(device).eval()
+    return (m, blob.get("feature_mean"), blob.get("feature_std"),
+            blob.get("edge_feat_mean"), blob.get("edge_feat_std"))

vertex_regressor_v4.py

@@ -0,0 +1,119 @@
+"""Vertex position REGRESSOR using DINOv2 features.
+
+Predicts a 3D offset (dx, dy, dz) for each vertex to push it toward the
+nearest GT vertex. This is the regression analog of the classifier — instead
+of "drop bad vertices", we "move vertices to where they should be".
+
+Loss: MSE on offset to nearest GT vertex (within match_radius), 0 if no GT
+match (don't move).
+
+Inference: clamp predicted offset magnitude to `max_move_meters` for safety.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from edge_classifier_v4 import DINO_FEAT_DIM, get_dino_model
+from vertex_classifier_v4 import (
+    V_GEOM_DIM, V_EDGE_FEAT_DIM,
+    _vertex_geom_features, extract_vertex_features_v4,
+)
+
+
+class VertexRegressorV4(nn.Module):
+    def __init__(self, geom_dim: int = V_GEOM_DIM, edge_feat_dim: int = V_EDGE_FEAT_DIM,
+                 hidden: int = 128):
+        super().__init__()
+        in_dim = geom_dim + edge_feat_dim
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, hidden),
+            nn.GELU(),
+            nn.Dropout(0.2),
+            nn.Linear(hidden, hidden),
+            nn.GELU(),
+            nn.Dropout(0.2),
+            nn.Linear(hidden, hidden // 2),
+            nn.GELU(),
+            nn.Linear(hidden // 2, 3),  # (dx, dy, dz)
+        )
+
+    def forward(self, geom_feats, dino_feats):
+        x = torch.cat([geom_feats, dino_feats], dim=1)
+        return self.net(x)
+
+
+def label_vertex_offsets(pv, gt_v, match_radius: float = 0.5):
+    """Return (V, 3) target offsets: vertex moves toward nearest GT within radius.
+
+    For vertices with no GT match within radius, target = (0, 0, 0).
+    Mask (V,) is 1 where we have valid GT to learn from.
+    """
+    pv_arr = np.asarray(pv, dtype=np.float32)
+    gt_v_arr = np.asarray(gt_v, dtype=np.float32)
+    V = pv_arr.shape[0]
+    offsets = np.zeros((V, 3), dtype=np.float32)
+    mask = np.zeros(V, dtype=np.float32)
+    if V == 0 or gt_v_arr.shape[0] == 0:
+        return offsets, mask
+    from scipy.spatial import cKDTree
+    tree = cKDTree(gt_v_arr)
+    dists, idxs = tree.query(pv_arr)
+    keep = dists <= match_radius
+    offsets[keep] = gt_v_arr[idxs[keep]] - pv_arr[keep]
+    mask[keep] = 1.0
+    return offsets, mask
+
+
+def refine_vertices_with_regressor(pv, pe, sample, regressor, dino, device="cpu",
+                                   feature_mean=None, feature_std=None,
+                                   edge_feat_mean=None, edge_feat_std=None,
+                                   max_move_meters: float = 0.4,
+                                   min_views_for_move: int = 2):
+    """Apply regressor to predict per-vertex offsets, clamp by max_move."""
+    try:
+        pv_arr = np.asarray(pv, dtype=np.float32)
+        if pv_arr.shape[0] == 0:
+            return pv, pe
+        geom, dino_feats = extract_vertex_features_v4(pv, pe, sample, dino, device=device)
+        # Only move vertices visible in enough views (sanity)
+        in_view_count = geom[:, 4].astype(np.int32)  # feature[4] is num views vertex is in-frame
+
+        if feature_mean is not None and feature_std is not None:
+            geom_n = (geom - feature_mean) / (feature_std + 1e-6)
+        else:
+            geom_n = geom
+        if edge_feat_mean is not None and edge_feat_std is not None:
+            dino_n = (dino_feats - edge_feat_mean) / (edge_feat_std + 1e-6)
+        else:
+            dino_n = dino_feats
+
+        with torch.no_grad():
+            g = torch.tensor(geom_n, dtype=torch.float32)
+            d = torch.tensor(dino_n, dtype=torch.float32)
+            offsets = regressor(g, d).numpy()  # (V, 3)
+
+        # Clamp magnitude
+        norms = np.linalg.norm(offsets, axis=1, keepdims=True)
+        scale = np.clip(max_move_meters / np.maximum(norms, 1e-9), 0, 1)
+        clamped = offsets * scale
+
+        # Don't move vertices with too few view supports
+        no_move = in_view_count < min_views_for_move
+        clamped[no_move] = 0
+
+        new_pv = pv_arr + clamped
+        return new_pv.astype(np.float64), pe
+    except Exception:
+        return pv, pe
+
+
+def load_regressor_v4(path: str, device: str = "cpu"):
+    blob = torch.load(path, map_location=device, weights_only=False)
+    m = VertexRegressorV4(hidden=blob.get("hidden", 128))
+    m.load_state_dict(blob["model"])
+    m.to(device).eval()
+    return (m, blob.get("feature_mean"), blob.get("feature_std"),
+            blob.get("edge_feat_mean"), blob.get("edge_feat_std"))