# aibluefisher/dagsfm architecture

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

- Interactive diagram: https://gitdiagram.com/aibluefisher/dagsfm
- Repository: https://github.com/aibluefisher/dagsfm

## Overview

##### Project Type and Purpose
- This is a high-performance C++ library for structure-from-motion (SfM) that supports both sequential and distributed processing.
- It is designed for large-scale image reconstructions where images are clustered, processed in parallel (using a master-worker model), and then merged.
- The library integrates a broad set of submodules (feature extraction, matching, clustering, estimation, optimization, etc.) and leverages external libraries (e.g., Eigen, FLANN, SiftGPU, igraph, rpclib, and others).

##### File Structure
- Top-Level Directories: Notice directories like src (main code), lib (integrated third-party libraries such as FLANN, Graclus, PoissonRecon, SiftGPU, Spectra, VLFeat, and mirror), scripts (build and helper scripts), docker (deployment container files), docs/doc (documentation), and cmake (CMake modules).
- In the src directory, components are divided by function:
– “base”: Fundamental data structures (camera, image, reconstruction, tracks, etc.).
– “controllers”: High-level modules for reconstruction (e.g., automatic reconstruction, incremental mapping, distributed mapper, bundle adjustment).
– “clustering”: Various clustering methods (NCut, Spectral, community detection) for image grouping.
– “estimators”, “math”, “mvs” (multi-view stereo), “graph”, “ransac”, “retrieval”, “rotation_estimation”, “solver”, “optim”: Modules dealing with estimation, optimization, geometric and algebraic computations.
– “map_reduce”: Implements the distributed or remote execution workflow which leverages the map-reduce paradigm.
– “ui”: GUI components (using Qt) which, although not integrated with the SfM pipeline directly, offer visualization of reconstruction results.
- Build and configuration files (CMakeLists.txt, cmake modules) reveal the project’s cross-platform and modular build approach.

##### Key Insights from the README
- The README explains build dependencies and usage for both sequential and distributed modes.
- Distributed Mode: The project uses rpclib for establishing RPC servers on worker nodes. A master node dispatches tasks to workers (configured via a “config.txt” file).
- It emphasizes various pipeline stages, such as feature extraction, clustering, and bundle adjustment. It notes integration with COLMAP (a known SfM tool) though this code represents an independent algorithmic extension.

a. Main Components:
- Input (Image Data Repository): Represents the source of images (stored on disk).
- Feature Extraction Module: Deals with image features using libraries like SiftGPU, VLFeat, etc.
- Matching & Graph Construction:
▪ Feature Matching (maybe using FLANN) to build similarity/ image graphs.
▪ Graph components: “Image Graph”, “Similarity Graph”, “View Graph” – used for clustering and graph-based filtering.
- Clustering & Partitioning:
▪ Modules under “clustering” and techniques like NCut, Spectral Clustering, and Community Detection.
- Estimation & Reconstruction:
▪ Core SfM modules in “base”, “estimators”, “sfm”, “solvers” – perform camera pose estimation, triangulation, and bundle adjustment.
- Optimization:
▪ Bundle adjustment routines and other solvers (for rotations, translations).
- Distributed Processing and MapReduce:
▪ Master Node: Coordinates distributed tasks in sequential/distributed modes.
▪ Worker Nodes: Smaller processes (set up using rpclib RPC servers) that perform local reconstructions.
▪ MapReduce Framework: Modules in “map_reduce” that dispatch jobs and aggregate results.
- Optional GUI and Visualization:
▪ “ui” modules that provide interactive visualizations of reconstructions.
- External Libraries and Dependencies:
▪ Support libraries from “lib”: FLANN, Graclus, LSD, PoissonRecon, SQLite, Spectra, VLFeat, etc.
▪ Build system support (CMake, scripts, docker).

b. Relationships and Interactions:
- Data Flow: Raw images are processed in the feature extraction module; resulting features are passed to matching & graph construction, which then feeds the clustering and partitioning modules.
- Clustering creates subsets/clusters of images which are then passed to local SfM routines (either running sequentially or distributed).
- In distributed mode, the master node dispatches clusters to worker nodes via RPC (rpclib) for local reconstruction.
- After local mapping, results are merged and refined (bundle adjustment, final optimization).
- The UI (if used) may read from the final outputs (e.g., COLMAP’s data files).
- The MapReduce module orchestrates distributed tasks, and various scripts automate the pipeline.

c. Architectural Patterns and Technologies:
- Modular Design: Separation of concerns across features, geometry, graph algorithms, optimization, and distributed control.
- Distributed / MapReduce Pattern: Master-worker architecture using RPC (rpclib) and a configuration file to coordinate processes.
- Use of Third-Party Libraries: Integration of libraries such as Eigen for linear algebra, FLANN for nearest neighbor search, and igraph for graph operations.
- Build & Deployment: CMake as the build system, Docker for containerized builds.

##### Additional Notes
- Be very detailed in capturing all essential architectural elements. For example, include subcomponents like “estimators”, “optimization”, “graph algorithms”, and “UI” if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core SfM Pipeline
    subgraph "Core SfM Pipeline"
        A["Image Data Repository"] 
        FE["Feature Extraction"]
        subgraph "Matching & Graph Construction"
            FM["Feature Matching"]
            GC["Graph Construction"]
        end
        CP["Clustering & Partitioning"]
        subgraph "Estimation & Reconstruction"
            ES["Estimation Data Structures"]
            EST["Estimators"]
            LR["Local Reconstruction"]
        end
        OPT["Optimization (Bundle Adjustment)"]
        
        A --> FE
        FE --> FM
        FM --> GC
        GC --> CP
        CP --> ES
        ES --> EST
        EST --> LR
        LR --> OPT
    end

    %% Distributed Orchestration
    subgraph "Distributed Orchestration"
        MN["Master Node"]
        WN["Worker Node"]
        MR["MapReduce Framework"]
        
        OPT --> MN
        MN --> WN
        WN --> MR
        MR --> OPT
    end

    %% GUI Component
    UI["GUI and Visualization"]
    OPT --> UI

    %% External Libraries and Dependencies
    EL["External Libraries & Dependencies"]

    %% Dotted external connections
    FE --- EL
    FM --- EL
    GC --- EL
    CP --- EL
    EST --- EL
    OPT --- EL
    MN --- EL

    %% Click Events
    click FE "https://github.com/aibluefisher/dagsfm/blob/dev/src/feature/extraction.cc"
    click FM "https://github.com/aibluefisher/dagsfm/blob/dev/src/feature/matching.cc"
    click GC "https://github.com/aibluefisher/dagsfm/tree/dev/src/graph"
    click CP "https://github.com/aibluefisher/dagsfm/tree/dev/src/clustering"
    click ES "https://github.com/aibluefisher/dagsfm/tree/dev/src/base"
    click EST "https://github.com/aibluefisher/dagsfm/blob/dev/src/estimators/essential_matrix.cc"
    click LR "https://github.com/aibluefisher/dagsfm/blob/dev/src/sfm/incremental_mapper.cc"
    click OPT "https://github.com/aibluefisher/dagsfm/blob/dev/src/optim/bundle_adjustment.cc"
    click MN "https://github.com/aibluefisher/dagsfm/blob/dev/src/map_reduce/master.cpp"
    click WN "https://github.com/aibluefisher/dagsfm/blob/dev/src/map_reduce/worker.cpp"
    click UI "https://github.com/aibluefisher/dagsfm/blob/dev/src/ui/main_window.cc"
    click EL "https://github.com/aibluefisher/dagsfm/tree/dev/lib"

    %% Styles
    class A,FE,FM,GC,CP,ES,EST,LR,OPT coreModule
    class MN,WN,MR distributed
    class UI ui
    class EL external

    classDef coreModule fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef distributed fill:#ffcce6,stroke:#333,stroke-width:2px;
    classDef ui fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#e6ffe6,stroke:#333,stroke-width:2px;
```
