# lhanaf/mild architecture

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

- Interactive diagram: https://gitdiagram.com/lhanaf/mild
- Repository: https://github.com/lhanaf/mild

## Overview

##### Project Type and Purpose
- This is a native C++ loop‐closure detection library and command‐line tool (“MILD”) used in visual SLAM. It ingests an image sequence and configuration settings, runs binary‐feature based matching and Bayesian filtering, and outputs loop‐closure hypotheses for downstream evaluation (Octave/MATLAB).

##### File Structure Analysis
Top‐level:
- CMakeLists.txt – build orchestrator
- main.cpp – CLI entry point (“./mild imagelist.txt settings.yaml”)
- settings.yaml, imagelist.txt – runtime parameters and input list
- data/ – ground‐truth .mat file for evaluation
- evaluation.m, run_scritp.m – post‐hoc accuracy scripts
- frame.cpp/.h, global.h – core data structures and global definitions
- MILD/ – library source
– loop_closure_detector.cpp/.h – orchestrates detection pipeline
– sparse_match.cpp/.h – binary‐feature matcher
– BayesianFilter.hpp – probabilistic scoring
– lightweight_vector.hpp – performance‐optimized containers
– mild.hpp – façade header collecting all submodules

##### Key Insights from README
- Dependencies: OpenCV 3.1, Eigen3 (matrix ops), optional Octave for evaluation
- Usage: run CLI, then call evaluation(…) to compare lcd_shared_flag.bin vs truthNewCollege.mat
- Output: three binary‐flag and score streams per frame in build/output/...

A. CLI Frontend (“mild”)
- Parses imagelist.txt (list of RGB image paths)
- Parses settings.yaml (feature & filter parameters)
- Hands off to LoopClosureDetector
B. I/O Layer
- Image Loader – reads each image via OpenCV
- Settings Parser – YAML → in‐memory config struct
C. Core Library (MILD/)
- Frame Module – wraps OpenCV Mat + pre‐computed keypoints/descriptors
- SparseMatch – binary feature extraction & approximate nearest‐neighbor matching
- BayesianFilter – fuses match scores over time to produce loop‐closure probability
- LoopClosureDetector – ties Frame, SparseMatch, BayesianFilter into a pipeline
D. Output Layer
- File Writer – writes lcd_shared_flag.bin, lcd_shared_score_mild.bin, relocalization_time_per_frame.bin
E. Post‐Processing (External Script)
- Octave/MATLAB–based evaluation.m/run_scritp.m reads built binaries + ground‐truth .mat and computes accuracy

imagelist.txt → CLI → Settings Parser → Detector
↓                       ↘
Image Loader → Frame → SparseMatch → BayesianFilter → Output Writer
↘
loop_closure_detector → binary files → evaluation.m

##### Architectural Patterns & Design Principles
- Modular pipeline: clear separation between I/O, feature matching, probabilistic filtering, and output
- Facade (mild.hpp) exposes high‐level API, hiding submodule complexity
- Single Responsibility: each class (SparseMatch, BayesianFilter, Frame) has one concern
- Performance‐critical data structures (lightweight_vector.hpp) for real‐time operation

##### Detail Level
- Interaction between main.cpp (CLI) and the library
- Build artifacts (CMake → executable + library) at the top or side

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Layer
    subgraph "Build Layer"
        CMake["CMakeLists.txt"]:::build
        MildExe["mild (executable)"]:::build
        CMake --> MildExe
    end

    %% CLI Frontend
    subgraph "CLI Frontend"
        Main["main.cpp"]:::io
        Imagelist["/imagelist.txt/"]:::io
        SettingsFile["/settings.yaml/"]:::io
        Main -->|reads| Imagelist
        Main -->|reads| SettingsFile
        Main --> SettingsParser
        Main --> ImageLoader
    end

    %% I/O Layer
    subgraph "I/O Layer"
        ImageLoader["Image Loader"]:::io
        SettingsParser["Settings Parser"]:::io
        ImageLoader --> FrameModule
        SettingsParser --> FrameModule
    end

    %% Core Library
    subgraph "Core Library (MILD/)"
        Facade["mild.hpp"]:::algo
        GlobalDefs["global.h"]:::algo
        FrameModule["Frame Module"]:::algo
        SparseMatch["SparseMatch"]:::algo
        BayesianFilter["BayesianFilter"]:::algo
        LightweightVec["lightweight_vector.hpp"]:::algo
        Detector["LoopClosureDetector"]:::algo

        Facade --> FrameModule
        Facade --> SparseMatch
        Facade --> BayesianFilter
        FrameModule --> SparseMatch
        SparseMatch --> BayesianFilter
        BayesianFilter --> Detector
    end

    %% Output Layer
    subgraph "Output Layer"
        FileWriter["File Writer"]:::output
        Detector --> FileWriter
        FileWriter -->|"writes lcd_shared_flag.bin"| Output1["/lcd_shared_flag.bin/"]:::output
        FileWriter -->|"writes lcd_shared_score_mild.bin"| Output2["/lcd_shared_score_mild.bin/"]:::output
        FileWriter -->|"writes relocalization_time_per_frame.bin"| Output3["/relocalization_time_per_frame.bin/"]:::output
    end

    %% Post-Processing
    subgraph "Post-Processing"
        GroundTruth(("truthNewCollege.mat")):::external
        EvalScript["evaluation.m & run_scritp.m"]:::external
        EvalScript -->|reads| Output1
        EvalScript -->|reads| Output2
        EvalScript -->|reads| Output3
        EvalScript -->|reads| GroundTruth
    end

    %% Click Events
    click Main "https://github.com/lhanaf/mild/blob/master/main.cpp"
    click CMake "https://github.com/lhanaf/mild/blob/master/CMakeLists.txt"
    click SettingsFile "https://github.com/lhanaf/mild/blob/master/settings.yaml"
    click Imagelist "https://github.com/lhanaf/mild/blob/master/imagelist.txt"
    click GroundTruth "https://github.com/lhanaf/mild/blob/master/data/truthNewCollege.mat"
    click FrameModule "https://github.com/lhanaf/mild/blob/master/frame.cpp"
    click GlobalDefs "https://github.com/lhanaf/mild/blob/master/global.h"
    click SparseMatch "https://github.com/lhanaf/mild/blob/master/MILD/sparse_match.cpp"
    click BayesianFilter "https://github.com/lhanaf/mild/blob/master/MILD/BayesianFilter.hpp"
    click LightweightVec "https://github.com/lhanaf/mild/blob/master/MILD/lightweight_vector.hpp"
    click Detector "https://github.com/lhanaf/mild/blob/master/MILD/loop_closure_detector.cpp"
    click Facade "https://github.com/lhanaf/mild/blob/master/MILD/mild.hpp"
    click EvalScript "https://github.com/lhanaf/mild/blob/master/evaluation.m"
    click EvalScript "https://github.com/lhanaf/mild/blob/master/run_scritp.m"

    %% Styles
    classDef build fill:#f2e5ff,stroke:#a366cc;
    classDef io fill:#deebf7,stroke:#2f74c0;
    classDef algo fill:#e2efda,stroke:#4f8b3a;
    classDef output fill:#ffe0b2,stroke:#e07a00;
    classDef external fill:#eeeeee,stroke:#888888;
```
