How pals-ttic/fastmap works
Project Type and Purpose
• FastMap is an open-source, command-line structure-from-motion (SfM) pipeline implemented in Python and PyTorch.
• It ingests a COLMAP database of matched keypoints (generated externally by COLMAP’s feature extractor and matcher) and a directory of input images, then estimates camera poses, triangulates a sparse 3D point cloud, and optionally visualizes the result.
File-Structure Analysis
• Top-level:
• run.py – main CLI entry point for SfM pipeline
• eval.py – evaluation utilities
• assets/ – static images (e.g., teaser)
• fastmap/ (core package):
• config.py – dataclass definitions for hyperparameters and YAML loader
• engine.py – orchestrates end-to-end pipeline
• database.py, io.py – read/write COLMAP database and model files
• Modules for geometric estimation:
– fundamental.py, essential.py, homography.py, epipolar.py
– decompose.py, rotation.py, translation.py, rel_t.py, focal.py, distortion.py
• sparse.py, track.py, point_pair.py – triangulation and track management
• vis.py – interactive 3D viewer (uses pyrender/pyglet)
Key README Insights
• Two-stage workflow: (1) COLMAP feature extraction & matching → SQLite DB; (2) FastMap pose estimation & triangulation → COLMAP-format output + viewer
• Configurable via YAML; single-GPU PyTorch backend; headless or interactive mode; supports various camera models and flags
a. Main Components
• External Component: COLMAP Feature Extractor & Matcher
• CLI Layer: run.py (invokes config loader and Engine)
• Configuration Loader: fastmap/config.py (YAML → dataclass)
• Core Pipeline Engine: fastmap/engine.py
• Submodules (grouped by function):
– I/O: fastmap/database.py, fastmap/io.py
– Geometry Estimation: fundamental, essential, homography, epipolar, distortion, focal
– Pose Decomposition & Optimization: decompose, rotation, translation, rel_t
– Sparse Reconstruction: sparse, track, point_pair
• Output Writer: populates output_dir in COLMAP format (sparse/0)
• Visualization Module: fastmap/vis.py (standalone CLI entry: python -m fastmap.vis)
b. Relationships & Data Flow
• run.py → loads config → instantiates Engine
• Engine reads COLMAP DB via database.py
• Engine loops over image-pairs/tracks: geometric estimation modules → pose decomposition → track management
• sparse.py triangulates points → assembled into output files by io.py
• timer and logging track performance
• Upon completion, files saved in output_dir; vis.py reads these for rendering
c. Architectural Patterns & Principles
• Modular pipeline: clear separation of concerns (I/O, geometry, optimization, visualization)
• Dependency injection via config dataclasses
• Single-process orchestrator (Engine) coordinating stateless functional modules
d. Technologies & Frameworks
• Python 3.x, PyTorch (tensor ops, GPU support)
• COLMAP (external tool, SQLite DB)
• YAML for configuration
• pyrender/pyglet for visualization
• Standard libs: logging (loguru), profiling (psutil), data handling (trimesh)
Final Recommendations
• Configuration entry points (CLI flags, YAML) feeding into the Engine
• Optional visualization path separately from the core SfM path