# pals-ttic/fastmap architecture

> Architecture diagram of the GitHub repository pals-ttic/fastmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pals-ttic/fastmap
- Repository: https://github.com/pals-ttic/fastmap

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    External["COLMAP Feature Extractor & Matcher"]:::external
    CLI["run.py (CLI)"]:::cli
    CONFIG["fastmap/config.py (Configuration Loader)"]:::config

    subgraph "Engine (fastmap/engine.py)"
        direction TB
        IO1["fastmap/database.py"]:::io
        IO2["fastmap/io.py"]:::io

        subgraph "Geometry Estimation"
            direction TB
            F["fastmap/fundamental.py"]:::geometry
            E["fastmap/essential.py"]:::geometry
            H["fastmap/homography.py"]:::geometry
            EP["fastmap/epipolar.py"]:::geometry
            D["fastmap/distortion.py"]:::geometry
            FO["fastmap/focal.py"]:::geometry
        end

        subgraph "Pose Decomposition & Optimization"
            direction TB
            DE["fastmap/decompose.py"]:::opt
            RO["fastmap/rotation.py"]:::opt
            TR["fastmap/translation.py"]:::opt
            RT["fastmap/rel_t.py"]:::opt
        end

        subgraph "Sparse Reconstruction & Track Management"
            direction TB
            SP["fastmap/sparse.py"]:::io
            TRK["fastmap/track.py"]:::io
            PP["fastmap/point_pair.py"]:::io
        end

        subgraph "Utilities"
            direction TB
            C["fastmap/container.py"]:::util
            T["fastmap/timer.py"]:::util
            U["fastmap/utils.py"]:::util
            CO["fastmap/color.py"]:::util
        end
    end

    OUTPUT["Output Writer (COLMAP format)"]:::io
    VIS["fastmap/vis.py (3D Viewer)"]:::vis
    EVAL["eval.py (Evaluation Utilities)"]:::external
    ASSETS["assets/ (Static Assets)"]:::external

    External -->|"COLMAP DB & Images"| CLI
    CLI -->|"loads config"| CONFIG
    CLI -->|"instantiates Engine"| IO1
    IO1 -->|"reads DB"| IO2
    IO2 -->|"image pairs"| F
    F -->|"estimated geometries"| DE
    DE -->|"decomposed poses"| SP
    SP -->|"triangulated points"| OUTPUT
    OUTPUT -->|"COLMAP-format output"| VIS

    EVAL -->|"optional eval"| CLI
    ASSETS -->|"static data"| CLI

    click CLI "https://github.com/pals-ttic/fastmap/blob/main/run.py"
    click EVAL "https://github.com/pals-ttic/fastmap/blob/main/eval.py"
    click ASSETS "https://github.com/pals-ttic/fastmap/tree/main/assets/"
    click CONFIG "https://github.com/pals-ttic/fastmap/blob/main/fastmap/config.py"
    click IO1 "https://github.com/pals-ttic/fastmap/blob/main/fastmap/database.py"
    click IO2 "https://github.com/pals-ttic/fastmap/blob/main/fastmap/io.py"
    click F "https://github.com/pals-ttic/fastmap/blob/main/fastmap/fundamental.py"
    click E "https://github.com/pals-ttic/fastmap/blob/main/fastmap/essential.py"
    click H "https://github.com/pals-ttic/fastmap/blob/main/fastmap/homography.py"
    click EP "https://github.com/pals-ttic/fastmap/blob/main/fastmap/epipolar.py"
    click D "https://github.com/pals-ttic/fastmap/blob/main/fastmap/distortion.py"
    click FO "https://github.com/pals-ttic/fastmap/blob/main/fastmap/focal.py"
    click DE "https://github.com/pals-ttic/fastmap/blob/main/fastmap/decompose.py"
    click RO "https://github.com/pals-ttic/fastmap/blob/main/fastmap/rotation.py"
    click TR "https://github.com/pals-ttic/fastmap/blob/main/fastmap/translation.py"
    click RT "https://github.com/pals-ttic/fastmap/blob/main/fastmap/rel_t.py"
    click SP "https://github.com/pals-ttic/fastmap/blob/main/fastmap/sparse.py"
    click TRK "https://github.com/pals-ttic/fastmap/blob/main/fastmap/track.py"
    click PP "https://github.com/pals-ttic/fastmap/blob/main/fastmap/point_pair.py"
    click C "https://github.com/pals-ttic/fastmap/blob/main/fastmap/container.py"
    click T "https://github.com/pals-ttic/fastmap/blob/main/fastmap/timer.py"
    click U "https://github.com/pals-ttic/fastmap/blob/main/fastmap/utils.py"
    click CO "https://github.com/pals-ttic/fastmap/blob/main/fastmap/color.py"
    click VIS "https://github.com/pals-ttic/fastmap/blob/main/fastmap/vis.py"

    classDef external fill:#dddddd,stroke:#888888,color:#333333
    classDef cli fill:#ffcc00,stroke:#886600,color:#333333
    classDef config fill:#ff99ff,stroke:#cc66cc,color:#333333
    classDef io fill:#ccccff,stroke:#6666cc,color:#333333
    classDef geometry fill:#ccffcc,stroke:#66cc66,color:#333333
    classDef opt fill:#ffcc99,stroke:#cc9966,color:#333333
    classDef util fill:#ffe699,stroke:#cc9933,color:#333333
    classDef vis fill:#e0ccff,stroke:#9966cc,color:#333333
```
