Add missing core Python files

bundle_adjust.py

@@ -0,0 +1,221 @@
+"""Post-hoc bundle adjustment of merged 3D wireframe vertices.
+
+For each vertex in ``merged_v``, we:
+1. Project its current 3D position into every available view.
+2. Find the nearest gestalt corner (from ``get_vertices_and_edges_improved``)
+   in each view within ``match_px`` pixels.
+3. If observations are found in ≥ ``min_views`` views, refine the 3D
+   position to minimise the sum of squared reprojection errors via
+   ``scipy.optimize.least_squares`` with a Huber loss.
+
+Cameras are fixed (COLMAP cameras are accurate). Only vertex positions
+are optimised.  No thresholds are tuned — just pure geometric
+optimisation that converges to the correct answer given the cameras.
+
+Entry point: ``refine_vertices_ba(merged_v, entry)``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import cv2
+from scipy.optimize import least_squares
+
+from hoho2025.example_solutions import (
+    convert_entry_to_human_readable,
+    filter_vertices_by_background,
+)
+from hoho2025.color_mappings import gestalt_color_mapping
+
+try:
+    from mvs_utils import collect_views, project_world_to_image
+except ImportError:
+    from submission.mvs_utils import collect_views, project_world_to_image
+
+
+VERTEX_CLASSES = ['apex', 'eave_end_point', 'flashing_end_point']
+
+
+def _detect_2d_corners(gest_np):
+    """Detect 2D gestalt corners in a single view (same as pipeline).
+
+    Returns (N, 2) float32 array of pixel coordinates.
+    """
+    corners = []
+    for v_class in VERTEX_CLASSES:
+        color = np.array(gestalt_color_mapping[v_class])
+        mask = cv2.inRange(gest_np, color - 0.5, color + 0.5)
+        if mask.sum() == 0:
+            continue
+        _, _, _, centroids = cv2.connectedComponentsWithStats(mask, 8, cv2.CV_32S)
+        for c in centroids[1:]:
+            corners.append(c)
+    if not corners:
+        return np.empty((0, 2), dtype=np.float32)
+    return np.array(corners, dtype=np.float32)
+
+
+def _collect_observations(
+    merged_v: np.ndarray,
+    views: dict,
+    corners_per_view: dict[str, np.ndarray],
+    match_px: float = 8.0,
+) -> list[list[tuple[str, np.ndarray]]]:
+    """For each vertex, find its 2D observation in each view.
+
+    Returns a list (one per vertex) of lists of ``(view_id, uv_observed)``.
+    """
+    n = len(merged_v)
+    observations: list[list[tuple[str, np.ndarray]]] = [[] for _ in range(n)]
+
+    for vid, info in views.items():
+        corners_2d = corners_per_view.get(vid)
+        if corners_2d is None or len(corners_2d) == 0:
+            continue
+        P = info['P']
+        # Project all merged_v into this view
+        uv, z = project_world_to_image(P, merged_v)
+        H, W = info['height'], info['width']
+        for i in range(n):
+            if z[i] <= 0:
+                continue
+            u, v_px = uv[i]
+            if u < -50 or u > W + 50 or v_px < -50 or v_px > H + 50:
+                continue
+            # Find nearest 2D corner
+            d = np.linalg.norm(corners_2d - uv[i], axis=1)
+            j = int(np.argmin(d))
+            if d[j] <= match_px:
+                observations[i].append((vid, corners_2d[j].copy()))
+
+    return observations
+
+
+def _ba_residuals(params, Ps, obs_2d):
+    """Reprojection residuals for a single 3D point.
+
+    params: (3,) — x, y, z of the 3D point.
+    Ps: list of (3, 4) projection matrices.
+    obs_2d: list of (2,) observed 2D points.
+
+    Returns: (2*N,) residual vector.
+    """
+    X = params
+    res = []
+    homog = np.array([X[0], X[1], X[2], 1.0])
+    for P, uv_obs in zip(Ps, obs_2d):
+        proj = P @ homog
+        if proj[2] <= 1e-6:
+            res.extend([100.0, 100.0])  # large penalty
+            continue
+        u = proj[0] / proj[2]
+        v = proj[1] / proj[2]
+        res.extend([u - uv_obs[0], v - uv_obs[1]])
+    return np.array(res, dtype=np.float64)
+
+
+def refine_vertices_ba(
+    merged_v: np.ndarray,
+    entry,
+    match_px: float = 8.0,
+    min_views: int = 2,
+    max_reproj_px: float = 5.0,
+    min_initial_err_px: float = 3.0,
+) -> np.ndarray:
+    """Refine 3D vertex positions via bundle adjustment.
+
+    Only vertices with observations in ≥ ``min_views`` views are refined;
+    the rest keep their original positions. If the optimised position has
+    a mean reprojection error > ``max_reproj_px``, the original position
+    is kept (optimiser diverged).
+
+    Parameters
+    ----------
+    merged_v : (N, 3) array of vertex positions.
+    entry : the raw dataset sample (passed to ``convert_entry_to_human_readable``).
+    match_px : maximum pixel distance to match a projected vertex to a
+        gestalt corner in a view.
+    min_views : minimum number of views with a matching observation for
+        BA to fire.
+    max_reproj_px : if post-BA mean reprojection error exceeds this,
+        revert to the original position.
+
+    Returns
+    -------
+    refined_v : (N, 3) array with refined positions.
+    """
+    merged_v = np.asarray(merged_v, dtype=np.float64)
+    refined = merged_v.copy()
+
+    if len(merged_v) == 0:
+        return refined
+
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return refined
+
+    views = collect_views(colmap_rec, good['image_ids'])
+    if len(views) < 2:
+        return refined
+
+    # Detect 2D corners in each view
+    corners_per_view: dict[str, np.ndarray] = {}
+    for gest, depth, img_id in zip(good['gestalt'], good['depth'], good['image_ids']):
+        if img_id not in views:
+            continue
+        depth_np = np.array(depth)
+        H, W = depth_np.shape[:2]
+        gest_np = np.array(gest.resize((W, H))).astype(np.uint8)
+        corners_per_view[img_id] = _detect_2d_corners(gest_np)
+
+    # Collect multi-view observations for each vertex
+    observations = _collect_observations(merged_v, views, corners_per_view, match_px)
+
+    # Run BA on each vertex independently.
+    # Key: only refine vertices whose INITIAL reprojection error is high
+    # (> min_initial_err_px). This targets the depth-estimation failures
+    # without disturbing already-good vertices.
+    n_refined = 0
+    for i in range(len(merged_v)):
+        obs = observations[i]
+        if len(obs) < min_views:
+            continue
+
+        Ps = [views[vid]['P'] for vid, _ in obs]
+        pts_2d = [uv for _, uv in obs]
+
+        x0 = merged_v[i].copy()
+
+        # Check initial reprojection error — skip if already low.
+        res0 = _ba_residuals(x0, Ps, pts_2d)
+        res0_pairs = res0.reshape(-1, 2)
+        initial_err = float(np.sqrt((res0_pairs ** 2).sum(axis=1)).mean())
+        if initial_err <= min_initial_err_px:
+            continue  # already well-localised, leave it alone
+
+        try:
+            result = least_squares(
+                _ba_residuals, x0,
+                args=(Ps, pts_2d),
+                method='trf',
+                loss='huber',
+                f_scale=2.0,
+                max_nfev=50,
+            )
+        except Exception:
+            continue
+
+        X_opt = result.x
+        # Sanity: check post-BA reprojection error and displacement.
+        res = _ba_residuals(X_opt, Ps, pts_2d)
+        res_pairs = res.reshape(-1, 2)
+        final_err = float(np.sqrt((res_pairs ** 2).sum(axis=1)).mean())
+        displacement = float(np.linalg.norm(X_opt - x0))
+
+        # Accept only if: (a) reproj improved, (b) didn't move too far.
+        if final_err < initial_err and final_err <= max_reproj_px and displacement <= 2.0:
+            refined[i] = X_opt
+            n_refined += 1
+
+    return refined

colmap_refine.py

@@ -0,0 +1,240 @@
+"""COLMAP-based vertex position refinement.
+
+Two complementary refinement strategies that use the COLMAP sparse point
+cloud as a high-precision 3D landmark source:
+
+1. ``refine_vertices_3d_plane`` — Variant (a+c).
+   For each merged_v vertex, find its K nearest COLMAP points in 3D,
+   fit a local plane, and project the vertex onto that plane. Cancels
+   depth-noise residuals after the initial unprojection.
+
+2. ``refine_vertices_multiview_plane`` — Variant (b).
+   For each merged_v vertex, project it into every view, find the K
+   nearest COLMAP points in 2D within each view's image, fit a local
+   plane in 3D from those points, project the vertex onto the plane,
+   and average the resulting 3D positions across views weighted by the
+   plane fit quality.
+
+Both methods only use ``pycolmap`` + ``numpy`` + ``scipy``. Purely
+geometric — no thresholds tuned on local validation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+from hoho2025.example_solutions import convert_entry_to_human_readable
+
+try:
+    from mvs_utils import collect_views, project_world_to_image
+except ImportError:
+    from submission.mvs_utils import collect_views, project_world_to_image
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _fit_plane_pca(points: np.ndarray) -> tuple[np.ndarray, np.ndarray, float]:
+    """PCA plane fit. Returns (centroid, unit_normal, fit_quality).
+
+    fit_quality = 1 - (smallest_eigval / largest_eigval). 1.0 = perfectly
+    planar, 0.0 = sphere. Used as a weight when combining multi-view
+    refinements.
+    """
+    centroid = points.mean(axis=0)
+    centred = points - centroid
+    # SVD instead of eig to be numerically stable on small N
+    _, s, Vt = np.linalg.svd(centred, full_matrices=False)
+    if len(s) < 3:
+        return centroid, np.array([0.0, 1.0, 0.0]), 0.0
+    normal = Vt[2]  # smallest variance direction
+    # quality: ratio of last to first singular value, inverted
+    if s[0] < 1e-9:
+        return centroid, normal, 0.0
+    quality = 1.0 - float(s[2] / s[0])
+    return centroid, normal, max(0.0, min(1.0, quality))
+
+
+def _project_point_to_plane(
+    point: np.ndarray, plane_centroid: np.ndarray, plane_normal: np.ndarray,
+) -> np.ndarray:
+    """Orthogonal projection of ``point`` onto a plane defined by
+    ``(centroid, unit normal)``.
+    """
+    rel = point - plane_centroid
+    d = float(np.dot(rel, plane_normal))
+    return point - d * plane_normal
+
+
+# ---------------------------------------------------------------------------
+# Variant (a+c): 3D KD-tree neighbours → local plane → snap
+# ---------------------------------------------------------------------------
+
+def refine_vertices_3d_plane(
+    vertices: np.ndarray,
+    colmap_xyz: np.ndarray,
+    knn_radius: float = 0.5,
+    knn_k: int = 12,
+    min_neighbours: int = 6,
+    max_displacement: float = 0.5,
+    min_quality: float = 0.6,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Refine each vertex by snapping to a local plane fit through its
+    nearest COLMAP neighbours in 3D.
+
+    Parameters
+    ----------
+    vertices : (N, 3) array of merged 3D vertex positions.
+    colmap_xyz : (M, 3) all COLMAP points3D world coordinates.
+    knn_radius : maximum distance for a neighbour to count.
+    knn_k : maximum number of neighbours to use (for speed).
+    min_neighbours : refuse to refine when fewer neighbours found.
+    max_displacement : reject the snap if it moves the vertex by more
+        than this many metres (likely a wall plane, not the roof).
+    min_quality : reject when the local plane fit is not flat enough
+        (PCA quality below this).
+
+    Returns
+    -------
+    refined : (N, 3) refined vertex positions.
+    snapped : (N,)  bool — which vertices were moved.
+    """
+    verts = np.asarray(vertices, dtype=np.float64)
+    refined = verts.copy()
+    snapped = np.zeros(len(verts), dtype=bool)
+
+    if len(verts) == 0 or len(colmap_xyz) < min_neighbours:
+        return refined, snapped
+
+    tree = cKDTree(colmap_xyz)
+    for i, v in enumerate(verts):
+        idx = tree.query_ball_point(v, knn_radius)
+        if len(idx) < min_neighbours:
+            continue
+        if len(idx) > knn_k:
+            # Pick the closest knn_k of the candidates
+            d = np.linalg.norm(colmap_xyz[idx] - v, axis=1)
+            order = np.argsort(d)[:knn_k]
+            idx = [idx[j] for j in order]
+
+        nbrs = colmap_xyz[idx]
+        centroid, normal, quality = _fit_plane_pca(nbrs)
+        if quality < min_quality:
+            continue
+
+        projected = _project_point_to_plane(v, centroid, normal)
+        if float(np.linalg.norm(projected - v)) > max_displacement:
+            continue
+        refined[i] = projected
+        snapped[i] = True
+
+    return refined, snapped
+
+
+# ---------------------------------------------------------------------------
+# Variant (b): multi-view consensus plane refinement
+# ---------------------------------------------------------------------------
+
+def refine_vertices_multiview_plane(
+    vertices: np.ndarray,
+    entry,
+    knn_2d_px: float = 30.0,
+    knn_k: int = 12,
+    min_neighbours: int = 6,
+    max_displacement: float = 0.5,
+    min_quality: float = 0.5,
+    min_views: int = 2,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Multi-view consensus refinement.
+
+    For each vertex:
+      1. Project it into every available view.
+      2. In each view, find COLMAP points whose own 2D projection is
+         within ``knn_2d_px`` of the vertex projection.
+      3. Take the corresponding 3D points and fit a local plane.
+      4. Project the vertex onto that plane → one candidate 3D position
+         per view, weighted by the plane's PCA quality.
+      5. Combine the per-view candidates as a quality-weighted mean.
+
+    Crucially, the 2D pixel neighbourhood ensures the COLMAP points used
+    for the plane fit are the **ones the camera sees near this vertex** —
+    not just close in 3D — so it does not blend roof + wall + ground
+    points like a 3D KNN would.
+
+    Returns ``(refined, snapped)`` arrays in the same shape as the input.
+    """
+    verts = np.asarray(vertices, dtype=np.float64)
+    refined = verts.copy()
+    snapped = np.zeros(len(verts), dtype=bool)
+
+    if len(verts) == 0:
+        return refined, snapped
+
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return refined, snapped
+
+    views = collect_views(colmap_rec, good['image_ids'])
+    if len(views) < 1:
+        return refined, snapped
+
+    colmap_xyz = np.array(
+        [p.xyz for p in colmap_rec.points3D.values()], dtype=np.float64
+    )
+    if len(colmap_xyz) < min_neighbours:
+        return refined, snapped
+
+    # Pre-project all COLMAP points into each view once
+    per_view_proj: dict[str, tuple[np.ndarray, np.ndarray]] = {}
+    for vid, info in views.items():
+        uv, z = project_world_to_image(info['P'], colmap_xyz)
+        in_front = z > 0
+        per_view_proj[vid] = (uv[in_front], np.where(in_front)[0])
+
+    for i, v in enumerate(verts):
+        candidates: list[tuple[np.ndarray, float]] = []
+        for vid, info in views.items():
+            uv_v, z_v = project_world_to_image(info['P'], v.reshape(1, 3))
+            if z_v[0] <= 0:
+                continue
+            target_uv = uv_v[0]
+            H, W = info['height'], info['width']
+            if not (0 <= target_uv[0] < W and 0 <= target_uv[1] < H):
+                continue
+            view_uv, view_idx = per_view_proj[vid]
+            if len(view_uv) == 0:
+                continue
+            d = np.linalg.norm(view_uv - target_uv, axis=1)
+            mask = d <= knn_2d_px
+            if mask.sum() < min_neighbours:
+                continue
+            cand_idx = view_idx[mask]
+            d_in = d[mask]
+            if len(cand_idx) > knn_k:
+                order = np.argsort(d_in)[:knn_k]
+                cand_idx = cand_idx[order]
+            nbrs = colmap_xyz[cand_idx]
+            centroid, normal, quality = _fit_plane_pca(nbrs)
+            if quality < min_quality:
+                continue
+            projected = _project_point_to_plane(v, centroid, normal)
+            if float(np.linalg.norm(projected - v)) > max_displacement:
+                continue
+            candidates.append((projected, quality))
+
+        if len(candidates) < min_views:
+            continue
+
+        # Quality-weighted mean
+        weights = np.array([c[1] for c in candidates], dtype=np.float64)
+        positions = np.array([c[0] for c in candidates], dtype=np.float64)
+        if weights.sum() < 1e-6:
+            continue
+        new_pos = (positions * weights[:, None]).sum(axis=0) / weights.sum()
+        refined[i] = new_pos
+        snapped[i] = True
+
+    return refined, snapped

depth_edges.py

@@ -0,0 +1,217 @@
+"""Depth-discontinuity edge source.
+
+Independent from the gestalt segmentation: extracts 2D line segments
+along sharp depth jumps inside the house silhouette, lifts them to 3D
+via the affine-fitted depth map, then merges across views.
+
+Pipeline:
+1. Affine-fit COLMAP-calibrated depth (same as the rest of the pipeline).
+2. Inside the eroded ADE20k house mask, run Canny on normalised depth.
+3. Connected components → fit 2D line per component.
+4. Sample N depth values along each 2D segment, unproject to 3D.
+5. RANSAC-fit a 3D line through the unprojected samples.
+6. Merge lines across views (direction + midpoint proximity).
+
+The merged 3D lines have endpoints (p1, p2) suitable for the same
+'edges-only lift onto merged_v' integration that v11 does for gestalt
+line cloud. Since gestalt and depth-discontinuity sources are independent,
+their lifts should be additive.
+
+Entry point:
+    extract_depth_3d_lines(entry) -> list[Line3D]
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import cv2
+
+from hoho2025.example_solutions import (
+    convert_entry_to_human_readable,
+    get_sparse_depth, get_house_mask,
+)
+
+try:
+    from line_cloud import Line3D, _fit_3d_line_ransac, _unproject_pixel, merge_3d_lines
+    from mvs_utils import collect_views
+    from sklearn_submission import fit_affine_ransac
+except ImportError:
+    from submission.line_cloud import Line3D, _fit_3d_line_ransac, _unproject_pixel, merge_3d_lines
+    from submission.mvs_utils import collect_views
+    from submission.sklearn_submission import fit_affine_ransac
+
+
+def _detect_depth_segments_2d(
+    depth_fitted: np.ndarray,
+    house_mask: np.ndarray,
+    canny_lo: int = 30,
+    canny_hi: int = 80,
+    erode_px: int = 9,
+    min_area_px: int = 20,
+    min_seglen_px: int = 25,
+):
+    """Return list of (xs, ys, p1, p2) for each detected 2D line segment."""
+    if depth_fitted.size == 0:
+        return []
+    H, W = depth_fitted.shape[:2]
+    eroded = cv2.erode(
+        house_mask.astype(np.uint8),
+        np.ones((erode_px, erode_px), np.uint8),
+    ).astype(bool)
+    if eroded.sum() < 100:
+        return []
+
+    # Normalise depth inside the eroded house mask to [0, 255]
+    d_in = depth_fitted.copy()
+    in_d = d_in[eroded]
+    if in_d.size == 0:
+        return []
+    d_min, d_max = float(in_d.min()), float(in_d.max())
+    if d_max - d_min < 0.5:
+        return []
+    d_norm = np.clip((d_in - d_min) / (d_max - d_min), 0.0, 1.0)
+    d_u8 = (d_norm * 255).astype(np.uint8)
+    d_u8 = cv2.GaussianBlur(d_u8, (5, 5), 0)
+
+    canny = cv2.Canny(d_u8, canny_lo, canny_hi)
+    canny[~eroded] = 0
+    if canny.sum() == 0:
+        return []
+
+    n_lbl, lbl, stats, _ = cv2.connectedComponentsWithStats(canny, 8)
+    out = []
+    for i in range(1, n_lbl):
+        area = int(stats[i, cv2.CC_STAT_AREA])
+        if area < min_area_px:
+            continue
+        ys, xs = np.where(lbl == i)
+        if len(xs) < 3:
+            continue
+        pts = np.column_stack([xs, ys]).astype(np.float32)
+        line = cv2.fitLine(pts, cv2.DIST_L2, 0, 0.01, 0.01)
+        vx, vy, x0, y0 = line.ravel()
+        proj = (xs - x0) * vx + (ys - y0) * vy
+        t_min, t_max = float(proj.min()), float(proj.max())
+        seglen = t_max - t_min
+        if seglen < min_seglen_px:
+            continue
+        p1 = np.array([x0 + t_min * vx, y0 + t_min * vy])
+        p2 = np.array([x0 + t_max * vx, y0 + t_max * vy])
+        out.append((xs, ys, p1, p2, (vx, vy, x0, y0, t_min, t_max)))
+    return out
+
+
+def extract_depth_3d_lines_single_view(
+    depth_fitted: np.ndarray,
+    house_mask: np.ndarray,
+    view_info: dict,
+    n_samples: int = 30,
+) -> list[Line3D]:
+    """Extract 3D lines from depth discontinuities in a single view."""
+    H, W = depth_fitted.shape[:2]
+    K = view_info['K']
+    R = view_info['R']
+    t = view_info['t']
+    K_inv = np.linalg.inv(K)
+    R_inv = R.T
+    cam_center = -R_inv @ t
+
+    segments = _detect_depth_segments_2d(depth_fitted, house_mask)
+    out: list[Line3D] = []
+    view_id = view_info['image_id']
+
+    for _, _, _, _, params in segments:
+        vx, vy, x0, y0, t_min, t_max = params
+        ts = np.linspace(t_min, t_max, n_samples)
+        pts3d_list = []
+        for tv in ts:
+            u = x0 + tv * vx
+            v_px = y0 + tv * vy
+            ui, vi = int(round(u)), int(round(v_px))
+            if 0 <= ui < W and 0 <= vi < H:
+                d = depth_fitted[vi, ui]
+                p = _unproject_pixel(u, v_px, d, K_inv, R_inv, cam_center)
+                if p is not None:
+                    pts3d_list.append(p)
+
+        if len(pts3d_list) < 5:
+            continue
+
+        pts3d = np.array(pts3d_list, dtype=np.float64)
+        result = _fit_3d_line_ransac(pts3d, n_iter=50, inlier_th=0.3, min_inliers=5)
+        if result is None:
+            continue
+        centroid, direction, inlier_pts = result
+        s = (inlier_pts - centroid) @ direction
+        p1 = centroid + float(s.min()) * direction
+        p2 = centroid + float(s.max()) * direction
+        length = float(np.linalg.norm(p2 - p1))
+        if length < 0.4:
+            continue
+
+        out.append(Line3D(
+            point=centroid,
+            direction=direction,
+            p1=p1, p2=p2,
+            length=length,
+            n_inliers=len(inlier_pts),
+            edge_class='depth_discontinuity',
+            view_id=view_id,
+        ))
+    return out
+
+
+def extract_depth_3d_lines(entry) -> tuple[list[Line3D], dict]:
+    """Extract depth-discontinuity 3D lines from all views.
+
+    Returns (all_lines, good_entry).
+    """
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return [], good
+
+    views = collect_views(colmap_rec, good['image_ids'])
+    all_lines: list[Line3D] = []
+
+    for gest, depth, img_id, ade_seg in zip(
+        good['gestalt'], good['depth'], good['image_ids'], good['ade']
+    ):
+        info = views.get(img_id)
+        if info is None:
+            continue
+        depth_np = np.array(depth).astype(np.float64) / 1000.0
+        H, W = depth_np.shape[:2]
+
+        # Affine fit (same as main pipeline)
+        try:
+            depth_sparse, found, _, _ = get_sparse_depth(colmap_rec, img_id, depth_np)
+            if found:
+                _, _, depth_np = fit_affine_ransac(
+                    depth_np, depth_sparse, get_house_mask(ade_seg),
+                )
+        except Exception:
+            pass
+
+        try:
+            house = get_house_mask(ade_seg)
+            house_resized = cv2.resize(
+                house.astype(np.uint8), (W, H), interpolation=cv2.INTER_NEAREST,
+            ) > 0
+        except Exception:
+            continue
+
+        view_lines = extract_depth_3d_lines_single_view(
+            depth_np, house_resized, info,
+        )
+        all_lines.extend(view_lines)
+
+    return all_lines, good
+
+
+def extract_and_merge_depth_lines(entry) -> list[Line3D]:
+    """Convenience: extract + merge across views."""
+    lines, _ = extract_depth_3d_lines(entry)
+    if not lines:
+        return []
+    return merge_3d_lines(lines)

dgcnn.py

@@ -0,0 +1,181 @@
+"""DGCNN backbone — drop-in replacement for PointNet.
+
+EdgeConv with dynamic graph KNN captures local geometric structure
+better than PointNet's global aggregation.
+
+Ref: Wang et al., "Dynamic Graph CNN for Learning on Point Clouds", TOG 2019
+     https://github.com/antao97/dgcnn.pytorch
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+def knn(x, k):
+    """Compute KNN graph. x: (B, C, N). Returns (B, N, k) indices."""
+    inner = -2 * torch.matmul(x.transpose(2, 1), x)  # (B, N, N)
+    xx = torch.sum(x ** 2, dim=1, keepdim=True)       # (B, 1, N)
+    pairwise_dist = -xx - inner - xx.transpose(2, 1)   # (B, N, N) negative distances
+    idx = pairwise_dist.topk(k=k, dim=-1)[1]           # (B, N, k)
+    return idx
+
+
+def get_graph_feature(x, k=20, idx=None):
+    """Build edge features for EdgeConv.
+
+    For each point, concatenate [x_j - x_i, x_i] for its k neighbors.
+    Returns (B, 2*C, N, k).
+    """
+    B, C, N = x.shape
+    device = x.device
+
+    if idx is None:
+        idx = knn(x, k=k)  # (B, N, k)
+
+    idx_base = torch.arange(0, B, device=device).view(-1, 1, 1) * N
+    idx = idx + idx_base
+    idx = idx.view(-1)
+
+    x = x.transpose(2, 1).contiguous()  # (B, N, C)
+    feature = x.view(B * N, -1)[idx, :]  # (B*N*k, C)
+    feature = feature.view(B, N, k, C)
+
+    x = x.view(B, N, 1, C).repeat(1, 1, k, 1)  # (B, N, k, C)
+
+    feature = torch.cat((feature - x, x), dim=3).permute(0, 3, 1, 2).contiguous()
+    # (B, 2*C, N, k)
+    return feature
+
+
+class EdgeConv(nn.Module):
+    """Single EdgeConv layer."""
+
+    def __init__(self, in_channels, out_channels, k=20):
+        super().__init__()
+        self.k = k
+        self.conv = nn.Sequential(
+            nn.Conv2d(in_channels * 2, out_channels, 1, bias=False),
+            nn.BatchNorm2d(out_channels),
+            nn.LeakyReLU(0.2, inplace=True),
+        )
+
+    def forward(self, x):
+        # x: (B, C, N)
+        feat = get_graph_feature(x, k=self.k)  # (B, 2*C, N, k)
+        feat = self.conv(feat)                  # (B, out, N, k)
+        feat = feat.max(dim=-1)[0]              # (B, out, N)
+        return feat
+
+
+class DGCNNBackbone(nn.Module):
+    """DGCNN backbone with multiple EdgeConv layers.
+
+    Same interface as PointNetBackbone: (B, C, N) → (B, out_dim).
+    """
+
+    def __init__(self, in_channels, k=20, emb_dims=1024):
+        super().__init__()
+        self.k = k
+
+        self.edge_conv1 = EdgeConv(in_channels, 64, k)
+        self.edge_conv2 = EdgeConv(64, 64, k)
+        self.edge_conv3 = EdgeConv(64, 128, k)
+        self.edge_conv4 = EdgeConv(128, 256, k)
+
+        # Aggregate all EdgeConv outputs
+        self.conv5 = nn.Sequential(
+            nn.Conv1d(64 + 64 + 128 + 256, emb_dims, 1, bias=False),
+            nn.BatchNorm1d(emb_dims),
+            nn.LeakyReLU(0.2, inplace=True),
+        )
+
+        self.out_dim = emb_dims * 2  # max + avg pooling
+
+    def forward(self, x):
+        """
+        Args:
+            x: (B, C, N)
+        Returns:
+            global_feat: (B, out_dim)
+        """
+        x1 = self.edge_conv1(x)   # (B, 64, N)
+        x2 = self.edge_conv2(x1)  # (B, 64, N)
+        x3 = self.edge_conv3(x2)  # (B, 128, N)
+        x4 = self.edge_conv4(x3)  # (B, 256, N)
+
+        x_cat = torch.cat([x1, x2, x3, x4], dim=1)  # (B, 512, N)
+        x5 = self.conv5(x_cat)                        # (B, emb_dims, N)
+
+        x_max = x5.max(dim=-1)[0]   # (B, emb_dims)
+        x_avg = x5.mean(dim=-1)     # (B, emb_dims)
+        global_feat = torch.cat([x_max, x_avg], dim=1)  # (B, 2*emb_dims)
+        return global_feat
+
+
+class DGCNNVertexClassifier(nn.Module):
+    """DGCNN vertex classifier — same heads as PointNet version."""
+
+    def __init__(self, in_channels=11, k=10, emb_dims=512):
+        super().__init__()
+        self.backbone = DGCNNBackbone(in_channels, k, emb_dims)
+        feat_dim = self.backbone.out_dim
+
+        self.cls_head = nn.Sequential(
+            nn.Linear(feat_dim, 512),
+            nn.BatchNorm1d(512),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(512, 128),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Linear(128, 1),
+        )
+
+        self.offset_head = nn.Sequential(
+            nn.Linear(feat_dim, 512),
+            nn.BatchNorm1d(512),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(512, 128),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Linear(128, 3),
+        )
+
+        self.conf_head = nn.Sequential(
+            nn.Linear(feat_dim, 256),
+            nn.BatchNorm1d(256),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Linear(256, 1),
+            nn.Sigmoid(),
+        )
+
+    def forward(self, x):
+        feat = self.backbone(x)
+        cls_logits = self.cls_head(feat)
+        offset = self.offset_head(feat)
+        confidence = self.conf_head(feat)
+        return cls_logits, offset, confidence
+
+
+class DGCNNEdgeClassifier(nn.Module):
+    """DGCNN edge classifier — same heads as PointNet version."""
+
+    def __init__(self, in_channels=6, k=10, emb_dims=256):
+        super().__init__()
+        self.backbone = DGCNNBackbone(in_channels, k, emb_dims)
+        feat_dim = self.backbone.out_dim
+
+        self.head = nn.Sequential(
+            nn.Linear(feat_dim, 512),
+            nn.BatchNorm1d(512),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Dropout(0.5),
+            nn.Linear(512, 256),
+            nn.LeakyReLU(0.2, inplace=True),
+            nn.Dropout(0.3),
+            nn.Linear(256, 1),
+        )
+
+    def forward(self, x):
+        feat = self.backbone(x)
+        return self.head(feat)

junction.py

@@ -0,0 +1,193 @@
+"""Junction-type constraints for 3D roof wireframes.
+
+After merging per-view detections into a 3D graph, we apply simple topology
+priors to drop obviously wrong edges/vertices:
+
+1. Collinear merge: if a vertex has degree 2 with two nearly antiparallel edges,
+   it is most likely a spurious point on a longer edge — merge the edges and
+   drop the vertex.
+2. Duplicate-direction prune: if a vertex has two incident edges that point in
+   (nearly) the same direction, keep only the stronger one (stronger = higher
+   sklearn score if available, else longer edge).
+3. Isolated leaf prune: vertices with degree 1 whose only edge is very short
+   (< 0.4 m) are dropped — they are almost always noise.
+
+The module is intentionally pure-numpy and side-effect-free so it can be
+dropped into both the heuristic and the triangulation pipelines.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from typing import Sequence
+
+
+def _edge_directions(vertices: np.ndarray, edges: np.ndarray) -> np.ndarray:
+    """Unit vectors for each edge (from a→b). Shape (E, 3)."""
+    if len(edges) == 0:
+        return np.empty((0, 3), dtype=np.float32)
+    diffs = vertices[edges[:, 1]] - vertices[edges[:, 0]]
+    norms = np.linalg.norm(diffs, axis=1, keepdims=True)
+    norms = np.where(norms < 1e-6, 1.0, norms)
+    return diffs / norms
+
+
+def _build_adj(n_vertices: int, edges: np.ndarray):
+    """Return list[list[(neighbour, edge_index)]]."""
+    adj = [[] for _ in range(n_vertices)]
+    for ei, (a, b) in enumerate(edges):
+        adj[int(a)].append((int(b), ei))
+        adj[int(b)].append((int(a), ei))
+    return adj
+
+
+def apply_junction_constraints(
+    vertices: np.ndarray,
+    edges: Sequence[tuple],
+    edge_scores: np.ndarray | None = None,
+    collinear_cos: float = 0.97,
+    duplicate_cos: float = 0.985,
+    leaf_min_len: float = 0.4,
+    max_passes: int = 3,
+) -> tuple[np.ndarray, list]:
+    """Apply junction-type constraints to a 3D wireframe.
+
+    Parameters
+    ----------
+    vertices : (N, 3) array of 3D vertex positions.
+    edges : list of (i, j) undirected edges.
+    edge_scores : optional (E,) array in [0, 1] giving edge confidence.
+        When missing, all edges are treated as equal (tie-break by length).
+    collinear_cos : cosine threshold above which two incident edges are
+        considered antiparallel → triggers collinear merge.
+    duplicate_cos : cosine threshold above which two incident edges pointing
+        the same way are treated as duplicates → keep only the stronger one.
+    leaf_min_len : edges shorter than this feeding a degree-1 vertex get cut.
+    max_passes : how many passes to iterate since removing one edge can
+        create new opportunities.
+
+    Returns
+    -------
+    (vertices_new, edges_new) where vertices_new may keep indices identical
+    to the input (we do not reindex; instead we return only the surviving
+    subset of edges). Fully-isolated vertices are filtered by callers that
+    already run `prune_not_connected`.
+    """
+    verts = np.asarray(vertices, dtype=np.float32)
+    edges_arr = np.asarray(list(edges), dtype=np.int64) if len(edges) else np.empty((0, 2), dtype=np.int64)
+
+    if len(edges_arr) == 0 or len(verts) == 0:
+        return verts, list(edges)
+
+    if edge_scores is None:
+        scores = np.ones(len(edges_arr), dtype=np.float32)
+    else:
+        scores = np.asarray(edge_scores, dtype=np.float32)
+        if len(scores) != len(edges_arr):
+            scores = np.ones(len(edges_arr), dtype=np.float32)
+
+    alive = np.ones(len(edges_arr), dtype=bool)
+
+    for _ in range(max_passes):
+        changed = False
+        directions = _edge_directions(verts, edges_arr)
+        lengths = np.linalg.norm(
+            verts[edges_arr[:, 1]] - verts[edges_arr[:, 0]], axis=1
+        )
+        adj = _build_adj(len(verts), edges_arr[alive])
+
+        # We need the original edge indices, not the compacted ones, for mutation.
+        # Rebuild adjacency using absolute indices.
+        adj = [[] for _ in range(len(verts))]
+        for ei, (a, b) in enumerate(edges_arr):
+            if not alive[ei]:
+                continue
+            adj[int(a)].append((int(b), ei))
+            adj[int(b)].append((int(a), ei))
+
+        # Pass 1: collinear merge on degree-2 vertices
+        for v in range(len(verts)):
+            if len(adj[v]) != 2:
+                continue
+            (n1, e1), (n2, e2) = adj[v]
+            if n1 == n2:
+                continue
+            # Direction from v outward
+            d1 = verts[n1] - verts[v]
+            d2 = verts[n2] - verts[v]
+            l1, l2 = np.linalg.norm(d1), np.linalg.norm(d2)
+            if l1 < 1e-6 or l2 < 1e-6:
+                continue
+            d1 /= l1
+            d2 /= l2
+            # Antiparallel = straight line through v
+            if float(np.dot(d1, d2)) < -collinear_cos:
+                # Merge: kill e1, reroute e2 to connect (n1, n2)
+                if (n1, n2) in {tuple(edges_arr[i]) for i in range(len(edges_arr)) if alive[i]} or \
+                   (n2, n1) in {tuple(edges_arr[i]) for i in range(len(edges_arr)) if alive[i]}:
+                    # Already exists — just drop both incident edges (degenerate)
+                    alive[e1] = False
+                    alive[e2] = False
+                else:
+                    alive[e1] = False
+                    edges_arr[e2] = (min(n1, n2), max(n1, n2))
+                changed = True
+                break
+
+        if changed:
+            continue
+
+        # Pass 2: duplicate-direction prune
+        for v in range(len(verts)):
+            if len(adj[v]) < 2:
+                continue
+            nbrs = adj[v]
+            # Build direction vectors for each incident alive edge
+            dirs = []
+            for nb, ei in nbrs:
+                d = verts[nb] - verts[v]
+                nrm = np.linalg.norm(d)
+                if nrm < 1e-6:
+                    dirs.append(None)
+                else:
+                    dirs.append(d / nrm)
+            # Find any duplicate pair
+            drop_ei = None
+            for i in range(len(nbrs)):
+                if dirs[i] is None:
+                    continue
+                for j in range(i + 1, len(nbrs)):
+                    if dirs[j] is None:
+                        continue
+                    if float(np.dot(dirs[i], dirs[j])) > duplicate_cos:
+                        ei_i, ei_j = nbrs[i][1], nbrs[j][1]
+                        # Keep the one with higher score; tiebreak by length
+                        s_i = (scores[ei_i], lengths[ei_i])
+                        s_j = (scores[ei_j], lengths[ei_j])
+                        drop_ei = ei_j if s_i >= s_j else ei_i
+                        break
+                if drop_ei is not None:
+                    break
+            if drop_ei is not None:
+                alive[drop_ei] = False
+                changed = True
+                break
+
+        if changed:
+            continue
+
+        # Pass 3: leaf prune (degree-1 short edge)
+        for v in range(len(verts)):
+            if len(adj[v]) != 1:
+                continue
+            nb, ei = adj[v][0]
+            if lengths[ei] < leaf_min_len:
+                alive[ei] = False
+                changed = True
+                break
+
+        if not changed:
+            break
+
+    surviving = [tuple(map(int, edges_arr[i])) for i in range(len(edges_arr)) if alive[i]]
+    return verts, surviving

line_cloud.py

@@ -0,0 +1,542 @@
+"""LC2WF-inspired 3D line cloud wireframe module.
+
+Instead of lifting individual 2D corners to 3D via a single depth sample,
+this module:
+
+1. Extracts 2D line segments from gestalt edge masks (eave/ridge/rake/etc).
+2. Samples many depth values along each 2D segment.
+3. Fits a robust 3D line through the unprojected samples (RANSAC).
+4. Merges similar 3D lines across views (direction + proximity).
+5. Computes closest-point intersections of 3D line pairs → vertex candidates.
+
+The resulting vertices average over many depth samples, cancelling noise
+that single-pixel corner depth estimates cannot. The 3D line intersections
+give overdetermined vertex positions.
+
+Entry points:
+    extract_3d_lines(entry) → list[Line3D]
+    intersect_lines_to_vertices(lines, ...) → np.ndarray
+    predict_wireframe_lines(entry) → (vertices, edges)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import cv2
+from dataclasses import dataclass
+
+from hoho2025.example_solutions import (
+    convert_entry_to_human_readable,
+    empty_solution,
+    point_to_segment_dist,
+)
+from hoho2025.color_mappings import gestalt_color_mapping
+
+try:
+    from mvs_utils import collect_views, project_world_to_image
+except ImportError:
+    from submission.mvs_utils import collect_views, project_world_to_image
+
+
+EDGE_CLASSES = ['eave', 'ridge', 'rake', 'valley', 'hip']
+VERTEX_CLASSES = ['apex', 'eave_end_point', 'flashing_end_point']
+
+
+@dataclass
+class Line3D:
+    """A 3D line segment fitted from depth samples."""
+    point: np.ndarray       # (3,) — a point on the line
+    direction: np.ndarray   # (3,) — unit direction vector
+    p1: np.ndarray          # (3,) — endpoint 1
+    p2: np.ndarray          # (3,) — endpoint 2
+    length: float
+    n_inliers: int
+    edge_class: str
+    view_id: str
+
+
+# ---------------------------------------------------------------------------
+# Step 1-2: Extract 2D segments, sample depth, fit 3D lines
+# ---------------------------------------------------------------------------
+
+def _unproject_pixel(u, v, depth, K_inv, R_t_inv, t_world):
+    """Unproject a single pixel (u, v) at the given depth to world coords.
+
+    K_inv : (3,3) — inverse intrinsics
+    R_t_inv : (3,3) — R^T (inverse rotation)
+    t_world : (3,) — camera centre in world = -R^T @ t
+    """
+    z = float(depth)
+    if z <= 0.01 or z > 80.0:
+        return None
+    cam = K_inv @ np.array([u * z, v * z, z])
+    world = R_t_inv @ cam + t_world
+    return world
+
+
+def _fit_3d_line_ransac(
+    pts3d: np.ndarray,
+    n_iter: int = 100,
+    inlier_th: float = 0.3,
+    min_inliers: int = 5,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None:
+    """RANSAC-fit a 3D line through a set of 3D points.
+
+    Returns (point_on_line, unit_direction, inlier_pts) or None.
+    """
+    n = len(pts3d)
+    if n < 2:
+        return None
+
+    best_inliers = None
+    best_dir = None
+    best_pt = None
+    best_count = 0
+
+    for _ in range(n_iter):
+        idx = np.random.choice(n, 2, replace=False)
+        p1, p2 = pts3d[idx[0]], pts3d[idx[1]]
+        d = p2 - p1
+        length = np.linalg.norm(d)
+        if length < 0.05:
+            continue
+        d = d / length
+        # Distance from each point to the line (p1, d)
+        rel = pts3d - p1
+        proj = rel @ d
+        perp = rel - proj[:, None] * d
+        dists = np.linalg.norm(perp, axis=1)
+        inlier_mask = dists <= inlier_th
+        count = int(inlier_mask.sum())
+        if count > best_count:
+            best_count = count
+            best_inliers = inlier_mask
+            best_dir = d
+            best_pt = p1
+
+    if best_count < min_inliers or best_inliers is None:
+        return None
+
+    # Refit on inliers using PCA
+    inlier_pts = pts3d[best_inliers]
+    centroid = inlier_pts.mean(axis=0)
+    _, _, Vt = np.linalg.svd(inlier_pts - centroid)
+    direction = Vt[0]
+    if np.dot(direction, best_dir) < 0:
+        direction = -direction
+
+    return centroid, direction, inlier_pts
+
+
+def extract_3d_lines_single_view(
+    gest_np: np.ndarray,
+    depth_np: np.ndarray,
+    view_info: dict,
+    n_samples: int = 30,
+    min_line_px: int = 20,
+) -> list[Line3D]:
+    """Extract 3D lines from a single view's gestalt + depth."""
+    H, W = depth_np.shape[:2]
+    K = view_info['K']
+    R = view_info['R']
+    t = view_info['t']
+    K_inv = np.linalg.inv(K)
+    R_inv = R.T
+    cam_center = -R_inv @ t
+
+    lines: list[Line3D] = []
+    view_id = view_info['image_id']
+
+    for edge_class in EDGE_CLASSES:
+        color = np.array(gestalt_color_mapping[edge_class])
+        mask = cv2.inRange(gest_np, color - 0.5, color + 0.5)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
+        if mask.sum() == 0:
+            continue
+
+        _, labels, stats, _ = cv2.connectedComponentsWithStats(mask, 8, cv2.CV_32S)
+        for lbl in range(1, labels.max() + 1):
+            area = stats[lbl, cv2.CC_STAT_AREA]
+            if area < min_line_px:
+                continue
+
+            ys, xs = np.where(labels == lbl)
+            if len(xs) < 3:
+                continue
+
+            # Fit 2D line to get direction + endpoints
+            pts2d = np.column_stack([xs, ys]).astype(np.float32)
+            line_params = cv2.fitLine(pts2d, cv2.DIST_L2, 0, 0.01, 0.01)
+            vx, vy, x0, y0 = line_params.ravel()
+            proj = (xs - x0) * vx + (ys - y0) * vy
+            t_min, t_max = float(proj.min()), float(proj.max())
+
+            # Sample N points along the 2D line
+            ts = np.linspace(t_min, t_max, n_samples)
+            pts3d_list = []
+            for t_val in ts:
+                u = x0 + t_val * vx
+                v_px = y0 + t_val * vy
+                ui, vi = int(round(u)), int(round(v_px))
+                if 0 <= ui < W and 0 <= vi < H:
+                    d = depth_np[vi, ui]
+                    p = _unproject_pixel(u, v_px, d, K_inv, R_inv, cam_center)
+                    if p is not None:
+                        pts3d_list.append(p)
+
+            if len(pts3d_list) < 5:
+                continue
+
+            pts3d = np.array(pts3d_list, dtype=np.float64)
+            result = _fit_3d_line_ransac(pts3d, n_iter=50, inlier_th=0.3, min_inliers=5)
+            if result is None:
+                continue
+
+            centroid, direction, inlier_pts = result
+            # Endpoints: project inliers onto direction, take extremes
+            s = (inlier_pts - centroid) @ direction
+            p1 = centroid + float(s.min()) * direction
+            p2 = centroid + float(s.max()) * direction
+            length = float(np.linalg.norm(p2 - p1))
+            if length < 0.3:
+                continue
+
+            lines.append(Line3D(
+                point=centroid,
+                direction=direction,
+                p1=p1, p2=p2,
+                length=length,
+                n_inliers=len(inlier_pts),
+                edge_class=edge_class,
+                view_id=view_id,
+            ))
+
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Step 1-2 entry: all views
+# ---------------------------------------------------------------------------
+
+def extract_3d_lines(entry) -> tuple[list[Line3D], dict]:
+    """Extract 3D lines from all views.
+
+    Returns (all_lines, good_entry).
+    """
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return [], good
+
+    views = collect_views(colmap_rec, good['image_ids'])
+    all_lines: list[Line3D] = []
+
+    for gest, depth, img_id in zip(good['gestalt'], good['depth'], good['image_ids']):
+        info = views.get(img_id)
+        if info is None:
+            continue
+        depth_np = np.array(depth).astype(np.float64) / 1000.0
+        H, W = depth_np.shape[:2]
+        gest_np = np.array(gest.resize((W, H))).astype(np.uint8)
+
+        # Affine depth calibration using COLMAP sparse depth (same as pipeline)
+        try:
+            from hoho2025.example_solutions import get_sparse_depth, get_house_mask
+            from sklearn_submission import fit_affine_ransac
+            depth_sparse, found, _, _ = get_sparse_depth(colmap_rec, img_id, depth_np)
+            if found:
+                _, _, depth_np = fit_affine_ransac(depth_np, depth_sparse,
+                                                    get_house_mask(good['ade'][good['image_ids'].index(img_id)]))
+        except Exception:
+            pass  # use raw depth if calibration fails
+
+        view_lines = extract_3d_lines_single_view(gest_np, depth_np, info)
+        all_lines.extend(view_lines)
+
+    return all_lines, good
+
+
+# ---------------------------------------------------------------------------
+# Step 3: Merge similar 3D lines across views
+# ---------------------------------------------------------------------------
+
+def merge_3d_lines(
+    lines: list[Line3D],
+    direction_cos: float = 0.95,
+    midpoint_dist: float = 1.0,
+) -> list[Line3D]:
+    """Merge 3D lines that have similar direction and nearby midpoints.
+
+    Uses greedy clustering: each line is assigned to the first compatible
+    cluster. The cluster representative is recomputed as the mean of its
+    members (direction via PCA, endpoints via extremal projections).
+    """
+    if len(lines) <= 1:
+        return lines
+
+    clusters: list[list[int]] = []
+    reps: list[Line3D] = []
+
+    for i, line in enumerate(lines):
+        matched = False
+        for ci, rep in enumerate(reps):
+            cos = abs(float(np.dot(line.direction, rep.direction)))
+            if cos < direction_cos:
+                continue
+            mid_d = float(np.linalg.norm(
+                (line.p1 + line.p2) / 2 - (rep.p1 + rep.p2) / 2
+            ))
+            if mid_d > midpoint_dist:
+                continue
+            clusters[ci].append(i)
+            # Recompute representative
+            members = [lines[j] for j in clusters[ci]]
+            all_pts = np.vstack([np.vstack([m.p1, m.p2]) for m in members])
+            centroid = all_pts.mean(axis=0)
+            _, _, Vt = np.linalg.svd(all_pts - centroid)
+            direction = Vt[0]
+            if np.dot(direction, rep.direction) < 0:
+                direction = -direction
+            s = (all_pts - centroid) @ direction
+            new_p1 = centroid + float(s.min()) * direction
+            new_p2 = centroid + float(s.max()) * direction
+            reps[ci] = Line3D(
+                point=centroid, direction=direction,
+                p1=new_p1, p2=new_p2,
+                length=float(np.linalg.norm(new_p2 - new_p1)),
+                n_inliers=sum(m.n_inliers for m in members),
+                edge_class=members[0].edge_class,
+                view_id='merged',
+            )
+            matched = True
+            break
+        if not matched:
+            clusters.append([i])
+            reps.append(Line3D(
+                point=line.point.copy(), direction=line.direction.copy(),
+                p1=line.p1.copy(), p2=line.p2.copy(),
+                length=line.length, n_inliers=line.n_inliers,
+                edge_class=line.edge_class, view_id=line.view_id,
+            ))
+
+    return reps
+
+
+# ---------------------------------------------------------------------------
+# Step 4: Intersect pairs of 3D lines → vertex candidates
+# ---------------------------------------------------------------------------
+
+def closest_point_on_two_lines(
+    p1: np.ndarray, d1: np.ndarray,
+    p2: np.ndarray, d2: np.ndarray,
+) -> tuple[np.ndarray, float] | None:
+    """Find the closest point between two 3D lines.
+
+    Returns (midpoint_of_closest_approach, distance_between_lines) or None
+    if the lines are nearly parallel.
+    """
+    w0 = p1 - p2
+    a = float(np.dot(d1, d1))
+    b = float(np.dot(d1, d2))
+    c = float(np.dot(d2, d2))
+    d = float(np.dot(d1, w0))
+    e = float(np.dot(d2, w0))
+
+    denom = a * c - b * b
+    if abs(denom) < 1e-8:
+        return None  # parallel
+
+    sc = (b * e - c * d) / denom
+    tc = (a * e - b * d) / denom
+
+    closest_on_1 = p1 + sc * d1
+    closest_on_2 = p2 + tc * d2
+    midpoint = (closest_on_1 + closest_on_2) / 2.0
+    dist = float(np.linalg.norm(closest_on_1 - closest_on_2))
+
+    return midpoint, dist
+
+
+def intersect_lines_to_vertices(
+    lines: list[Line3D],
+    max_dist: float = 0.5,
+    parallel_cos: float = 0.95,
+    segment_margin: float = 0.5,
+) -> np.ndarray:
+    """Generate vertex candidates from 3D line intersections.
+
+    For each pair of non-parallel lines:
+    - compute the closest approach point;
+    - accept if the distance between the lines at that point is ≤ max_dist;
+    - accept only if the closest point is within ``segment_margin`` of
+      both line segments (not too far outside the actual edge extent).
+    """
+    if len(lines) < 2:
+        return np.empty((0, 3), dtype=np.float64)
+
+    vertices: list[np.ndarray] = []
+    for i in range(len(lines)):
+        for j in range(i + 1, len(lines)):
+            cos = abs(float(np.dot(lines[i].direction, lines[j].direction)))
+            if cos >= parallel_cos:
+                continue
+
+            result = closest_point_on_two_lines(
+                lines[i].point, lines[i].direction,
+                lines[j].point, lines[j].direction,
+            )
+            if result is None:
+                continue
+            midpoint, dist = result
+            if dist > max_dist:
+                continue
+
+            # Check that the intersection is near both line segments
+            ok = True
+            for line in (lines[i], lines[j]):
+                s = float(np.dot(midpoint - line.point, line.direction))
+                s_min = float(np.dot(line.p1 - line.point, line.direction))
+                s_max = float(np.dot(line.p2 - line.point, line.direction))
+                if s < s_min - segment_margin or s > s_max + segment_margin:
+                    ok = False
+                    break
+            if ok:
+                vertices.append(midpoint)
+
+    if not vertices:
+        return np.empty((0, 3), dtype=np.float64)
+    return np.array(vertices, dtype=np.float64)
+
+
+# ---------------------------------------------------------------------------
+# Step 5: Integration helper
+# ---------------------------------------------------------------------------
+
+def snap_vertices_to_lines(
+    vertices: np.ndarray,
+    lines: list[Line3D],
+    snap_radius: float = 0.4,
+    min_line_inliers: int = 10,
+    segment_margin: float = 0.3,
+    require_agree: int = 1,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Snap each vertex to the nearest 3D line if the line is trustworthy
+    and the vertex sits within ``snap_radius`` perpendicular distance.
+
+    The snap is a perpendicular projection of the vertex onto the line. If
+    the projected point falls outside the segment ``[p1, p2]`` by more than
+    ``segment_margin``, we clamp it to the nearest endpoint (so we never
+    slide a vertex off the ends of the real edge).
+
+    A line is considered "trustworthy" if it has ≥ ``min_line_inliers``
+    depth samples (the more, the better the depth-noise averaging).
+
+    When ``require_agree`` ≥ 2 we only snap if the vertex is within
+    ``snap_radius`` of **multiple** independent lines and they all agree
+    on roughly the same 3D location — this is a "consensus" mode that
+    avoids snapping to a single noisy line.
+
+    Returns
+    -------
+    refined : (N, 3) float64 — refined vertex positions
+    snapped : (N,)  bool    — which vertices were moved
+    """
+    verts = np.asarray(vertices, dtype=np.float64)
+    refined = verts.copy()
+    snapped = np.zeros(len(verts), dtype=bool)
+
+    if len(verts) == 0 or not lines:
+        return refined, snapped
+
+    # Pre-filter trustworthy lines
+    trusted = [ln for ln in lines if ln.n_inliers >= min_line_inliers]
+    if not trusted:
+        return refined, snapped
+
+    for i, v in enumerate(verts):
+        # Compute perpendicular distance and projected point for each line
+        candidates: list[tuple[float, np.ndarray, Line3D]] = []
+        for ln in trusted:
+            rel = v - ln.point
+            s = float(np.dot(rel, ln.direction))
+            projected = ln.point + s * ln.direction
+            perp = float(np.linalg.norm(v - projected))
+            if perp > snap_radius:
+                continue
+            # Clamp projection to segment
+            s_min = float(np.dot(ln.p1 - ln.point, ln.direction))
+            s_max = float(np.dot(ln.p2 - ln.point, ln.direction))
+            if s_min > s_max:
+                s_min, s_max = s_max, s_min
+            if s < s_min - segment_margin:
+                projected = ln.point + (s_min - segment_margin) * ln.direction
+            elif s > s_max + segment_margin:
+                projected = ln.point + (s_max + segment_margin) * ln.direction
+            candidates.append((perp, projected, ln))
+
+        if len(candidates) < require_agree:
+            continue
+
+        if require_agree >= 2:
+            # Consensus: keep only if ≥2 candidates agree within snap_radius.
+            candidates.sort(key=lambda c: c[0])
+            best_proj = candidates[0][1]
+            agree = 0
+            for _, cp, _ in candidates:
+                if np.linalg.norm(cp - best_proj) <= snap_radius:
+                    agree += 1
+            if agree < require_agree:
+                continue
+            # Snap to the mean of agreeing projections
+            agreeing = [c[1] for c in candidates
+                        if np.linalg.norm(c[1] - best_proj) <= snap_radius]
+            refined[i] = np.mean(agreeing, axis=0)
+            snapped[i] = True
+        else:
+            # Single-line snap: pick the closest
+            candidates.sort(key=lambda c: c[0])
+            refined[i] = candidates[0][1]
+            snapped[i] = True
+
+    return refined, snapped
+
+
+def line_based_vertices(
+    entry,
+    max_intersection_dist: float = 0.5,
+    merge_radius: float = 0.4,
+) -> np.ndarray:
+    """High-level: extract 3D lines, merge, intersect → vertex candidates.
+
+    Returns (K, 3) array of deduplicated vertex positions.
+    """
+    lines, good = extract_3d_lines(entry)
+    if not lines:
+        return np.empty((0, 3), dtype=np.float64)
+
+    merged_lines = merge_3d_lines(lines)
+    if len(merged_lines) < 2:
+        return np.empty((0, 3), dtype=np.float64)
+
+    raw_verts = intersect_lines_to_vertices(
+        merged_lines, max_dist=max_intersection_dist,
+    )
+    if len(raw_verts) == 0:
+        return np.empty((0, 3), dtype=np.float64)
+
+    # Simple NMS merge
+    from scipy.spatial import cKDTree
+    tree = cKDTree(raw_verts)
+    clusters = tree.query_ball_point(raw_verts, merge_radius)
+    used = set()
+    out = []
+    for i, cl in enumerate(clusters):
+        if i in used:
+            continue
+        members = [j for j in cl if j not in used]
+        if not members:
+            continue
+        out.append(raw_verts[members].mean(axis=0))
+        used.update(members)
+
+    return np.array(out, dtype=np.float64) if out else np.empty((0, 3), dtype=np.float64)

plane_wireframe.py

@@ -0,0 +1,472 @@
+"""Plane-intersection wireframe predictor (Tier 2).
+
+Classical-geometry pipeline, orthogonal to the gestalt + depth path:
+
+1. Crop the COLMAP sparse cloud to the top portion along the up-axis so that
+   only roof points remain (the dataset uses +Y as up).
+2. Iteratively RANSAC-segment the cropped cloud into planes (open3d).
+3. Keep only planes whose normal has a significant +Y component (roof
+   slopes) or is near-horizontal (flat roof / eaves).
+4. For each pair of surviving planes, compute the infinite intersection
+   line via scikit-spatial and clip it to the overlap of the two inlier
+   sets (percentile endpoints with a perpendicular tolerance).
+5. Vertices = segment endpoints ∪ triple-plane intersections, merged at
+   a small radius.
+6. Edges = clipped segments remapped onto the merged vertex set.
+
+Only numpy / open3d / scikit-spatial / pycolmap are used — no torch.
+
+The main entry point is :func:`predict_wireframe_planes`, which returns
+``(vertices, edges)`` in the format expected by ``hss()``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import open3d as o3d
+from skspatial.objects import Plane as SkPlane
+
+from hoho2025.example_solutions import (
+    convert_entry_to_human_readable,
+    empty_solution,
+)
+
+
+UP_AXIS = 1  # +Y is up in this dataset (verified across 15 validation samples)
+
+
+# ---------------------------------------------------------------------------
+# Plane data structure
+# ---------------------------------------------------------------------------
+
+class RoofPlane:
+    """A planar segment of the roof point cloud.
+
+    ``eq`` stores a normalised (a, b, c, d) plane equation such that
+    ``|n| = 1`` and ``a*x + b*y + c*z + d = 0``.
+    """
+
+    __slots__ = ("eq", "normal", "d", "inliers")
+
+    def __init__(self, eq: np.ndarray, inliers: np.ndarray):
+        eq = np.asarray(eq, dtype=np.float64)
+        n = eq[:3]
+        nn = np.linalg.norm(n)
+        if nn > 1e-9:
+            eq = eq / nn
+        self.eq = eq
+        self.normal = eq[:3]
+        self.d = float(eq[3])
+        self.inliers = np.asarray(inliers, dtype=np.float64)
+
+    def signed_distance(self, pts: np.ndarray) -> np.ndarray:
+        return pts @ self.normal + self.d
+
+
+# ---------------------------------------------------------------------------
+# Roof crop
+# ---------------------------------------------------------------------------
+
+def crop_to_roof(
+    xyz: np.ndarray,
+    up_axis: int = UP_AXIS,
+    top_frac: float = 0.70,
+    pad: float = 1.0,
+) -> np.ndarray:
+    """Keep points whose up-axis coordinate is in the top ``top_frac`` of the
+    distribution.
+
+    COLMAP reconstructions include ground, walls, vegetation and roof. The
+    roof corners live in the upper Y range. A fractional cut along the up
+    axis is a robust proxy that does not need any external scale calibration
+    and works for both peaked and flat roofs.
+    """
+    if len(xyz) == 0:
+        return xyz
+    up = xyz[:, up_axis]
+    lo, hi = float(up.min()), float(up.max())
+    if hi - lo < 1e-6:
+        return xyz
+    threshold = lo + (hi - lo) * (1.0 - top_frac) - pad
+    mask = up >= threshold
+    return xyz[mask]
+
+
+def _is_roof_normal(normal: np.ndarray, up_axis: int = UP_AXIS,
+                    min_up: float = 0.15) -> bool:
+    """A roof plane either has significant vertical component (pitched
+    surface) or is nearly horizontal (flat roof). Walls have ``|n_up| ≈ 0``
+    and are rejected.
+    """
+    return abs(float(normal[up_axis])) >= min_up
+
+
+# ---------------------------------------------------------------------------
+# T2.1 Iterative RANSAC plane segmentation (open3d backend)
+# ---------------------------------------------------------------------------
+
+def segment_roof_planes(
+    xyz: np.ndarray,
+    distance_threshold: float = 0.15,
+    ransac_n: int = 3,
+    num_iterations: int = 1000,
+    min_inliers: int = 60,
+    max_planes: int = 8,
+    roof_crop_top_frac: float = 0.70,
+    crop_pad: float = 1.0,
+    keep_walls: bool = True,
+) -> list[RoofPlane]:
+    """Sequentially RANSAC-fit roof planes.
+
+    Crops the cloud to the top ``roof_crop_top_frac`` along +Y first, then
+    iteratively removes inliers until no plane with at least ``min_inliers``
+    remains or ``max_planes`` have been found. Planes whose normal is nearly
+    perpendicular to the up axis (walls) are dropped.
+    """
+    cropped = crop_to_roof(xyz, top_frac=roof_crop_top_frac, pad=crop_pad)
+    if len(cropped) < min_inliers * 2:
+        # Fall back to the full cloud if the crop is too aggressive.
+        cropped = np.asarray(xyz, dtype=np.float64)
+    if len(cropped) < min_inliers:
+        return []
+
+    remaining = cropped.copy()
+    planes: list[RoofPlane] = []
+
+    pcd = o3d.geometry.PointCloud()
+    for _ in range(max_planes):
+        if len(remaining) < min_inliers:
+            break
+        pcd.points = o3d.utility.Vector3dVector(remaining)
+        try:
+            eq, inlier_idx = pcd.segment_plane(
+                distance_threshold=distance_threshold,
+                ransac_n=ransac_n,
+                num_iterations=num_iterations,
+            )
+        except Exception:
+            break
+        if len(inlier_idx) < min_inliers:
+            break
+        eq = np.asarray(eq, dtype=np.float64)
+        inliers = remaining[np.asarray(inlier_idx, dtype=np.int64)]
+        normal = eq[:3] / (np.linalg.norm(eq[:3]) + 1e-12)
+        if keep_walls or _is_roof_normal(normal):
+            planes.append(RoofPlane(eq, inliers))
+        # Always remove inliers from the remaining cloud even for rejected
+        # planes, otherwise RANSAC keeps returning the same ones.
+        keep_mask = np.ones(len(remaining), dtype=bool)
+        keep_mask[np.asarray(inlier_idx, dtype=np.int64)] = False
+        remaining = remaining[keep_mask]
+
+    return planes
+
+
+# ---------------------------------------------------------------------------
+# T2.2 Plane-pair intersection line (scikit-spatial)
+# ---------------------------------------------------------------------------
+
+def intersect_two_planes(
+    p1: RoofPlane, p2: RoofPlane, parallel_cos: float = 0.995,
+) -> tuple[np.ndarray, np.ndarray] | None:
+    """Return ``(point_on_line, unit_direction)`` or ``None`` if near parallel."""
+    dot = abs(float(np.dot(p1.normal, p2.normal)))
+    if dot >= parallel_cos:
+        return None
+    sk1 = SkPlane(point=-p1.d * p1.normal, normal=p1.normal)
+    sk2 = SkPlane(point=-p2.d * p2.normal, normal=p2.normal)
+    try:
+        line = sk1.intersect_plane(sk2)
+    except Exception:
+        return None
+    point = np.asarray(line.point, dtype=np.float64)
+    direction = np.asarray(line.direction, dtype=np.float64)
+    norm = np.linalg.norm(direction)
+    if norm < 1e-9:
+        return None
+    return point, direction / norm
+
+
+# ---------------------------------------------------------------------------
+# T2.3 Clip the line to a real segment
+# ---------------------------------------------------------------------------
+
+def clip_line_to_segment(
+    point: np.ndarray,
+    direction: np.ndarray,
+    p1: RoofPlane,
+    p2: RoofPlane,
+    perp_tol: float = 0.4,
+    trim_pct: float = 5.0,
+    min_length: float = 0.3,
+) -> tuple[np.ndarray, np.ndarray] | None:
+    """Clip the infinite line to the overlap region of the two inlier sets.
+
+    Only inliers whose projection onto the line is within ``perp_tol`` of the
+    line contribute — otherwise a large plane would stretch the intersection
+    far outside the real roof feature. The segment endpoints are the
+    5th / 95th percentile of projected scalars taken over the union of the
+    two filtered sets.
+    """
+    endpoints_s = []
+    for plane in (p1, p2):
+        rel = plane.inliers - point
+        s = rel @ direction
+        perp = rel - s[:, None] * direction
+        d_perp = np.linalg.norm(perp, axis=1)
+        near = s[d_perp <= perp_tol]
+        if len(near) >= 5:
+            endpoints_s.append(near)
+    if not endpoints_s:
+        return None
+    all_s = np.concatenate(endpoints_s)
+    if len(all_s) < 5:
+        return None
+    lo, hi = np.percentile(all_s, [trim_pct, 100.0 - trim_pct])
+    if hi - lo < min_length:
+        return None
+    a = point + lo * direction
+    b = point + hi * direction
+    return a, b
+
+
+# ---------------------------------------------------------------------------
+# T2.4 Triple-plane corners + vertex dedup
+# ---------------------------------------------------------------------------
+
+def _triple_plane_corners(
+    planes: list[RoofPlane], max_dist_to_inlier: float = 1.0,
+) -> list[np.ndarray]:
+    """Solve the 3x3 linear system for every non-collinear triple.
+
+    A corner is kept only if every one of the three parent planes has at
+    least one inlier within ``max_dist_to_inlier`` of the computed point,
+    which removes ghost intersections far outside the roof.
+    """
+    out: list[np.ndarray] = []
+    n = len(planes)
+    for i in range(n):
+        for j in range(i + 1, n):
+            for k in range(j + 1, n):
+                A = np.vstack([planes[i].normal, planes[j].normal, planes[k].normal])
+                if abs(float(np.linalg.det(A))) < 1e-3:
+                    continue
+                b = -np.array([planes[i].d, planes[j].d, planes[k].d])
+                try:
+                    X = np.linalg.solve(A, b)
+                except np.linalg.LinAlgError:
+                    continue
+                ok = True
+                for p in (planes[i], planes[j], planes[k]):
+                    if np.linalg.norm(p.inliers - X, axis=1).min() > max_dist_to_inlier:
+                        ok = False
+                        break
+                if ok:
+                    out.append(X)
+    return out
+
+
+def _merge_points(points: np.ndarray, radius: float) -> tuple[np.ndarray, np.ndarray]:
+    """Greedy dedup by nearest-cluster assignment."""
+    pts = np.asarray(points, dtype=np.float64)
+    if len(pts) == 0:
+        return np.empty((0, 3)), np.empty((0,), dtype=np.int64)
+    mapping = np.full(len(pts), -1, dtype=np.int64)
+    clusters: list[list[int]] = []
+    centroids: list[np.ndarray] = []
+    for i, p in enumerate(pts):
+        if not centroids:
+            clusters.append([i])
+            centroids.append(p.copy())
+            mapping[i] = 0
+            continue
+        c_arr = np.array(centroids)
+        d = np.linalg.norm(c_arr - p, axis=1)
+        j = int(np.argmin(d))
+        if d[j] <= radius:
+            clusters[j].append(i)
+            centroids[j] = pts[clusters[j]].mean(axis=0)
+            mapping[i] = j
+        else:
+            clusters.append([i])
+            centroids.append(p.copy())
+            mapping[i] = len(centroids) - 1
+    merged = np.array(centroids, dtype=np.float64)
+    return merged, mapping
+
+
+# ---------------------------------------------------------------------------
+# T2.7 Hybrid integration helpers: snap intersection lines to existing
+# sklearn-derived vertices.
+# ---------------------------------------------------------------------------
+
+def edges_from_planes_and_vertices(
+    vertices: np.ndarray,
+    planes: list[RoofPlane],
+    perp_tol: float = 0.6,
+    min_length: float = 0.5,
+    max_length: float = 10.0,
+) -> list[tuple[int, int]]:
+    """Vote edges between vertices using plane-pair intersection lines.
+
+    For each line ``L_ij = plane_i ∩ plane_j``:
+      * find all ``vertices`` whose perpendicular distance to L_ij is
+        below ``perp_tol``,
+      * pair the two extremes along the line direction as an edge.
+
+    The result is a set of 3D edges supported by plane geometry. Because
+    the vertices come from sklearn's depth-based detection, positions are
+    noisy but complete — while the lines come from RANSAC on thousands
+    of COLMAP points and are very accurate in direction. Matching the two
+    gives clean roof ridges / eaves without depending on 2D fitLine noise.
+    """
+    if len(vertices) < 2 or len(planes) < 2:
+        return []
+    V = np.asarray(vertices, dtype=np.float64)
+    edges: set[tuple[int, int]] = set()
+
+    for i in range(len(planes)):
+        for j in range(i + 1, len(planes)):
+            inter = intersect_two_planes(planes[i], planes[j])
+            if inter is None:
+                continue
+            point, direction = inter
+            rel = V - point
+            s = rel @ direction
+            perp = rel - s[:, None] * direction
+            d_perp = np.linalg.norm(perp, axis=1)
+            near_idx = np.where(d_perp <= perp_tol)[0]
+            if len(near_idx) < 2:
+                continue
+            # Take the two vertices with the most extreme projections
+            s_near = s[near_idx]
+            a = int(near_idx[np.argmin(s_near)])
+            b = int(near_idx[np.argmax(s_near)])
+            if a == b:
+                continue
+            dist3d = float(np.linalg.norm(V[a] - V[b]))
+            if dist3d < min_length or dist3d > max_length:
+                continue
+            lo, hi = (a, b) if a < b else (b, a)
+            edges.add((lo, hi))
+
+            # Additionally, for each adjacent pair of projections along the
+            # line, add them as an edge if the 3D distance is reasonable.
+            order = np.argsort(s[near_idx])
+            sorted_idx = near_idx[order]
+            for k in range(len(sorted_idx) - 1):
+                x = int(sorted_idx[k])
+                y = int(sorted_idx[k + 1])
+                d = float(np.linalg.norm(V[x] - V[y]))
+                if d < min_length or d > max_length:
+                    continue
+                lo, hi = (x, y) if x < y else (y, x)
+                edges.add((lo, hi))
+
+    return list(edges)
+
+
+def predict_plane_edges(entry, vertices: np.ndarray,
+                         distance_threshold: float = 0.20,
+                         min_inliers: int = 60,
+                         max_planes: int = 10,
+                         roof_crop_top_frac: float = 0.95,
+                         perp_tol: float = 0.8,
+                         ) -> list[tuple[int, int]]:
+    """High-level helper: given a sklearn wireframe's vertices, return a
+    list of extra edges supported by plane-pair intersection geometry.
+    """
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get("colmap") or good.get("colmap_binary")
+    if colmap_rec is None:
+        return []
+    all_xyz = np.array([p.xyz for p in colmap_rec.points3D.values()], dtype=np.float64)
+    if len(all_xyz) < min_inliers * 2:
+        return []
+    planes = segment_roof_planes(
+        all_xyz,
+        distance_threshold=distance_threshold,
+        min_inliers=min_inliers,
+        max_planes=max_planes,
+        roof_crop_top_frac=roof_crop_top_frac,
+    )
+    if len(planes) < 2:
+        return []
+    return edges_from_planes_and_vertices(vertices, planes, perp_tol=perp_tol)
+
+
+# ---------------------------------------------------------------------------
+# T2.6 Standalone predictor
+# ---------------------------------------------------------------------------
+
+def predict_wireframe_planes(
+    entry,
+    distance_threshold: float = 0.15,
+    min_inliers: int = 60,
+    max_planes: int = 8,
+    perp_tol: float = 0.4,
+    merge_radius: float = 0.35,
+    roof_crop_top_frac: float = 0.55,
+) -> tuple[np.ndarray, list[tuple[int, int]]]:
+    """Build a wireframe from COLMAP sparse points via plane intersection."""
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get("colmap") or good.get("colmap_binary")
+    if colmap_rec is None:
+        return empty_solution()
+
+    all_xyz = np.array([p.xyz for p in colmap_rec.points3D.values()], dtype=np.float64)
+    if len(all_xyz) < min_inliers * 2:
+        return empty_solution()
+
+    planes = segment_roof_planes(
+        all_xyz,
+        distance_threshold=distance_threshold,
+        min_inliers=min_inliers,
+        max_planes=max_planes,
+        roof_crop_top_frac=roof_crop_top_frac,
+    )
+    if len(planes) < 2:
+        return empty_solution()
+
+    endpoint_pool: list[np.ndarray] = []
+    segments: list[tuple[int, int]] = []
+    for i in range(len(planes)):
+        for j in range(i + 1, len(planes)):
+            inter = intersect_two_planes(planes[i], planes[j])
+            if inter is None:
+                continue
+            point, direction = inter
+            seg = clip_line_to_segment(
+                point, direction, planes[i], planes[j], perp_tol=perp_tol
+            )
+            if seg is None:
+                continue
+            a, b = seg
+            ia = len(endpoint_pool)
+            endpoint_pool.append(a)
+            ib = len(endpoint_pool)
+            endpoint_pool.append(b)
+            segments.append((ia, ib))
+
+    if not segments:
+        return empty_solution()
+
+    corners = _triple_plane_corners(planes)
+    endpoint_pool.extend(corners)
+
+    all_pts = np.asarray(endpoint_pool, dtype=np.float64)
+    merged, mapping = _merge_points(all_pts, radius=merge_radius)
+
+    edge_set: set[tuple[int, int]] = set()
+    for ia, ib in segments:
+        ma = int(mapping[ia])
+        mb = int(mapping[ib])
+        if ma == mb:
+            continue
+        lo, hi = (ma, mb) if ma < mb else (mb, ma)
+        edge_set.add((lo, hi))
+
+    if not edge_set or len(merged) < 2:
+        return empty_solution()
+
+    return merged, [(int(a), int(b)) for a, b in edge_set]

triangulation.py

@@ -0,0 +1,618 @@
+"""Multi-view corner triangulation pipeline (T1.2 – T1.6).
+
+Drop-in replacement for the depth-based ``project_vertices_to_3d`` step in
+``sklearn_submission.py``. The depth map is only used as a sanity filter, never
+as the source of 3D positions — the actual geometry comes from COLMAP cameras
+via DLT triangulation.
+
+Entry points:
+    detect_corners_per_view(entry)  → dict[view_id → List[Corner]]
+    triangulate_wireframe(entry, corners_per_view) → Tracks + per-track obs
+
+Everything is pure numpy + pycolmap + cv2 — no torch, no kornia.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import cv2
+from dataclasses import dataclass, field
+
+from hoho2025.example_solutions import (
+    convert_entry_to_human_readable,
+    filter_vertices_by_background,
+    point_to_segment_dist,
+)
+from hoho2025.color_mappings import gestalt_color_mapping
+
+try:
+    from mvs_utils import (
+        collect_views, triangulate_dlt, mean_reprojection_error,
+        fundamental_matrix, epipolar_line, point_to_line_distance,
+        project_world_to_image,
+    )
+except ImportError:
+    from submission.mvs_utils import (
+        collect_views, triangulate_dlt, mean_reprojection_error,
+        fundamental_matrix, epipolar_line, point_to_line_distance,
+        project_world_to_image,
+    )
+
+
+# Vertex classes we consider (minus 'post' — added later in T1.7 when safe).
+VERTEX_CLASSES = ['apex', 'eave_end_point', 'flashing_end_point']
+EDGE_CLASSES = ['eave', 'ridge', 'rake', 'valley', 'hip']
+
+
+@dataclass
+class Corner:
+    """A 2D corner detected on a single view."""
+    view_id: str
+    xy: np.ndarray          # (2,) float32 pixel coords at COLMAP-native resolution
+    cls: str                # gestalt class label
+    blob_area: int          # area of the connected component, for tie-breaks
+
+
+@dataclass
+class Track:
+    """A 3D wireframe vertex with its per-view observations."""
+    xyz: np.ndarray         # (3,) float64
+    cls: str
+    observations: list[tuple[str, np.ndarray]] = field(default_factory=list)
+    reproj_err: float = float("inf")
+    # view_id → index into corners_per_view[view_id]. Populated by build_tracks
+    # when per-view edges need to be lifted to 3D.
+    corner_indices: dict[str, int] = field(default_factory=dict)
+
+
+def _refine_centroids_subpix(gest_seg_np, centroids, max_shift=4.0, win=5):
+    """cv2.cornerSubPix refinement inside an apex blob. Identical to the
+    version in sklearn_submission.py — duplicated here to keep triangulation.py
+    importable on its own.
+    """
+    if len(centroids) == 0:
+        return centroids
+    gray = cv2.cvtColor(gest_seg_np, cv2.COLOR_RGB2GRAY)
+    gray = cv2.GaussianBlur(gray, (3, 3), 0)
+    pts = np.asarray(centroids, dtype=np.float32).reshape(-1, 1, 2).copy()
+    criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.01)
+    try:
+        refined = cv2.cornerSubPix(gray, pts, (win, win), (-1, -1), criteria)
+    except cv2.error:
+        return centroids
+    refined = refined.reshape(-1, 2)
+    orig = np.asarray(centroids, dtype=np.float32)
+    shifts = np.linalg.norm(refined - orig, axis=1)
+    mask = shifts <= max_shift
+    out = orig.copy()
+    out[mask] = refined[mask]
+    return out
+
+
+def _detect_edges_2d(
+    gest_np: np.ndarray,
+    corners: list[Corner],
+    edge_th: float = 15.0,
+) -> list[tuple[int, int, str]]:
+    """Detect 2D gestalt edges and connect them to existing corner indices.
+
+    Mirrors ``get_vertices_and_edges_improved`` from sklearn_submission but
+    keeps *all* edge classes and returns triples ``(ci, cj, edge_cls)`` so
+    we can aggregate edge-class votes downstream.
+    """
+    if len(corners) < 2:
+        return []
+    apex_pts = np.array([c.xy for c in corners], dtype=np.float32)
+    connections: list[tuple[int, int, str]] = []
+    for edge_class in EDGE_CLASSES:
+        color = np.array(gestalt_color_mapping[edge_class])
+        mask_raw = cv2.inRange(gest_np, color - 0.5, color + 0.5)
+        mask = cv2.morphologyEx(mask_raw, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
+        if mask.sum() == 0:
+            continue
+        _, labels, _, _ = cv2.connectedComponentsWithStats(mask, 8, cv2.CV_32S)
+        for lbl in range(1, labels.max() + 1):
+            ys, xs = np.where(labels == lbl)
+            if len(xs) < 2:
+                continue
+            pts = np.column_stack([xs, ys]).astype(np.float32)
+            line_params = cv2.fitLine(pts, cv2.DIST_L2, 0, 0.01, 0.01)
+            vx, vy, x0, y0 = line_params.ravel()
+            proj = (xs - x0) * vx + (ys - y0) * vy
+            p1 = np.array([x0 + proj.min() * vx, y0 + proj.min() * vy])
+            p2 = np.array([x0 + proj.max() * vx, y0 + proj.max() * vy])
+            dists = np.array(
+                [point_to_segment_dist(apex_pts[i], p1, p2) for i in range(len(apex_pts))]
+            )
+            near = np.where(dists <= edge_th)[0]
+            if len(near) < 2:
+                continue
+            near_pts = apex_pts[near]
+            a = int(near[np.argmin(np.linalg.norm(near_pts - p1, axis=1))])
+            b = int(near[np.argmin(np.linalg.norm(near_pts - p2, axis=1))])
+            if a != b:
+                lo, hi = (a, b) if a < b else (b, a)
+                connections.append((lo, hi, edge_class))
+    return connections
+
+
+def detect_corners_per_view(
+    entry,
+    vertex_classes: list[str] | None = None,
+    filter_background: bool = True,
+    return_edges: bool = False,
+):
+    """Run per-view corner detection + subpixel refinement.
+
+    Returns
+    -------
+    corners_per_view : dict[image_id → list[Corner]]
+    good_entry : the convert_entry_to_human_readable output (caller reuses it)
+    edges_per_view (if ``return_edges``) : dict[image_id → list[(ci, cj, edge_cls)]]
+    """
+    if vertex_classes is None:
+        vertex_classes = VERTEX_CLASSES
+
+    good = convert_entry_to_human_readable(entry)
+    corners_per_view: dict[str, list[Corner]] = {}
+    edges_per_view: dict[str, list[tuple[int, int, str]]] = {}
+
+    for i, (gest, depth, img_id, ade_seg) in enumerate(zip(
+        good['gestalt'], good['depth'], good['image_ids'], good['ade']
+    )):
+        # Native resolution used by the COLMAP camera is the depth resolution
+        # (768×576 in practice). Resize gestalt to match so pixel coordinates
+        # are compatible with our projection matrices.
+        depth_np = np.array(depth)
+        H, W = depth_np.shape[:2]
+        gest_np = np.array(gest.resize((W, H))).astype(np.uint8)
+        ade_np = np.array(ade_seg.resize((W, H))).astype(np.uint8)
+
+        corners: list[Corner] = []
+        for v_class in vertex_classes:
+            color = np.array(gestalt_color_mapping[v_class])
+            mask = cv2.inRange(gest_np, color - 0.5, color + 0.5)
+            if mask.sum() == 0:
+                continue
+            _, _, stats, centroids = cv2.connectedComponentsWithStats(mask, 8, cv2.CV_32S)
+            blob_centroids = centroids[1:]
+            areas = stats[1:, cv2.CC_STAT_AREA]
+            if len(blob_centroids) == 0:
+                continue
+            refined = _refine_centroids_subpix(gest_np, blob_centroids)
+            for xy, area in zip(refined, areas):
+                corners.append(Corner(
+                    view_id=img_id,
+                    xy=np.asarray(xy, dtype=np.float32),
+                    cls=v_class,
+                    blob_area=int(area),
+                ))
+
+        if filter_background and corners:
+            fake_verts = [{"xy": c.xy, "type": c.cls} for c in corners]
+            fake_verts, _ = filter_vertices_by_background(fake_verts, [], ade_np)
+            kept_keys = {(float(v['xy'][0]), float(v['xy'][1]), v['type']) for v in fake_verts}
+            corners = [c for c in corners
+                       if (float(c.xy[0]), float(c.xy[1]), c.cls) in kept_keys]
+
+        corners_per_view[img_id] = corners
+        if return_edges:
+            edges_per_view[img_id] = _detect_edges_2d(gest_np, corners)
+
+    if return_edges:
+        return corners_per_view, good, edges_per_view
+    return corners_per_view, good
+
+
+def build_tracks(
+    corners_per_view: dict[str, list[Corner]],
+    views: dict[str, dict],
+    class_strict: bool = True,
+    epipolar_px: float = 6.0,
+    reproj_px: float = 4.0,
+    min_views: int = 2,
+) -> list[Track]:
+    """Greedy multi-view matching and triangulation with epipolar gating.
+
+    Strategy (classical, mirrors PC2WF / COLMAP incremental triangulation):
+
+    1. Build a pool of unmatched corners from every view.
+    2. For every ordered pair of views compute the fundamental matrix.
+    3. For each corner in view_a, find all corners in view_b of the same class
+       whose perpendicular distance to the epipolar line is below
+       ``epipolar_px``. Triangulate each candidate pair via DLT.
+    4. For each candidate 3D point, reproject it back into every other view.
+       A corner of the same class within ``reproj_px`` of the reprojection
+       becomes an additional observation. Re-triangulate with the enlarged
+       observation list.
+    5. Accept the track if it has ≥ ``min_views`` observations, mean
+       reprojection error < ``reproj_px``, and positive depth everywhere.
+    6. Mark all corners in the track as matched so they are not reused.
+
+    Parameters are intentionally tight — noise-reducing rather than
+    permissive — because a wrongly triangulated vertex can sit meters
+    away from any real roof feature.
+    """
+    # Stable ordering: view ids sorted
+    view_ids = [vid for vid in corners_per_view.keys() if vid in views]
+    view_ids.sort()
+
+    # Index remaining corners (view_id, idx) → Corner
+    remaining: dict[tuple[str, int], Corner] = {}
+    for vid in view_ids:
+        for idx, c in enumerate(corners_per_view[vid]):
+            remaining[(vid, idx)] = c
+
+    tracks: list[Track] = []
+
+    for anchor_vid in view_ids:
+        for (r_vid, r_idx), anchor in list(remaining.items()):
+            if r_vid != anchor_vid:
+                continue
+            # Try matching this anchor against each other view.
+            best_track: Track | None = None
+
+            for other_vid in view_ids:
+                if other_vid == anchor_vid:
+                    continue
+                F = fundamental_matrix(views[anchor_vid], views[other_vid])
+                line = epipolar_line(F, anchor.xy)
+
+                for (o_vid, o_idx), cand in remaining.items():
+                    if o_vid != other_vid:
+                        continue
+                    if class_strict and cand.cls != anchor.cls:
+                        continue
+                    d = point_to_line_distance(line, cand.xy)
+                    if d > epipolar_px:
+                        continue
+
+                    # Two-view DLT
+                    Ps = [views[anchor_vid]["P"], views[other_vid]["P"]]
+                    pts = [anchor.xy, cand.xy]
+                    X = triangulate_dlt(Ps, pts)
+                    if not np.all(np.isfinite(X)):
+                        continue
+
+                    # Extend with all other views that also see this point.
+                    obs = [(anchor_vid, anchor.xy), (other_vid, cand.xy)]
+                    used_keys = {(anchor_vid, r_idx), (other_vid, o_idx)}
+                    for ext_vid in view_ids:
+                        if ext_vid in (anchor_vid, other_vid):
+                            continue
+                        uv, z = project_world_to_image(views[ext_vid]["P"], X.reshape(1, 3))
+                        if z[0] <= 0:
+                            continue
+                        u_pred = uv[0]
+                        best_match = None
+                        best_dist = reproj_px
+                        for (e_vid, e_idx), ec in remaining.items():
+                            if e_vid != ext_vid:
+                                continue
+                            if class_strict and ec.cls != anchor.cls:
+                                continue
+                            d2 = float(np.linalg.norm(ec.xy - u_pred))
+                            if d2 < best_dist:
+                                best_dist = d2
+                                best_match = (e_vid, e_idx, ec)
+                        if best_match is not None:
+                            obs.append((best_match[0], best_match[2].xy))
+                            used_keys.add((best_match[0], best_match[1]))
+
+                    if len(obs) < min_views:
+                        continue
+
+                    # Retriangulate on full observation set for stability
+                    Ps_full = [views[vid]["P"] for vid, _ in obs]
+                    pts_full = [uv for _, uv in obs]
+                    X_full = triangulate_dlt(Ps_full, pts_full)
+                    if not np.all(np.isfinite(X_full)):
+                        continue
+                    err = mean_reprojection_error(X_full, Ps_full, pts_full)
+                    if err > reproj_px:
+                        continue
+
+                    track = Track(
+                        xyz=X_full,
+                        cls=anchor.cls,
+                        observations=obs,
+                        reproj_err=err,
+                    )
+                    track._used_keys = used_keys  # type: ignore[attr-defined]
+                    if best_track is None or len(track.observations) > len(best_track.observations) \
+                       or (len(track.observations) == len(best_track.observations) and err < best_track.reproj_err):
+                        best_track = track
+
+            if best_track is not None:
+                # Freeze the corner-index mapping and forget the private attr.
+                used = getattr(best_track, "_used_keys", set())
+                best_track.corner_indices = {vid: int(idx) for vid, idx in used}
+                try:
+                    delattr(best_track, "_used_keys")
+                except AttributeError:
+                    pass
+                tracks.append(best_track)
+                # Retire matched corners so they aren't reused.
+                for key in used:
+                    remaining.pop(key, None)
+
+    return tracks
+
+
+def get_high_confidence_tracks(
+    entry,
+    min_views: int = 3,
+    max_reproj_px: float = 2.0,
+    epipolar_px: float = 6.0,
+    build_reproj_px: float = 4.0,
+) -> list[Track]:
+    """Run the full triangulation pipeline and return only the tracks
+    that pass a stricter quality gate.
+
+    The default ``min_views=3`` and ``max_reproj_px=2.0`` are tighter
+    than ``predict_wireframe_tracks`` defaults and are designed for
+    using these tracks as **vertex sources** rather than just edge
+    sources. A ≥3-view DLT triangulation with <2 px mean reprojection
+    error has a 3D accuracy of 5–10 cm — substantially better than
+    depth-based unprojection.
+    """
+    tracks, _views, _good = triangulate_wireframe(
+        entry,
+        epipolar_px=epipolar_px,
+        reproj_px=build_reproj_px,
+        min_views=2,
+        want_edges=False,
+    )
+    return [
+        t for t in tracks
+        if len(t.observations) >= min_views and t.reproj_err <= max_reproj_px
+    ]
+
+
+def predict_wireframe_tracks(
+    entry,
+    min_views: int = 2,
+    min_votes: int = 1,
+    epipolar_px: float = 6.0,
+    reproj_px: float = 4.0,
+    merge_radius: float = 0.3,
+) -> tuple[np.ndarray, list[tuple[int, int]]]:
+    """Standalone triangulation-based wireframe predictor.
+
+    Returns (vertices, edges) in the same format as
+    ``predict_wireframe_sklearn`` — ready to feed into ``hss()``.
+    """
+    import numpy as _np
+
+    tracks, _views, _good, t_edges = triangulate_wireframe(
+        entry,
+        epipolar_px=epipolar_px,
+        reproj_px=reproj_px,
+        min_views=min_views,
+        want_edges=True,
+    )
+    if not tracks:
+        return _np.zeros((2, 3), dtype=_np.float64), [(0, 1)]
+
+    xyz = _np.array([t.xyz for t in tracks], dtype=_np.float64)
+
+    # Merge vertices closer than ``merge_radius``. A simple greedy union-find
+    # keyed on first-touched neighbour keeps it O(N^2) but N ≤ 200 in practice.
+    n = len(xyz)
+    parent = list(range(n))
+
+    def find(x):
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(a, b):
+        ra, rb = find(a), find(b)
+        if ra != rb:
+            parent[ra] = rb
+
+    diff = xyz[:, None, :] - xyz[None, :, :]
+    dists = _np.sqrt((diff ** 2).sum(-1))
+    for i in range(n):
+        for j in range(i + 1, n):
+            if dists[i, j] <= merge_radius:
+                union(i, j)
+
+    groups: dict[int, list[int]] = {}
+    for i in range(n):
+        r = find(i)
+        groups.setdefault(r, []).append(i)
+
+    old_to_new: dict[int, int] = {}
+    new_xyz = []
+    for new_idx, (root, members) in enumerate(groups.items()):
+        for m in members:
+            old_to_new[m] = new_idx
+        new_xyz.append(xyz[members].mean(axis=0))
+    new_xyz = _np.array(new_xyz, dtype=_np.float64)
+
+    # Remap edges, dedup
+    edge_set: dict[tuple[int, int], int] = {}
+    for ti, tj, votes in t_edges:
+        if votes < min_votes:
+            continue
+        a = old_to_new[ti]
+        b = old_to_new[tj]
+        if a == b:
+            continue
+        key = (a, b) if a < b else (b, a)
+        edge_set[key] = edge_set.get(key, 0) + votes
+
+    edges = list(edge_set.keys())
+    if not edges or len(new_xyz) < 2:
+        return _np.zeros((2, 3), dtype=_np.float64), [(0, 1)]
+
+    return new_xyz, [(int(a), int(b)) for a, b in edges]
+
+
+def build_track_edges(
+    tracks: list[Track],
+    edges_per_view: dict[str, list[tuple[int, int, str]]],
+    min_votes: int = 1,
+    max_3d_len: float = 8.0,
+) -> list[tuple[int, int, int]]:
+    """Aggregate 3D edges from per-view 2D gestalt edges.
+
+    Parameters
+    ----------
+    tracks : list of Track
+    edges_per_view : dict[view_id → list[(corner_i_idx, corner_j_idx, edge_cls)]]
+    min_votes : minimum number of views that must agree on an edge.
+    max_3d_len : drop edges that would be absurdly long in 3D.
+
+    Returns
+    -------
+    list of (track_i, track_j, vote_count)
+    """
+    # (view_id, corner_idx) → track_idx
+    key_to_track: dict[tuple[str, int], int] = {}
+    for t_idx, t in enumerate(tracks):
+        for vid, cidx in t.corner_indices.items():
+            key_to_track[(vid, cidx)] = t_idx
+
+    votes: dict[tuple[int, int], int] = {}
+    for vid, edges in edges_per_view.items():
+        for ci, cj, _ecls in edges:
+            ti = key_to_track.get((vid, ci))
+            tj = key_to_track.get((vid, cj))
+            if ti is None or tj is None or ti == tj:
+                continue
+            key = (ti, tj) if ti < tj else (tj, ti)
+            votes[key] = votes.get(key, 0) + 1
+
+    out: list[tuple[int, int, int]] = []
+    for (ti, tj), v in votes.items():
+        if v < min_votes:
+            continue
+        d = float(np.linalg.norm(tracks[ti].xyz - tracks[tj].xyz))
+        if d > max_3d_len:
+            continue
+        out.append((ti, tj, v))
+    return out
+
+
+def triangulate_wireframe(
+    entry,
+    epipolar_px: float = 6.0,
+    reproj_px: float = 4.0,
+    min_views: int = 2,
+    want_edges: bool = False,
+):
+    """High-level wrapper: detect corners, build views, triangulate tracks.
+
+    Returns
+    -------
+    (tracks, views, good_entry)
+        when ``want_edges=False`` (default, backwards compatible).
+    (tracks, views, good_entry, track_edges)
+        when ``want_edges=True``. ``track_edges`` is the output of
+        :func:`build_track_edges` — a list of ``(track_i, track_j, vote_count)``.
+    """
+    if want_edges:
+        corners_per_view, good, edges_per_view = detect_corners_per_view(
+            entry, return_edges=True
+        )
+    else:
+        corners_per_view, good = detect_corners_per_view(entry)
+        edges_per_view = None
+
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    views = collect_views(colmap_rec, good['image_ids'])
+    tracks = build_tracks(
+        corners_per_view, views,
+        epipolar_px=epipolar_px,
+        reproj_px=reproj_px,
+        min_views=min_views,
+    )
+    if not want_edges:
+        return tracks, views, good
+    track_edges = build_track_edges(tracks, edges_per_view or {})
+    return tracks, views, good, track_edges
+
+
+# ---------------------------------------------------------------------------
+# T1.6: integration helper — refine an existing depth-based 3D vertex set
+# by snapping each vertex to its closest triangulated track.
+# ---------------------------------------------------------------------------
+
+def refine_vertices_with_tracks(
+    merged_v: np.ndarray,
+    tracks: list[Track],
+    snap_radius: float = 1.0,
+    min_views_for_snap: int = 2,
+    max_reproj_err_px: float = float("inf"),
+) -> tuple[np.ndarray, np.ndarray]:
+    """For each vertex in ``merged_v``, find the closest triangulated track
+    (by 3D distance) and, if it sits within ``snap_radius`` metres, move the
+    vertex to that track's position.
+
+    The graph structure is preserved — only positions move. Tracks with
+    fewer than ``min_views_for_snap`` observations are ignored (2-view DLT
+    is noisy on short baselines).
+
+    Returns
+    -------
+    refined_v : (N, 3) float64 — refined vertex positions
+    snap_mask : (N,)  bool    — True where a snap happened
+    """
+    refined = np.asarray(merged_v, dtype=np.float64).copy()
+    snap = np.zeros(len(refined), dtype=bool)
+
+    good_tracks = [
+        t for t in tracks
+        if len(t.observations) >= min_views_for_snap and t.reproj_err <= max_reproj_err_px
+    ]
+    if not good_tracks or len(refined) == 0:
+        return refined, snap
+
+    track_xyz = np.array([t.xyz for t in good_tracks], dtype=np.float64)
+    for i in range(len(refined)):
+        d = np.linalg.norm(track_xyz - refined[i], axis=1)
+        j = int(np.argmin(d))
+        if d[j] <= snap_radius:
+            refined[i] = track_xyz[j]
+            snap[i] = True
+    return refined, snap
+
+
+def augment_with_tracks(
+    merged_v: np.ndarray,
+    heur_edges: list,
+    tracks: list[Track],
+    dup_radius: float = 0.4,
+    min_views_for_add: int = 3,
+    max_reproj_err_px: float = 2.5,
+) -> tuple[np.ndarray, list]:
+    """Append high-confidence triangulated tracks as new vertices.
+
+    Unlike ``refine_vertices_with_tracks`` (which moves existing vertices and
+    risks regressions on already-good ones), this only adds new points that
+    sit more than ``dup_radius`` metres from any existing vertex.
+
+    The edge list is returned unchanged — new vertices only get edges via the
+    downstream sklearn classifier or heuristic edge-detection step, not here.
+    """
+    merged = np.asarray(merged_v, dtype=np.float64)
+    confident = [t for t in tracks
+                 if len(t.observations) >= min_views_for_add
+                 and t.reproj_err <= max_reproj_err_px]
+    if not confident:
+        return merged, heur_edges
+    tvs = np.array([t.xyz for t in confident], dtype=np.float64)
+    if len(merged) == 0:
+        return tvs, heur_edges
+    # Keep tracks that are not a duplicate of any existing merged vertex.
+    diffs = tvs[:, None, :] - merged[None, :, :]
+    dists = np.sqrt((diffs ** 2).sum(-1))
+    min_d = dists.min(axis=1)
+    new = tvs[min_d > dup_radius]
+    if len(new) == 0:
+        return merged, heur_edges
+    augmented = np.vstack([merged, new])
+    return augmented, heur_edges

winner_candidates.py

@@ -0,0 +1,270 @@
+"""3D vertex candidate generation in the style of the S23DR 2025 winner.
+
+The original baseline (and our v11) detects 2D corners on gestalt images
+then unprojects them via depth — which introduces 30–100 cm of error from
+the monocular depth ambiguity.
+
+The winner generates candidates **directly in 3D** by selecting the COLMAP
+points whose projection lands inside a gestalt corner-class blob:
+
+1. Per view, per gestalt corner class (apex, eave_end_point, flashing_end_point):
+   a. Find connected components of the class mask.
+   b. For each blob, iteratively binary-dilate it until at least
+      ``min_colmap_points`` projected COLMAP points fall inside.
+   c. Record those COLMAP point indices as a "cluster" tagged with class+view.
+
+2. Globally:
+   a. Take the union of all clustered point indices.
+   b. For each cluster compute its 3D centroid, then redefine it as all
+      filtered points within ``cluster_radius`` of that centroid.
+   c. Merge any pair of clusters whose smaller member shares >50% of its
+      points with the other.
+
+The output is a list of 3D vertex candidates with sub-decimetre accuracy
+(limited only by COLMAP triangulation precision).
+
+Entry point: ``generate_winner_candidates(entry)``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import cv2
+from dataclasses import dataclass
+
+from hoho2025.example_solutions import convert_entry_to_human_readable
+from hoho2025.color_mappings import gestalt_color_mapping
+
+try:
+    from mvs_utils import collect_views, project_world_to_image
+except ImportError:
+    from submission.mvs_utils import collect_views, project_world_to_image
+
+
+VERTEX_CLASSES = ['apex', 'eave_end_point', 'flashing_end_point']
+
+
+@dataclass
+class WinnerCandidate:
+    """A 3D vertex candidate produced by the winner-2025 algorithm."""
+    centroid: np.ndarray         # (3,) world coords
+    point_indices: set[int]      # COLMAP point3D indices it owns
+    classes: set[str]            # gestalt vertex classes that voted for it
+    view_count: int              # how many views the cluster came from
+
+
+def _project_colmap_to_view(colmap_xyz: np.ndarray, P: np.ndarray, W: int, H: int):
+    """Return (uv int, in_bounds_mask, in_front_mask)."""
+    uv, z = project_world_to_image(P, colmap_xyz)
+    in_front = z > 0
+    uv_int = np.round(uv).astype(np.int64)
+    in_bounds = (
+        (uv_int[:, 0] >= 0) & (uv_int[:, 0] < W) &
+        (uv_int[:, 1] >= 0) & (uv_int[:, 1] < H)
+    )
+    return uv_int, in_bounds & in_front
+
+
+def _expand_blob_to_min_colmap(
+    blob_mask: np.ndarray,
+    uv_int: np.ndarray,
+    valid_mask: np.ndarray,
+    min_points: int = 5,
+    max_iters: int = 20,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Iteratively dilate a 2D blob mask until at least ``min_points`` of the
+    valid projected COLMAP points fall inside it.
+
+    Returns (final_mask, point_indices_inside).
+    """
+    H, W = blob_mask.shape
+    valid_uv = uv_int[valid_mask]
+    valid_idx = np.where(valid_mask)[0]
+
+    def hit_indices(mask):
+        # Indices into valid_uv that fall inside the mask.
+        # Critical: cast to bool — masks are uint8 0/255 and integer
+        # indexing would otherwise be silently wrong (fancy indexing).
+        h_inside = mask[valid_uv[:, 1], valid_uv[:, 0]] > 0
+        return valid_idx[h_inside]
+
+    inside = hit_indices(blob_mask)
+    if len(inside) >= min_points:
+        return blob_mask, inside
+
+    kernel = np.ones((3, 3), np.uint8)
+    cur = blob_mask.copy()
+    for _ in range(max_iters):
+        cur = cv2.dilate(cur, kernel, iterations=1)
+        inside = hit_indices(cur)
+        if len(inside) >= min_points:
+            return cur, inside
+    return cur, inside
+
+
+def _per_view_clusters(
+    gest_np: np.ndarray,
+    colmap_xyz: np.ndarray,
+    P: np.ndarray,
+    W: int, H: int,
+    view_id: str,
+    min_colmap_points: int = 5,
+    min_blob_area: int = 4,
+) -> list[tuple[set[int], str, str]]:
+    """Yield clusters from a single view.
+
+    Returns list of (point_indices_set, gestalt_class, view_id).
+    """
+    uv_int, valid = _project_colmap_to_view(colmap_xyz, P, W, H)
+    out: list[tuple[set[int], str, str]] = []
+    if not np.any(valid):
+        return out
+
+    for v_class in VERTEX_CLASSES:
+        color = np.array(gestalt_color_mapping[v_class])
+        mask = cv2.inRange(gest_np, color - 0.5, color + 0.5)
+        if mask.sum() == 0:
+            continue
+        n_lbl, lbl, stats, _ = cv2.connectedComponentsWithStats(mask, 8, cv2.CV_32S)
+        for i in range(1, n_lbl):
+            area = int(stats[i, cv2.CC_STAT_AREA])
+            if area < min_blob_area:
+                continue
+            blob_mask = (lbl == i).astype(np.uint8)
+            _, inside = _expand_blob_to_min_colmap(
+                blob_mask, uv_int, valid,
+                min_points=min_colmap_points,
+            )
+            if len(inside) >= min_colmap_points:
+                out.append((set(inside.tolist()), v_class, view_id))
+    return out
+
+
+def _merge_clusters(
+    raw_clusters: list[tuple[set[int], str, str]],
+    colmap_xyz: np.ndarray,
+    cluster_radius: float = 0.5,
+    overlap_threshold: float = 0.5,
+) -> list[WinnerCandidate]:
+    """Global merge step.
+
+    1. Filter the global cloud to points that appear in at least one cluster.
+    2. For each cluster: centroid → all filtered points within cluster_radius.
+    3. Merge any pair sharing >50% of its points (smaller side).
+    """
+    if not raw_clusters:
+        return []
+
+    used_idx = set()
+    for pts, _, _ in raw_clusters:
+        used_idx.update(pts)
+    used_idx_arr = np.array(sorted(used_idx), dtype=np.int64)
+    if len(used_idx_arr) == 0:
+        return []
+    filtered_xyz = colmap_xyz[used_idx_arr]
+    # Map global → filtered index for fast neighbour query
+    g_to_f = -np.ones(len(colmap_xyz), dtype=np.int64)
+    g_to_f[used_idx_arr] = np.arange(len(used_idx_arr))
+
+    # Build KDTree on filtered cloud
+    from scipy.spatial import cKDTree
+    tree = cKDTree(filtered_xyz)
+
+    # Step 2: redefine each cluster by ball query around its centroid
+    candidates: list[WinnerCandidate] = []
+    for pts, cls, vid in raw_clusters:
+        if not pts:
+            continue
+        pts_arr = np.array([p for p in pts if g_to_f[p] >= 0])
+        if len(pts_arr) == 0:
+            continue
+        local = filtered_xyz[g_to_f[pts_arr]]
+        centroid = local.mean(axis=0)
+        # Ball query in 0.5 m
+        nbr_f_idx = tree.query_ball_point(centroid, cluster_radius)
+        if not nbr_f_idx:
+            continue
+        nbr_global = set(int(used_idx_arr[i]) for i in nbr_f_idx)
+        candidates.append(WinnerCandidate(
+            centroid=centroid,
+            point_indices=nbr_global,
+            classes={cls},
+            view_count=1,
+        ))
+
+    if not candidates:
+        return []
+
+    # Step 3: greedy merge by overlap > 50%
+    changed = True
+    while changed:
+        changed = False
+        i = 0
+        while i < len(candidates):
+            j = i + 1
+            while j < len(candidates):
+                a, b = candidates[i], candidates[j]
+                inter = len(a.point_indices & b.point_indices)
+                smaller = min(len(a.point_indices), len(b.point_indices))
+                if smaller > 0 and inter / smaller > overlap_threshold:
+                    # Merge b into a
+                    merged_pts = a.point_indices | b.point_indices
+                    merged_xyz = colmap_xyz[np.array(sorted(merged_pts))]
+                    a.centroid = merged_xyz.mean(axis=0)
+                    a.point_indices = merged_pts
+                    a.classes |= b.classes
+                    a.view_count = a.view_count + b.view_count
+                    candidates.pop(j)
+                    changed = True
+                else:
+                    j += 1
+            i += 1
+
+    return candidates
+
+
+def generate_winner_candidates(
+    entry,
+    min_colmap_points: int = 5,
+    cluster_radius: float = 0.5,
+    overlap_threshold: float = 0.5,
+    min_blob_area: int = 4,
+) -> tuple[list[WinnerCandidate], dict]:
+    """Run the winner-2025 3D vertex candidate generator.
+
+    Returns (candidates, good_entry).
+    """
+    good = convert_entry_to_human_readable(entry)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return [], good
+
+    colmap_xyz = np.array(
+        [p.xyz for p in colmap_rec.points3D.values()], dtype=np.float64
+    )
+    if len(colmap_xyz) == 0:
+        return [], good
+
+    views = collect_views(colmap_rec, good['image_ids'])
+    raw_clusters: list[tuple[set[int], str, str]] = []
+
+    for gest, depth, img_id in zip(good['gestalt'], good['depth'], good['image_ids']):
+        info = views.get(img_id)
+        if info is None:
+            continue
+        depth_np = np.array(depth)
+        H, W = depth_np.shape[:2]
+        gest_np = np.array(gest.resize((W, H))).astype(np.uint8)
+        view_clusters = _per_view_clusters(
+            gest_np, colmap_xyz, info['P'], W, H, img_id,
+            min_colmap_points=min_colmap_points,
+            min_blob_area=min_blob_area,
+        )
+        raw_clusters.extend(view_clusters)
+
+    candidates = _merge_clusters(
+        raw_clusters, colmap_xyz,
+        cluster_radius=cluster_radius,
+        overlap_threshold=overlap_threshold,
+    )
+    return candidates, good

winner_inference.py

@@ -0,0 +1,267 @@
+"""Inference adapter for the winner-2025 pipeline.
+
+Loads:
+  - DGCNN vertex classifier (3 heads: cls/offset/conf)
+  - DGCNN edge classifier (1 head)
+
+And exposes:
+  - refine_winner_candidates(candidates, sample, model, device, threshold)
+        For each candidate, build the 4×4×4 m cubic patch with 11D point
+        features (winner spec), run the model, return only candidates that
+        pass the classification threshold and were shifted to the model's
+        offset.
+  - score_edges(vertices, sample, model, device, threshold)
+        For each pair of vertices within MAX_PAIR_DIST, build the 6D
+        cylindrical patch and ask the model whether the edge exists.
+
+Both functions degrade gracefully if torch is missing or the checkpoint
+is not found — they return None and the caller falls back to the
+heuristic pipeline.
+"""
+
+from __future__ import annotations
+
+import os
+import numpy as np
+from pathlib import Path
+
+# Lazy torch import — only required at training/inference time, not at
+# submission package import time.
+_torch = None
+_DGCNNVertexClassifier = None
+_DGCNNEdgeClassifier = None
+
+
+def _ensure_torch():
+    global _torch, _DGCNNVertexClassifier, _DGCNNEdgeClassifier
+    if _torch is not None:
+        return True
+    try:
+        import torch as _t
+        _torch = _t
+    except Exception:
+        return False
+    # Try multiple import paths for DGCNN classes:
+    # 1. Full package (local development)
+    # 2. Submission-directory copy (HF container)
+    for _module_path in [
+        "s23dr.models.dgcnn",
+        "dgcnn",
+        "submission.dgcnn",
+    ]:
+        try:
+            _mod = __import__(_module_path, fromlist=["DGCNNVertexClassifier", "DGCNNEdgeClassifier"])
+            _DGCNNVertexClassifier = _mod.DGCNNVertexClassifier
+            _DGCNNEdgeClassifier = _mod.DGCNNEdgeClassifier
+            break
+        except Exception:
+            continue
+    if _DGCNNVertexClassifier is None:
+        return False
+    return True
+
+
+def _resolve_model_path(path: str) -> str | None:
+    """Try multiple locations for a model checkpoint."""
+    candidates = [
+        path,
+        os.path.join(os.path.dirname(__file__), os.path.basename(path)),
+        os.path.join(os.path.dirname(__file__), path),
+        os.path.basename(path),
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    return None
+
+
+def load_vertex_model(path="checkpoints/vertex_model_dgcnn.pt", device="cuda"):
+    if not _ensure_torch():
+        return None
+    path = _resolve_model_path(path)
+    if path is None:
+        return None
+    try:
+        ckpt = _torch.load(path, map_location=device, weights_only=False)
+        state = ckpt['model'] if isinstance(ckpt, dict) and 'model' in ckpt else ckpt
+        model = _DGCNNVertexClassifier(in_channels=11).to(device)
+        model.load_state_dict(state)
+        model.eval()
+        return model
+    except Exception:
+        return None
+
+
+def load_edge_model(path="checkpoints/edge_model_dgcnn.pt", device="cuda"):
+    if not _ensure_torch():
+        return None
+    path = _resolve_model_path(path)
+    if path is None:
+        return None
+    try:
+        ckpt = _torch.load(path, map_location=device, weights_only=False)
+        state = ckpt['model'] if isinstance(ckpt, dict) and 'model' in ckpt else ckpt
+        model = _DGCNNEdgeClassifier(in_channels=6).to(device)
+        model.load_state_dict(state)
+        model.eval()
+        return model
+    except Exception:
+        return None
+
+
+def refine_winner_candidates(
+    candidates,
+    sample,
+    model,
+    device="cuda",
+    cls_threshold: float = 0.5,
+    apply_offset: bool = True,
+    batch_size: int = 64,
+    max_points: int = 1024,
+    patch_size: float = 4.0,
+):
+    """Run DGCNN vertex refinement on Stage 1 winner candidates.
+
+    Args:
+        candidates: list of dicts from generate_vertex_candidates
+            (each must have 'xyz' and 'point_ids').
+        sample: raw HF dataset entry.
+        model: loaded DGCNNVertexClassifier (or compatible).
+        device: torch device.
+        cls_threshold: keep candidate if sigmoid(cls_logit) ≥ threshold.
+        apply_offset: shift accepted candidates by predicted offset.
+
+    Returns:
+        list of (xyz, score) for accepted candidates, OR None on failure.
+    """
+    if model is None or not candidates:
+        return None
+    if not _ensure_torch():
+        return None
+
+    try:
+        from hoho2025.example_solutions import convert_entry_to_human_readable
+        from s23dr.data_prep.patch_extraction import (
+            _get_all_points_with_features, _project_and_get_gestalt_labels,
+            extract_vertex_patch,
+        )
+    except Exception:
+        return None
+
+    good = convert_entry_to_human_readable(sample)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return None
+
+    all_xyz, all_rgb, all_pids = _get_all_points_with_features(colmap_rec)
+    if len(all_xyz) == 0:
+        return None
+
+    depth_shapes = [(np.array(d).shape[0], np.array(d).shape[1]) for d in good['depth']]
+    all_gestalt = _project_and_get_gestalt_labels(
+        all_xyz, colmap_rec, good['gestalt'], good['image_ids'], depth_shapes,
+    )
+
+    patches = []
+    cand_idx = []
+    for i, cand in enumerate(candidates):
+        patch = extract_vertex_patch(
+            cand['xyz'], all_xyz, all_rgb, all_gestalt,
+            cand.get('point_ids', set()), all_pids,
+            patch_size=patch_size, max_points=max_points,
+        )
+        if patch is None:
+            continue
+        patches.append(patch)
+        cand_idx.append(i)
+    if not patches:
+        return []
+
+    accepted = []
+    with _torch.no_grad():
+        for start in range(0, len(patches), batch_size):
+            end = min(start + batch_size, len(patches))
+            batch = np.stack(patches[start:end], axis=0)  # (B, 11, N)
+            x = _torch.from_numpy(batch).to(device)
+            cls_logits, pred_offset, pred_conf = model(x)
+            cls_logits = cls_logits.squeeze(-1).cpu().numpy()
+            pred_offset = pred_offset.cpu().numpy()
+            pred_conf = pred_conf.squeeze(-1).cpu().numpy()
+            probs = 1.0 / (1.0 + np.exp(-cls_logits))
+            for k in range(end - start):
+                if probs[k] < cls_threshold:
+                    continue
+                ci = cand_idx[start + k]
+                xyz = candidates[ci]['xyz'].copy()
+                if apply_offset:
+                    xyz = xyz + pred_offset[k]
+                accepted.append((xyz.astype(np.float64), float(probs[k])))
+    return accepted
+
+
+def score_edges(
+    vertices: np.ndarray,
+    sample,
+    model,
+    device: str = "cuda",
+    threshold: float = 0.5,
+    max_pair_dist: float = 8.0,
+    batch_size: int = 64,
+    max_points: int = 1024,
+):
+    """Run DGCNN edge classifier over all vertex pairs within max_pair_dist.
+
+    Returns list of (i, j, prob) for pairs where the model says "edge".
+    """
+    if model is None or vertices is None or len(vertices) < 2:
+        return None
+    if not _ensure_torch():
+        return None
+
+    try:
+        from hoho2025.example_solutions import convert_entry_to_human_readable
+        from s23dr.data_prep.patch_extraction import (
+            _get_all_points_with_features, extract_edge_patch,
+        )
+    except Exception:
+        return None
+
+    good = convert_entry_to_human_readable(sample)
+    colmap_rec = good.get('colmap') or good.get('colmap_binary')
+    if colmap_rec is None:
+        return None
+    all_xyz, all_rgb, _ = _get_all_points_with_features(colmap_rec)
+    if len(all_xyz) == 0:
+        return None
+
+    n = len(vertices)
+    pairs = []
+    patches = []
+    for i in range(n):
+        for j in range(i + 1, n):
+            dist = float(np.linalg.norm(vertices[i] - vertices[j]))
+            if dist > max_pair_dist:
+                continue
+            patch = extract_edge_patch(
+                vertices[i], vertices[j], all_xyz, all_rgb, max_points=max_points,
+            )
+            if patch is None:
+                continue
+            pairs.append((i, j))
+            patches.append(patch)
+    if not patches:
+        return []
+
+    out = []
+    with _torch.no_grad():
+        for start in range(0, len(patches), batch_size):
+            end = min(start + batch_size, len(patches))
+            batch = np.stack(patches[start:end], axis=0)
+            x = _torch.from_numpy(batch).to(device)
+            logits = model(x).squeeze(-1).cpu().numpy()
+            probs = 1.0 / (1.0 + np.exp(-logits))
+            for k in range(end - start):
+                if probs[k] >= threshold:
+                    i, j = pairs[start + k]
+                    out.append((int(i), int(j), float(probs[k])))
+    return out