# seareale/vision-based-localization architecture

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

- Interactive diagram: https://gitdiagram.com/seareale/vision-based-localization
- Repository: https://github.com/seareale/vision-based-localization

## Overview

##### Project type and purpose
- This is a native C++ desktop application for vision-based camera pose localization and real-time 3D visualization using OpenCV and OpenGL.
- The `_practice` folder holds proof-of-concept tools (calibration, detection, marker generation, simple OpenGL demo).
- The `KnuMarkerViewer` folder contains the main viewer: it captures a live camera feed, detects a known marker, computes its 3D pose, loads a 3D model via Assimp, and renders everything with OpenGL (gl3w + GLFW + glm), with an ImGui-driven UI.

##### File structure
- Top-level:
- `KnuMarkerViewer/` – core application (CMakeLists.txt, `src/`, `shader/`).
- `_practice/` – supporting demos (calibration, detection, marker creation).
- `libs/` – vendored third-party: gl3w, imgui, stb modules.
- In `KnuMarkerViewer/src/`:
- `main.cpp` – application entry, UI setup, main loop.
- `knuCamera.{cpp,h}` – camera capture & calibration file loader.
- `yeAssimp.{cpp,h}` – 3D model loader wrapper around Assimp.
- `knuGlModel.{cpp,h}` – OpenGL mesh and shader binding.
- In `KnuMarkerViewer/shader/`: GLSL vertex & fragment shaders for grid and sample object.
- Build/config: `CMakeLists.txt` orchestrates compiler flags and links OpenCV, OpenGL, GLFW, glm, Assimp.

##### Key insights from README
- Workflow:
a. Generate Charuco board image (`charucoboard.cpp`)
b. Calibrate camera to produce `output.txt` (`calibrate.cpp`)
c. Build viewer (`cmake` + `make`)
d. Run `./viewer [markerID] [threadMode] [cameraID]`
- Dependencies: OpenCV 4.x, OpenGL 4.x, GLFW, glm, Assimp.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input/Calibration"
        CAM["Camera Capture Module"]:::internal
        CALMOD["Calibration Module"]:::internal
        OUTPUT["Calibration Output (output.txt)"]:::data
    end

    subgraph "Processing"
        MAIN["Application Entry & Main Loop"]:::internal
        THREAD["Thread Manager"]:::internal
        DET["Marker Detection & Pose Estimation"]:::internal
        ASSIMP["Model Loader (Assimp)"]:::internal
    end

    subgraph "Assets"
        MODELS["3D Models"]:::data
        SHADERS["Shader Assets"]:::data
    end

    subgraph "Rendering"
        RENDER["Rendering Engine"]:::internal
        UI["UI Layer (ImGui)"]:::internal
    end

    subgraph "External Dependencies"
        OPENCV["OpenCV"]:::external
        OPENGL["OpenGL Loader (gl3w) & GLFW & glm"]:::external
        ASSIMPLIB["Assimp"]:::external
        STB["stb Utilities"]:::external
    end

    CAM -->|"frames →"| MAIN
    MAIN -->|"invoke detection"| DET
    MAIN -->|"manage threads"| THREAD
    THREAD <-->|"process in parallel"| DET
    CALMOD -->|"calibration data →"| DET
    OUTPUT -->|"load config"| DET
    DET -->|"pose →"| RENDER
    ASSIMP -->|"mesh →"| RENDER
    MODELS -->|"model files"| ASSIMP
    SHADERS -->|"shaders →"| RENDER
    RENDER -->|"frame buffer →"| UI
    UI -->|"user inputs →"| MAIN

    CAM -.-> OPENCV
    DET -.-> OPENCV
    CALMOD -.-> OPENCV
    ASSIMP -.-> ASSIMPLIB
    RENDER -.-> OPENGL
    UI -.-> STB
    UI -.-> OPENGL

    click CAM "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/knuCamera.cpp"
    click CAM "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/knuCamera.h"
    click CALMOD "https://github.com/seareale/vision-based-localization/blob/master/_practice/calibration/charucoboard.cpp"
    click CALMOD "https://github.com/seareale/vision-based-localization/blob/master/_practice/calibration/calibrate.cpp"
    click DET "https://github.com/seareale/vision-based-localization/blob/master/_practice/detection/markerdetection.cpp"
    click DET "https://github.com/seareale/vision-based-localization/blob/master/_practice/detection/markerdetection_2.cpp"
    click DET "https://github.com/seareale/vision-based-localization/blob/master/_practice/detection/dictionary.hpp"
    click ASSIMP "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/yeAssimp.cpp"
    click ASSIMP "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/yeAssimp.h"
    click RENDER "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/knuGlModel.cpp"
    click RENDER "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/knuGlModel.h"
    click SHADERS "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/shader/grid.vs"
    click SHADERS "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/shader/grid.fs"
    click SHADERS "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/shader/sample.vertex"
    click SHADERS "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/shader/sample.fragment"
    click MAIN "https://github.com/seareale/vision-based-localization/blob/master/KnuMarkerViewer/src/main.cpp"
    click UI "https://github.com/seareale/vision-based-localization/blob/master/libs/imgui_190703/imgui.cpp"
    click UI "https://github.com/seareale/vision-based-localization/blob/master/libs/imgui_190703/imgui.h"
    click UI "https://github.com/seareale/vision-based-localization/blob/master/libs/imgui_190703/examples/imgui_impl_glfw.cpp"
    click UI "https://github.com/seareale/vision-based-localization/blob/master/libs/imgui_190703/examples/imgui_impl_glfw.h"
    click OPENGL "https://github.com/seareale/vision-based-localization/blob/master/libs/gl3w_190703/src/gl3w.c"
    click OPENGL "https://github.com/seareale/vision-based-localization/blob/master/libs/gl3w_190703/include/GL/gl3w.h"
    click STB "https://github.com/seareale/vision-based-localization/blob/master/libs/stb_190703/stb.h"
    click OUTPUT "https://github.com/seareale/vision-based-localization/blob/master/_practice/calibration/output.txt"

    classDef internal fill:#AED6F1,stroke:#333,stroke-width:1px;
    classDef data fill:#A9DFBF,stroke:#333,stroke-width:1px;
    classDef external fill:#F5B041,stroke:#333,stroke-width:1px;
```
