reconstruct3d 0.1.0__py3-none-any.whl

reconstruct3d/dense_mvs.py

@@ -0,0 +1,256 @@
+"""MVS-lite: densificación por stereo de dos vistas usando las poses ya estimadas.
+
+Para cada par de frames vecinos registrados:
+  1. Calcula la pose relativa entre las dos cámaras.
+  2. Rectifica el par (stereoRectify + remap) -> filas epipolares alineadas.
+  3. Disparidad densa con StereoSGBM.
+  4. Retroproyecta a 3D (reprojectImageTo3D) en el frame rectificado.
+  5. Transforma esos puntos al mundo con la pose conocida y acumula.
+
+No es MVS "real" (sin fusión multi-vista ni refinamiento de profundidad), pero
+convierte la nube rala (~30k pts) en una densa usando solo OpenCV en CPU. La
+calidad depende del baseline: pares con poca traslación se descartan.
+
+Entrada: map_state.npy (poses) + video. Salida: dense_cloud.ply.
+"""
+import os
+import argparse
+import threading
+from concurrent.futures import ThreadPoolExecutor
+import numpy as np
+import cv2
+from tqdm import tqdm
+
+from reconstruct3d.core import CameraConfig, MAP_STATE_FILE, resolve_workers
+from reconstruct3d.init_sfm import export_ply
+
+DENSE_CLOUD_FILE = "dense_cloud.ply"
+
+# StereoSGBM tampoco es thread-safe si se comparte; un objeto por hilo.
+_tls_dense = threading.local()
+
+
+def _tls_sgbm(num_disp, block):
+    s = getattr(_tls_dense, "sgbm", None)
+    if s is None or getattr(_tls_dense, "cfg", None) != (num_disp, block):
+        s = _make_sgbm(num_disp, block)
+        _tls_dense.sgbm = s
+        _tls_dense.cfg = (num_disp, block)
+    return s
+
+
+def _relative_pose(P_a, P_b):
+    """R,T que llevan un punto de la cámara A a la cámara B (X_b = R X_a + T).
+    Poses son world->cam (4x4)."""
+    R_a, t_a = P_a[:3, :3], P_a[:3, 3]
+    R_b, t_b = P_b[:3, :3], P_b[:3, 3]
+    R_rel = R_b @ R_a.T
+    t_rel = t_b - R_rel @ t_a
+    return R_rel, t_rel
+
+
+def _make_sgbm(num_disp=128, block=5):
+    return cv2.StereoSGBM_create(
+        minDisparity=0,
+        numDisparities=num_disp,         # múltiplo de 16
+        blockSize=block,
+        P1=8 * 3 * block ** 2,
+        P2=32 * 3 * block ** 2,
+        disp12MaxDiff=1,
+        uniquenessRatio=10,
+        speckleWindowSize=100,
+        speckleRange=2,
+        mode=cv2.STEREO_SGBM_MODE_SGBM_3WAY,
+    )
+
+
+def _voxel_downsample(pts, colors, voxel):
+    if voxel <= 0 or len(pts) == 0:
+        return pts, colors
+    keys = np.floor(pts / voxel).astype(np.int64)
+    _, idx = np.unique(keys, axis=0, return_index=True)
+    return pts[idx], colors[idx]
+
+
+def densify_pair(frame_a, frame_b, P_a, P_b, K, sgbm, max_depth):
+    """Devuelve (pts_world Nx3, colors_bgr Nx3) del par. Vacío si falla."""
+    h, w = frame_a.shape[:2]
+    dist = np.zeros(5)
+    R_rel, t_rel = _relative_pose(P_a, P_b)
+
+    R1, R2, P1, P2, Q, _, _ = cv2.stereoRectify(
+        K, dist, K, dist, (w, h), R_rel, t_rel.reshape(3, 1),
+        flags=cv2.CALIB_ZERO_DISPARITY, alpha=0,
+    )
+    # La profundidad reconstruida es Z ≈ f / (disp · Q[3,2]), así que para que
+    # las disparidades positivas de SGBM den Z>0 hace falta Q[3,2] > 0. Si sale
+    # negativo, TODO quedaría con Z<0 y se descartaría: intercambiamos A<->B
+    # (lo que invierte el signo de Q[3,2]) y re-rectificamos.
+    if Q[3, 2] < 0:
+        frame_a, frame_b = frame_b, frame_a
+        P_a, P_b = P_b, P_a
+        R_rel, t_rel = _relative_pose(P_a, P_b)
+        R1, R2, P1, P2, Q, _, _ = cv2.stereoRectify(
+            K, dist, K, dist, (w, h), R_rel, t_rel.reshape(3, 1),
+            flags=cv2.CALIB_ZERO_DISPARITY, alpha=0,
+        )
+
+    m1x, m1y = cv2.initUndistortRectifyMap(K, dist, R1, P1, (w, h), cv2.CV_32FC1)
+    m2x, m2y = cv2.initUndistortRectifyMap(K, dist, R2, P2, (w, h), cv2.CV_32FC1)
+    rect_a = cv2.remap(frame_a, m1x, m1y, cv2.INTER_LINEAR)
+    rect_b = cv2.remap(frame_b, m2x, m2y, cv2.INTER_LINEAR)
+
+    disp = sgbm.compute(cv2.cvtColor(rect_a, cv2.COLOR_BGR2GRAY),
+                        cv2.cvtColor(rect_b, cv2.COLOR_BGR2GRAY)).astype(np.float32) / 16.0
+
+    pts_rect = cv2.reprojectImageTo3D(disp, Q)
+    Z = pts_rect[:, :, 2]
+    mask = (disp > sgbm.getMinDisparity()) & np.isfinite(pts_rect).all(axis=2) & (Z > 0)
+    if mask.sum() < 50:
+        return np.empty((0, 3)), np.empty((0, 3), np.uint8)
+
+    pts = pts_rect[mask]
+    colors = rect_a[mask]  # BGR, alineado con la imagen rectificada izquierda
+
+    # Recorte de profundidad: percentiles del propio par + tope global
+    zr = pts[:, 2]
+    lo, hi = np.percentile(zr, 2), np.percentile(zr, 98)
+    hi = min(hi, max_depth)
+    keep = (zr >= lo) & (zr <= hi)
+    pts, colors = pts[keep], colors[keep]
+
+    # rectificado-izq -> cámara A original -> mundo
+    pts_cam = (R1.T @ pts.T).T
+    R_a, t_a = P_a[:3, :3], P_a[:3, 3]
+    pts_world = (R_a.T @ (pts_cam - t_a).T).T
+    return pts_world, colors
+
+
+def _multiview_fuse(all_keys, all_pts, all_cols, min_views):
+    """Votación por vóxel: agrupa puntos por celda y conserva solo las celdas
+    confirmadas por >= min_views PARES distintos (cada par aporta <=1 punto por
+    celda). Devuelve posición y color promedio por celda. Esto elimina el ruido
+    SGBM de un solo par (un match espurio no lo confirma ningún otro par)."""
+    keys = np.concatenate(all_keys); pts = np.concatenate(all_pts)
+    cols = np.concatenate(all_cols).astype(np.float64)
+    uniq, inv, cnt = np.unique(keys, axis=0, return_inverse=True, return_counts=True)
+    sum_p = np.zeros((len(uniq), 3)); np.add.at(sum_p, inv, pts)
+    sum_c = np.zeros((len(uniq), 3)); np.add.at(sum_c, inv, cols)
+    keep = cnt >= min_views
+    mean_p = (sum_p[keep] / cnt[keep, None])
+    mean_c = (sum_c[keep] / cnt[keep, None]).astype(np.uint8)
+    return mean_p, mean_c, int(keep.sum()), len(uniq)
+
+
+def run_dense(out_dir, video_path, neighbor_steps=(1, 2), min_views=2,
+              num_disp=128, block=5, voxel=0.0, jobs=0):
+    map3d = np.load(os.path.join(out_dir, MAP_STATE_FILE), allow_pickle=True).item()
+    cam = CameraConfig.from_dict(map3d.get('camera'))  # intrínsecos del map_state
+    K = cam.K
+    frames = sorted(map3d['poses'].keys())
+    poses = map3d['poses']
+
+    centers = np.array([(-(poses[f][:3, :3].T @ poses[f][:3, 3:]).ravel()) for f in frames])
+    pts_sparse = np.asarray(map3d['points'])
+    pts_sparse = pts_sparse[np.isfinite(pts_sparse).all(axis=1)]
+    scale = float(np.median(np.linalg.norm(pts_sparse - centers.mean(axis=0), axis=1)))
+    seg = np.linalg.norm(np.diff(centers, axis=0), axis=1)
+    min_baseline = 0.3 * float(np.median(seg))
+    max_depth = 5.0 * scale
+    if voxel <= 0:
+        voxel = scale / 400.0
+    print(f"[MVS] escala~{scale:.2f}  baseline_min={min_baseline:.3f}  max_depth={max_depth:.1f}  "
+          f"voxel={voxel:.4f}  neighbor_steps={list(neighbor_steps)}  min_views={min_views}")
+
+    # Caché de frames (cada uno se decodifica una sola vez; clave para que la
+    # fusión multi-vista con muchos pares no relea el video 4K repetidamente).
+    cap = cv2.VideoCapture(video_path)
+    cache = {}
+    for f in tqdm(frames, desc="Cargando frames"):
+        cap.set(cv2.CAP_PROP_POS_FRAMES, f)
+        ret, fr = cap.read()
+        if ret:
+            cache[f] = cam.preprocess(fr)
+    cap.release()
+
+    workers = resolve_workers(jobs)
+    all_keys, all_pts, all_cols = [], [], []
+    used = skipped = 0
+
+    pairs = [(i, i + s) for i in range(len(frames)) for s in neighbor_steps if i + s < len(frames)]
+
+    # Cada par es independiente -> se paraleliza. densify_pair es CPU-bound
+    # (StereoSGBM libera el GIL), así que los hilos dan speedup real.
+    def _task(pair):
+        i, j = pair
+        fa, fb = frames[i], frames[j]
+        if fa not in cache or fb not in cache:
+            return None
+        if np.linalg.norm(_relative_pose(poses[fa], poses[fb])[1]) < min_baseline:
+            return "skip"
+        pw, cl = densify_pair(cache[fa], cache[fb], poses[fa], poses[fb], K,
+                              _tls_sgbm(num_disp, block), max_depth)
+        if len(pw) == 0:
+            return None
+        # 1 punto por vóxel por par -> el conteo por celda = nº de pares que la ven
+        pw, cl = _voxel_downsample(pw, cl, voxel)
+        return np.floor(pw / voxel).astype(np.int64), pw, cl
+
+    print(f"[MVS] densificando {len(pairs)} pares con {workers} hilos...")
+    if workers == 1:
+        results = (_task(p) for p in tqdm(pairs, desc="Densificando (multi-vista)"))
+        results = list(results)
+    else:
+        with ThreadPoolExecutor(max_workers=workers) as ex:
+            results = list(tqdm(ex.map(_task, pairs), total=len(pairs),
+                                desc="Densificando (multi-vista)"))
+    for r in results:
+        if r is None:
+            continue
+        if r == "skip":
+            skipped += 1
+            continue
+        keys, pw, cl = r
+        all_keys.append(keys); all_pts.append(pw); all_cols.append(cl)
+        used += 1
+
+    if not all_pts:
+        print("[MVS] No se generaron puntos densos.")
+        return
+
+    if min_views <= 1:
+        pts = np.concatenate(all_pts); cols = np.concatenate(all_cols)
+        pts, cols = _voxel_downsample(pts, cols, voxel)
+        n_kept, n_total = len(pts), len(pts)
+    else:
+        pts, cols, n_kept, n_total = _multiview_fuse(all_keys, all_pts, all_cols, min_views)
+
+    print(f"[MVS] pares usados={used} saltados={skipped}  celdas={n_total:,}  "
+          f"conservadas(>={min_views} vistas)={n_kept:,}")
+
+    median_pt = np.median(pts, axis=0)
+    out_path = os.path.join(out_dir, DENSE_CLOUD_FILE)
+    export_ply(out_path, pts - median_pt, cols, [])
+    print(f"[MVS] nube densa: {len(pts):,} puntos -> {out_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="MVS multi-vista: densificación stereo + fusión por consistencia")
+    parser.add_argument("video", help="Path al video original (mp4/MOV).")
+    parser.add_argument("--out", required=True, help="Output dir con map_state.npy.")
+    parser.add_argument("--neighbor-steps", type=str, default="1,2",
+                        help="Offsets de vecinos para cada frame de referencia (default '1,2'). "
+                             "Más vecinos = más cobertura y más votos de consistencia.")
+    parser.add_argument("--min-views", type=int, default=2,
+                        help="Conservar solo puntos confirmados por >= N pares distintos (default 2; "
+                             "1 = sin fusión). Más alto = más limpio pero menos denso.")
+    parser.add_argument("--num-disp", type=int, default=128, help="numDisparities SGBM (múltiplo de 16, default 128).")
+    parser.add_argument("--block", type=int, default=5, help="blockSize SGBM (impar, default 5).")
+    parser.add_argument("--voxel", type=float, default=0.0,
+                        help="Tamaño de vóxel para fusión/downsample (default 0 = automático según escala).")
+    parser.add_argument("--jobs", type=int, default=0,
+                        help="Hilos para densificar pares (0=auto=nº de CPUs; 1=secuencial).")
+    args = parser.parse_args()
+    steps = tuple(int(s) for s in args.neighbor_steps.split(",") if s.strip())
+    run_dense(args.out, args.video, neighbor_steps=steps, min_views=args.min_views,
+              num_disp=args.num_disp, block=args.block, voxel=args.voxel, jobs=args.jobs)

reconstruct3d/init_sfm.py

@@ -0,0 +1,151 @@
+import os
+import sys
+import argparse
+import cv2
+import numpy as np
+import pandas as pd
+from reconstruct3d.core import (
+    SfMDatabase, Features, create_frontend,
+    filter_triangulation,
+    DB_FILE, MAP_STATE_FILE, INIT_CLOUD_FILE,
+)
+
+# Inyección en el namespace para permitir la deserialización de pickle
+sys.modules['__main__'].Features = Features
+
+def export_ply(filename, points3d, colors, cameras=[]):
+    with open(filename, 'w') as f:
+        f.write("ply\nformat ascii 1.0\n")
+        f.write(f"element vertex {len(points3d) + len(cameras)}\n")
+        f.write("property float x\nproperty float y\nproperty float z\n")
+        f.write("property uchar red\nproperty uchar green\nproperty uchar blue\n")
+        f.write("end_header\n")
+        for pt, c in zip(points3d, colors):
+            f.write(f"{pt[0]} {pt[1]} {pt[2]} {int(c[2])} {int(c[1])} {int(c[0])}\n") # BGR to RGB
+        for cam in cameras:
+            f.write(f"{cam[0]} {cam[1]} {cam[2]} 255 0 0\n") # Cámaras en rojo
+
+def _try_seed_pair(frontend, fi, fj, cam):
+    """Triangula + filtra un par candidato. Siempre retorna dict con diagnósticos;
+    'viable' indica si el seed es usable."""
+    res = {'viable': False, 'n_matches': 0, 'e_count': 0, 'chir_count': 0, 'kept_count': 0}
+    matches = frontend.match(fi, fj)
+    res['n_matches'] = len(matches)
+    if len(matches) < 20:
+        return res
+
+    pts1 = fi.pts[[m[0] for m in matches]]
+    pts2 = fj.pts[[m[1] for m in matches]]
+    colors = fi.colors[[m[0] for m in matches]]
+
+    E, mask_E = cv2.findEssentialMat(pts1, pts2, cam.K, cv2.RANSAC, 0.999, 1.0)
+    if E is None or E.shape != (3, 3):
+        return res
+    res['e_count'] = int(mask_E.sum())
+
+    # Pasar TODOS los matches a recoverPose (no solo E-inliers): los outliers
+    # actúan como tiebreakers para que la votación de chiralidad elija la
+    # descomposición correcta de E (las 4 son casi empatadas si solo das
+    # E-inliers en escenas con baseline corta).
+    _, R, t, mask_pose = cv2.recoverPose(E, pts1, pts2, cam.K)
+    chir_idx = np.where(mask_pose.ravel() > 0)[0]
+    res['chir_count'] = len(chir_idx)
+    if len(chir_idx) < 20:
+        return res
+
+    pts1_v, pts2_v = pts1[chir_idx], pts2[chir_idx]
+    colors_v = colors[chir_idx]
+
+    P1 = cam.K @ np.hstack((np.eye(3), np.zeros((3, 1))))
+    P2 = cam.K @ np.hstack((R, t))
+    pts4d = cv2.triangulatePoints(P1, P2, pts1_v.T, pts2_v.T)
+    pts3d = (pts4d[:3, :] / pts4d[3, :]).T
+
+    pose_i = np.eye(4)
+    pose_j = np.vstack((np.hstack((R, t)), [0, 0, 0, 1]))
+    keep = filter_triangulation(pts3d, pose_i, pose_j, pts1_v, pts2_v, cam.K,
+                                max_reproj_err=10.0, min_angle_deg=1.0)
+    final_idx = chir_idx[keep]
+    res.update({
+        'viable': int(keep.sum()) >= 20,
+        'matches': matches,
+        'pts3d': pts3d[keep], 'colors': colors_v[keep],
+        'pose_i': pose_i, 'pose_j': pose_j, 'R': R, 't': t,
+        'kept_count': int(keep.sum()),
+        'valid_idx_kept': final_idx,
+    })
+    return res
+
+
+def init_reconstruction(out_dir):
+    db = SfMDatabase()
+    db.load(os.path.join(out_dir, DB_FILE))
+    print(f"[*] Frontend leído de la DB: '{db.frontend_name}'")
+    frontend = create_frontend(db.frontend_name)
+
+    df = pd.DataFrame(db.pairwise)
+    df['gap'] = (df['frame_j'] - df['frame_i']).abs()
+    top = df.sort_values("inliers", ascending=False).head(20)
+    strong = top[top['inliers'] >= 0.6 * top['inliers'].iloc[0]]
+    candidates = strong.sort_values('gap', ascending=False)
+
+    cam = db.get_camera()  # intrínsecos persistidos en la DB (o defaults)
+    MIN_SEED_POINTS = 25
+
+    best, tried = None, []
+    print("[*] Probando candidatos seed (orden: mayor baseline primero):")
+    for _, row in candidates.iterrows():
+        i, j = int(row['frame_i']), int(row['frame_j'])
+        res = _try_seed_pair(frontend, db.features[i], db.features[j], cam)
+        res.update({'i': i, 'j': j, 'inliers_db': int(row['inliers']), 'gap': int(row['gap'])})
+        flag = "OK" if res['viable'] else "skip"
+        print(f"    ({i:4d},{j:4d}) gap={res['gap']:2d}  db_inl={res['inliers_db']:4d}  "
+              f"matches={res['n_matches']:4d}  E={res['e_count']:4d}  chir={res['chir_count']:4d}  "
+              f"kept={res['kept_count']:4d}  [{flag}]")
+        if res['viable']:
+            tried.append(res)
+            if res['kept_count'] >= MIN_SEED_POINTS:
+                best = res
+                break
+
+    if best is None:
+        if not tried:
+            raise RuntimeError("No se encontró ningún seed pair viable.")
+        best = max(tried, key=lambda r: r['kept_count'])
+        print(f"[!] Ningún seed alcanzó {MIN_SEED_POINTS} pts; tomando el mejor disponible "
+              f"({best['kept_count']} pts).")
+
+    i, j = best['i'], best['j']
+    matches = best['matches']
+    pts3d, colors_v = best['pts3d'], best['colors']
+    pose_i, pose_j = best['pose_i'], best['pose_j']
+    R, t = best['R'], best['t']
+    valid_idx_kept = best['valid_idx_kept']
+    print(f"[*] Seed elegido: ({i}, {j})  gap={best['gap']}  puntos finales={best['kept_count']}")
+
+    # Map3D State
+    map3d = {
+        'points': pts3d, 'colors': colors_v,
+        'poses': {i: pose_i, j: pose_j},
+        # Registros: {frame_id: {kp_idx: pt3d_idx}}
+        'obs': {
+            i: {matches[k][0]: idx for idx, k in enumerate(valid_idx_kept)},
+            j: {matches[k][1]: idx for idx, k in enumerate(valid_idx_kept)}
+        },
+        'frontend': db.frontend_name,
+        'camera': cam.to_dict(),  # propaga los intrínsecos a las etapas que solo leen map_state
+    }
+
+    os.makedirs(out_dir, exist_ok=True)
+    np.save(os.path.join(out_dir, MAP_STATE_FILE), map3d)
+
+    cam_centers = [np.zeros(3), -R.T @ t.ravel()]
+    ply_path = os.path.join(out_dir, INIT_CLOUD_FILE)
+    export_ply(ply_path, pts3d, colors_v, cam_centers)
+    print(f"Triangulación inicial: {len(pts3d)} puntos. Exportado a {ply_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="SfM init: triangulate seed pair from DB")
+    parser.add_argument("--out", required=True, help="Output dir containing sfm_data.pkl (from core.py).")
+    args = parser.parse_args()
+    init_reconstruction(args.out)

reconstruct3d/mesh.py

@@ -0,0 +1,99 @@
+"""Etapa de mallado: reconstruye una malla triangulada desde la nube densa usando
+CGAL (Advancing Front o Poisson).
+
+El cómputo lo hace un pequeño programa en C++ (`cgal_mesh/mesh_reconstruct.cpp`)
+que enlaza CGAL. Este módulo se encarga de **compilarlo bajo demanda** (CMake) la
+primera vez y luego invocarlo sobre `dense_cloud.ply` (o la nube que se indique)
+para producir `mesh.ply`.
+
+Requisitos del sistema (no se instalan con uv, son nativos): CGAL, boost, gmp,
+mpfr, eigen, cmake y un compilador C++. En macOS: `brew install cgal cmake eigen`.
+
+Uso:
+    uv run python mesh.py --out outputs/sift
+    uv run python mesh.py --out outputs/sift --method poisson --smooth 24
+"""
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+
+DENSE_CLOUD_FILE = "dense_cloud.ply"
+MESH_FILE = "mesh.ply"
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+CGAL_DIR = os.path.join(_HERE, "cgal_mesh")
+BUILD_DIR = os.path.join(CGAL_DIR, "build")
+BINARY = os.path.join(BUILD_DIR, "mesh_reconstruct")
+
+
+def ensure_built(force=False):
+    """Compila el binario CGAL si falta (o si --force). Devuelve la ruta al binario."""
+    if os.path.exists(BINARY) and not force:
+        return BINARY
+    if shutil.which("cmake") is None:
+        raise RuntimeError(
+            "cmake no está instalado. Instala las dependencias nativas de CGAL:\n"
+            "  macOS:  brew install cgal cmake eigen boost gmp mpfr\n"
+            "  Debian: sudo apt install libcgal-dev cmake libeigen3-dev")
+    print(f"[mesh] compilando el binario CGAL en {BUILD_DIR} ...")
+    subprocess.run(["cmake", "-S", CGAL_DIR, "-B", BUILD_DIR,
+                    "-DCMAKE_BUILD_TYPE=Release"], check=True)
+    subprocess.run(["cmake", "--build", BUILD_DIR, "-j",
+                    str(os.cpu_count() or 2)], check=True)
+    if not os.path.exists(BINARY):
+        raise RuntimeError(f"La compilación terminó pero no se encontró {BINARY}")
+    return BINARY
+
+
+def run_mesh(out_dir, input_ply=None, method="afront", outlier_pct=2.0,
+             simplify=0.0, smooth=0, mesh_smooth=2, min_component=0.002,
+             afront_radius=5.0, poisson_spacing_mult=1.0, rebuild=False):
+    """Genera out_dir/mesh.ply desde la nube densa (o input_ply) con CGAL."""
+    binary = ensure_built(force=rebuild)
+    src = input_ply or os.path.join(out_dir, DENSE_CLOUD_FILE)
+    if not os.path.exists(src):
+        raise FileNotFoundError(
+            f"No existe la nube de entrada '{src}'. Corre primero `dense` "
+            "(o pasa la ruta del .ply).")
+    dst = os.path.join(out_dir, MESH_FILE)
+
+    cmd = [binary, src, dst,
+           "--method", method,
+           "--outlier-pct", str(outlier_pct),
+           "--simplify", str(simplify),
+           "--smooth", str(smooth),
+           "--mesh-smooth", str(mesh_smooth),
+           "--min-component", str(min_component),
+           "--afront-radius", str(afront_radius),
+           "--poisson-spacing-mult", str(poisson_spacing_mult)]
+    print(f"[mesh] {' '.join(cmd)}")
+    subprocess.run(cmd, check=True)
+    print(f"[mesh] malla escrita en {dst}")
+    return dst
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Mallado de la nube densa con CGAL.")
+    p.add_argument("--out", required=True, help="Directorio con dense_cloud.ply (y donde se escribe mesh.ply).")
+    p.add_argument("--input", default=None, help="Nube .ply de entrada (default: <out>/dense_cloud.ply).")
+    p.add_argument("--method", choices=["afront", "poisson"], default="afront",
+                   help="afront=interpola puntos, conserva color, bordes abiertos (default). "
+                        "poisson=superficie suave/cerrada, tolera ruido.")
+    p.add_argument("--outlier-pct", type=float, default=2.0, help="%% de outliers a eliminar (0=off).")
+    p.add_argument("--simplify", type=float, default=0.0,
+                   help="Celda de grid simplify (0=auto~spacing; <0=sin simplificar).")
+    p.add_argument("--smooth", type=int, default=0, help="Vecinos de jet smooth de PUNTOS (0=off).")
+    p.add_argument("--mesh-smooth", type=int, default=2,
+                   help="Iteraciones de suavizado tangencial de la MALLA (default 2; 0=off).")
+    p.add_argument("--min-component", type=float, default=0.002,
+                   help="Elimina componentes < FRAC*caras, p.ej. islas de ruido (default 0.002; 0=off).")
+    p.add_argument("--afront-radius", type=float, default=5.0, help="Longitud máx. de arista (x spacing).")
+    p.add_argument("--poisson-spacing-mult", type=float, default=1.0, help="Multiplicador de spacing para Poisson.")
+    p.add_argument("--rebuild", action="store_true", help="Recompilar el binario CGAL.")
+    args = p.parse_args()
+    run_mesh(args.out, input_ply=args.input, method=args.method, outlier_pct=args.outlier_pct,
+             simplify=args.simplify, smooth=args.smooth, mesh_smooth=args.mesh_smooth,
+             min_component=args.min_component, afront_radius=args.afront_radius,
+             poisson_spacing_mult=args.poisson_spacing_mult, rebuild=args.rebuild)