reconstruct3d 0.1.0__tar.gz

reconstruct3d-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+# Se dispara solo al empujar un tag de versión (ej. v0.2.0). El tag define la
+# versión publicada (la lee hatch-vcs). Para publicar:  git tag v0.2.0 && git push --tags
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Construir distribución
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs necesita el historial completo + tags para calcular la versión.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build (sdist + wheel)
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publicar en PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Debe coincidir con el "Environment name" del Trusted Publisher en PyPI.
+    environment: pypi
+    permissions:
+      # OIDC: token efímero para Trusted Publishing. SIN tokens ni passwords.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

reconstruct3d-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv*/
+.env
+.venv
+
+# Build artifacts
+build/
+dist/
+
+# IDE
+.vscode/
+.idea/
+
+# Input videos (heavy binaries, keep the folder via .gitkeep)
+data/*
+!data/.gitkeep
+!data/README.md
+
+# Runtime outputs (regenerated by the pipeline)
+outputs/
+*.pkl
+*.npy
+*.ply
+!pruebas1/*.ply
+
+# OS noise
+.DS_Store
+Thumbs.db

reconstruct3d-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

reconstruct3d-0.1.0/CLAUDE.md

@@ -0,0 +1,203 @@
+# CLAUDE.md — Contexto del proyecto para agentes de IA
+
+> Este archivo orienta a Claude Code (y otros agentes) sobre **qué es** este
+> proyecto, **cómo está organizado** y **cómo trabajar en él** sin romper nada.
+> Léelo antes de proponer cambios.
+
+## Qué es (y qué NO es)
+
+Pipeline **offline** de reconstrucción 3D a partir de un video monocular. El
+nombre del repo dice "SLAM", pero técnicamente esto es **Structure-from-Motion
+(SfM) incremental + densificación MVS-lite**, no SLAM:
+
+- **NO** es tiempo real, **NO** hay loop-closure ni mapeo online.
+- Procesa un video ya grabado por **etapas secuenciales** que escriben artefactos
+  a disco.
+- El "tracking" de cámara se hace con **PnP** (`cv2.solvePnPRansac`), no con un
+  filtro recursivo.
+
+El emparejamiento de features tiene **3 front-ends intercambiables** (no uno
+solo): `sift` (default), `orb`, y `spglue` (SuperPoint + LightGlue, requiere
+torch). LightGlue es **opcional**, no el camino por defecto.
+
+## Arquitectura: el pipeline de 6 etapas
+
+Todas las etapas comparten un **directorio de salida** (`outputs/<frontend>/`)
+donde leen/escriben artefactos. El orden importa: cada etapa consume lo que
+produjo la anterior.
+
+```
+video.mp4
+   │
+   ▼  [1] core.py ............ extrae features + matrices esenciales por pares
+sfm_data.pkl
+   │
+   ▼  [2] init_sfm.py ........ triangula el "par semilla" (mejor baseline)
+map_state.npy + init_cloud.ply
+   │
+   ▼  [3] track_sfm.py ....... registro incremental PnP + BA local + fusión
+tracked_cloud.ply  (nube rala/sparse)
+   │
+   ▼  [4] bundle_adjust.py ... BA GLOBAL opcional (refina todo el mapa)
+map_state.npy (refinado)
+   │
+   ▼  [5] dense_mvs.py ....... densificación stereo SGBM + fusión multi-vista
+dense_cloud.ply  (nube densa)
+   │
+   ▼  [6] viewer.py .......... visor POV interactivo (proyecta puntos sobre video)
+```
+
+### Estructura de paquete (importante)
+
+El código se reorganizó como **paquete instalable `reconstruct3d/`**. Los módulos
+de la tabla viven ahora en `reconstruct3d/<módulo>.py` (no en la raíz), con
+**imports absolutos** `from reconstruct3d.X import ...`. Piezas nuevas:
+
+- `reconstruct3d/api.py` — **API de alto nivel** (clase `Pipeline` con callback
+  `on_event` para progreso). Es la forma recomendada de usar la librería desde
+  código; `reconstruct3d/__init__.py` exporta `Pipeline`, `run_all`, `CameraConfig`.
+- `reconstruct3d/cli.py` — el orquestador CLI (antes `pipeline.py`). El `pipeline.py`
+  de la raíz es solo un **shim** `from reconstruct3d.cli import main`. Console script
+  instalado: `reconstruct3d`.
+- `reconstruct3d/cgal_mesh/` — el programa C++ se movió aquí (mesh.py lo localiza
+  vía `dirname(__file__)`).
+- `backend/` (FastAPI) y `frontend/` (Vite+React+Three.js) — **demo**, NO forman
+  parte del paquete publicado.
+- `pyproject.toml` — paquete con hatchling. **torch/lightglue NO van en deps base**
+  (solo en el extra `spglue`), porque lightglue no está en PyPI y torch es pesado.
+  Para dev local, `[tool.uv.sources]` resuelve lightglue desde git.
+
+### Mapa de archivos
+
+| Archivo | Rol | Entradas → Salidas |
+|---|---|---|
+| [pipeline.py](pipeline.py) | **Orquestador CLI**. Punto de entrada único; subcomandos `extract/init/track/ba/dense/view/all`. | — |
+| [core.py](core.py) | Config de cámara, clase `Features`, front-ends (`SiftFrontEnd`, `OrbFrontEnd`, `SuperPointLightGlueFrontEnd`), `SfMDatabase`, `filter_triangulation`. **Módulo base que todos importan.** | video → `sfm_data.pkl` |
+| [init_sfm.py](init_sfm.py) | Selección de par semilla + triangulación inicial. Define `export_ply`. | `sfm_data.pkl` → `map_state.npy`, `init_cloud.ply` |
+| [track_sfm.py](track_sfm.py) | Registro incremental de cámaras (PnP) + inyección de puntos nuevos. | `map_state.npy` → `tracked_cloud.ply` |
+| [bundle_adjust.py](bundle_adjust.py) | `run_local_ba` (ventana, usado por track), `run_bundle_adjustment` (global), `fuse_map_points`. | `map_state.npy` → `map_state.npy` |
+| [dense_mvs.py](dense_mvs.py) | MVS de dos vistas (rectify + StereoSGBM) + fusión por votación de vóxel. **Paralelizado** (`jobs`). | `map_state.npy` + video → `dense_cloud.ply` |
+| [viewer.py](viewer.py) | Visor interactivo OpenCV (sliders de frame y opacidad). | `map_state.npy` + video |
+| [calibrate.py](calibrate.py) | Calibración de `K` desde un video de tablero (`cv2.calibrateCamera`). Modo automático e interactivo. Escribe/crea `camera.json`. | video tablero → `camera.json` |
+| [chunked.py](chunked.py) | Reconstrucción por fragmentos solapados (procesos en paralelo) + alineación Sim(3) por Umeyama sobre centros de cámara compartidos + fusión. | video → `merged_cloud.ply`, `merged_state.npy` |
+| [mesh.py](mesh.py) + [cgal_mesh/](cgal_mesh/) | Mallado de la nube densa con **CGAL** (C++). `mesh.py` compila el binario bajo demanda (CMake) y lo invoca; `mesh_reconstruct.cpp` hace denoise + Advancing Front / Poisson. | `dense_cloud.ply` → `mesh.ply` |
+
+### Estructuras de datos clave
+
+- **`CameraConfig`** (core.py): intrínsecos `K`, `dist_coeffs`, `PROC_SIZE`.
+  Parametrizable y serializable (`to_dict`/`from_dict`/`from_json`). `from_dict`
+  acepta K explícita o el atajo `fx/fy/cx/cy` + `width/height`.
+- **`Features`** (core.py): `pts (N,2)`, `descriptors`, `colors (N,3 BGR)`,
+  `scores`, `image_size`. Serializada en `sfm_data.pkl` vía pickle.
+- **`SfMDatabase`** (core.py / `sfm_data.pkl`): `features`, `pairwise`,
+  `frontend_name`, **`camera`** (dict de `CameraConfig.to_dict()`). `get_camera()`
+  devuelve la `CameraConfig` persistida.
+- **`map3d`** (dict en `map_state.npy`, cargado con `np.load(..., allow_pickle=True).item()`):
+  - `points (M,3)`, `colors (M,3)`
+  - `poses`: `{frame_id: matriz 4x4 world→cam}`
+  - `obs`: `{frame_id: {kp_idx: punto3d_idx}}` — la tabla de observaciones que
+    conecta keypoints 2D con puntos 3D. **Es el corazón del estado**; BA y
+    fusión la reindexan.
+  - `frontend`: nombre del front-end usado.
+  - `camera`: dict de intrínsecos (lo copia `init` desde la DB; lo leen las etapas
+    que solo cargan map_state: `dense`, `view`).
+
+## Comandos (con uv)
+
+`uv` gestiona el entorno. **No uses `pip` ni venvs manuales.**
+
+```bash
+uv sync                      # instala dependencias base (sift/orb)
+uv sync --extra spglue       # + torch/torchvision/lightglue (para --frontend spglue)
+
+# Pipeline completo end-to-end:
+uv run python pipeline.py all data/video.mp4
+uv run python pipeline.py all data/video.mp4 --frontend spglue --no-dense
+
+# Calibración / paralelización / videos largos:
+uv run python pipeline.py calibrate data/calib.mp4 --board 9x6   # crea camera.json
+uv run python pipeline.py all data/video.mp4 --jobs 8            # paraleliza
+uv run python pipeline.py chunked data/video.mp4 --chunk 80 --overlap 20 --chunk-jobs 4
+uv run python pipeline.py mesh --method afront                   # malla CGAL (requiere CGAL nativo)
+
+# Etapa por etapa (mismo --out implícito = outputs/<frontend>/):
+uv run python pipeline.py extract data/video.mp4
+uv run python pipeline.py init
+uv run python pipeline.py track
+uv run python pipeline.py ba          # opcional pero recomendado
+uv run python pipeline.py dense data/video.mp4
+uv run python pipeline.py view data/video.mp4
+```
+
+Los scripts individuales (`core.py`, etc.) **siguen funcionando** vía
+`uv run python core.py video.mp4 --out ...`; el orquestador solo los encadena.
+
+## Convenciones del código
+
+- **Idioma:** comentarios, docstrings y mensajes de consola en **español**.
+  Los nombres de variables/funciones en inglés. Mantén esa mezcla.
+- **Comentarios densos y explicativos:** el código existente comenta el *porqué*
+  de cada decisión geométrica/numérica (chiralidad, baseline, gauge del BA…).
+  Iguala ese nivel; no añadas comentarios triviales.
+- **Convención de poses:** todas las matrices `4x4` son **world→cam**. El centro
+  de cámara es `-R.T @ t`. Respétalo en todo el código nuevo.
+- **Front-ends:** para añadir uno, hereda de `FrontEnd` (core.py), implementa
+  `extract`/`match` y regístralo en `_FRONTEND_REGISTRY`. Los imports pesados
+  (torch) van **lazy** dentro de `__init__`.
+- **Salida vía `export_ply`** (init_sfm.py): la nube se exporta **centrada** en
+  la mediana y los colores se guardan BGR→RGB. Las cámaras van en rojo.
+
+## Gotchas / cosas que romper sin querer
+
+- **Pickles atados al layout.** `sfm_data.pkl` guarda objetos `Features`; los
+  scripts hacen `sys.modules['__main__'].Features = Features` para poder
+  deserializarlos. Si reorganizas `core.py` como paquete, los pickles viejos
+  dejan de cargar (`ModuleNotFoundError`). Los artefactos en `outputs/` del repo
+  son de un layout empaquetado anterior y **no cargan con los scripts planos
+  actuales** — regenéralos con `extract`.
+- **Intrínsecos por dispositivo.** `K` depende de la cámara que grabó. Se
+  configura con `--camera tu_camara.json` en `extract`/`all` (ver
+  `camera.example.json`), o se genera con `calibrate`. Se persiste en la DB +
+  map_state, propagándose a todas las etapas. **No vuelvas a hardcodear K**. `K` y
+  `PROC_SIZE` deben corresponder a la MISMA resolución (el frame se redimensiona a
+  `PROC_SIZE` antes de extraer). La resolución de calibración (`proc_size`) debe
+  tener el punto principal ≈ centro: si `cx,cy` no caen cerca de `W/2,H/2`, la
+  resolución es incorrecta.
+- **Paralelismo y thread-safety.** Extracción/matching (core) y densificación
+  (dense_mvs) usan `ThreadPoolExecutor` con `--jobs`. Los objetos de OpenCV
+  (SIFT/ORB/BFMatcher/StereoSGBM) **no son thread-safe compartidos** → cada hilo
+  crea el suyo vía `threading.local` (`tls_frontend`, `_tls_sgbm`). Si añades una
+  etapa paralela, replica ese patrón; no compartas el detector entre hilos. Para
+  `spglue` el paralelismo se fuerza a 1 (`resolve_workers`). Los resultados
+  paralelos son idénticos al modo secuencial (verificado).
+- **Mallado nativo (CGAL).** El paso `mesh` NO es Python puro: usa un binario C++
+  (`cgal_mesh/mesh_reconstruct.cpp`) que enlaza **CGAL** (header-only) + boost/gmp/
+  mpfr/eigen, compilado con CMake. `mesh.py` lo compila bajo demanda en
+  `cgal_mesh/build/` la primera vez. Si CGAL no está, `all` **omite** el mallado
+  con un aviso (no falla). CGAL 6.x cambió APIs respecto a 5.x: `property_map`
+  devuelve `std::optional`, los parámetros usan `CGAL::parameters::`. Advancing
+  Front conserva el color (vértices = puntos de entrada); Poisson genera vértices
+  nuevos y transfiere color por KD-tree (vecino más cercano).
+- **Chunking y alineación.** `chunked.py` reconstruye fragmentos en **procesos**
+  separados (`ProcessPoolExecutor`, start method `spawn` en macOS → el worker
+  `_run_chunk_worker` y su `cfg` deben ser top-level/picklables). La alineación
+  necesita **≥4 frames de solape no degenerados**: con <4 la Sim(3) de Umeyama
+  queda subdeterminada (ajusta el solape pero no recupera la rotación global).
+  Todos los chunks muestrean la MISMA rejilla global de `k_skip` para que los
+  frames del solape tengan índices absolutos idénticos.
+- **Reset del estado.** Si `track` se estanca, vuelve a correr `init` antes de
+  reintentar (reinicia `map_state.npy`).
+- **`req.txt` es legacy** (un `pip freeze` inflado con open3d/dash/sklearn que el
+  código NO usa). La fuente de verdad de dependencias es `pyproject.toml`.
+- **Escenas degeneradas.** Paneos sobre superficies planas o arranques de
+  casi-rotación pura no producen seed viable (paralaje ~0). Usa `--start-seconds`
+  para saltar arranques malos.
+- **macOS/Wayland + visor.** `viewer.py` abre ventanas OpenCV HighGUI; en
+  entornos headless o Wayland puede fallar. En Arch/Wayland: `env -u WAYLAND_DISPLAY ...`.
+
+## Carpetas
+
+- `data/` — videos de entrada (ignorada por git salvo `.gitkeep`).
+- `outputs/` — artefactos regenerables (ignorada por git).
+- `pruebas1/` — **scripts experimentales antiguos** (SfM/VO previos). No forman
+  parte del pipeline actual; no los uses como referencia de la arquitectura viva.

reconstruct3d-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlackMonkcr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.