# simondemoreau/doc-depth architecture

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

- Interactive diagram: https://gitdiagram.com/simondemoreau/doc-depth
- Repository: https://github.com/simondemoreau/doc-depth

## Overview

##### Project type and purpose
- DOC-Depth is a multi-stage data-processing pipeline (not a web app or microservice). It ingests raw sensor data (ROS “.bag” files), performs camera–LiDAR calibration, pre-processes the data with SLAM & classification, and finally applies a custom rendering pipeline (with GLSL shaders) to produce dense depth ground truth on KITTI scenes.

##### File structure
- Top-level folders:
- Calibration: Python tools to extract frames, detect chessboards, solve LiDAR–camera extrinsics.
- Preprocessing: Python pipeline for pose extraction (SLAM), coordinate transforms, reconstruction classification via DOC.
- Rendering: Python application plus GLSL shader files to composite LiDAR classifications into dense depth maps.
- Each stage has its own “src” subfolder with modular code (e.g., camera.py, lidar.py, transform.py).
- There are no heavy build scripts or containers—this is a script-driven pipeline reliant on ROS and Python packages.

##### README for architecture hints
- Three sequential stages (Calibration → Preprocessing → Rendering).
- External dependencies: ROS (for recording), a SLAM system (e.g., ORB-SLAM2), and the DOC algorithm for classification.
- Input/Output per stage:
- Calibration inputs: raw .bag files → outputs: aligned point clouds + camera intrinsics/extrinsics.
- Preprocessing inputs: calibrated data → outputs: dense, classified 3D reconstruction + trajectories.
- Rendering inputs: classified point clouds + poses → outputs: per-pixel depth images.

a. Main components
- Data Ingestion (ROS Bag Recorder)
- Calibration Module
- Preprocessing Module
- Rendering Module
- External Services: SLAM engine, DOC classifier
- Data Store / File System (for intermediate artifacts)
b. Relationships & data flow
1. Raw sensors → ROS Bag
2. ROS Bag → Calibration
3. Calibration → calibrated point clouds + camera parameters → Preprocessing
4. Preprocessing ↔ SLAM engine & DOC → reconstructed, classified 3D model + trajectories → Rendering
5. Rendering + shaders → dense depth maps
c. Architectural patterns
- Linear, modular pipeline.
- Each folder is a self-contained stage with clear inputs/outputs.
- Pluggable external engines (SLAM, classification).
d. Key technologies
- Python scripts (numpy, OpenCV, PCL bindings)
- ROS (.bag API)
- SLAM library (external)
- DOC classification code
- OpenGL/GLSL shaders (fragment and vertex programs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion
    subgraph "Data Ingestion"
        direction TB
        RAW["Raw Sensors"]:::external
        ING1["extract_frame_from_bag.py"]:::ingest
        ING2["extract_images_from_bag.py"]:::ingest
    end

    RAW -->|".bag files"| ING1
    RAW -->|".bag files"| ING2

    %% Calibration Module
    subgraph "Calibration Module"
        direction TB
        CAL_APP["app_calib.py"]:::calib
        CAL_CAM["calib_lidar_camera.py"]:::calib
        CAL_CAMERA["camera.py"]:::calib
        CAL_LIDAR["lidar.py"]:::calib
        CAL_CHESS["extract_chessboard.py"]:::calib
        CAL_COLOR["colorize_pc.py"]:::calib
    end

    ING1 -->|"raw .bag"| CAL_APP
    CAL_APP -->|"calls modules"| CAL_CAM
    CAL_APP -->|"calls modules"| CAL_CAMERA
    CAL_APP -->|"calls modules"| CAL_LIDAR
    CAL_APP -->|"calls modules"| CAL_CHESS
    CAL_APP -->|"calls modules"| CAL_COLOR

    %% Intermediate Data Store
    FILE1["Intermediate Store\n(calibrated point clouds,\ncamera params)"]:::datastore

    CAL_COLOR -->|".pcd + params"| FILE1

    %% Preprocessing Module
    subgraph "Preprocessing Module"
        direction TB
        PRE_MAIN["camera_trajectory.py"]:::pre
        PRE_POSE["pose.py"]:::pre
        PRE_TRAJ["trajectory.py"]:::pre
        PRE_TRANS["transform.py"]:::pre
        PRE_UTILS["utils.py"]:::pre
    end

    FILE1 -->|"calibrated data"| PRE_MAIN
    PRE_MAIN -->|"uses"| PRE_POSE
    PRE_MAIN -->|"uses"| PRE_TRAJ
    PRE_MAIN -->|"uses"| PRE_TRANS
    PRE_MAIN -->|"uses"| PRE_UTILS

    %% External Services for Preprocessing
    SLAM["SLAM Engine"]:::external
    DOC["DOC Classifier"]:::external

    PRE_MAIN -->|"/invoke SLAM"| SLAM
    PRE_MAIN -->|"/invoke DOC"| DOC
    SLAM -->|"poses + map"| PRE_MAIN
    DOC -->|"labels"| PRE_MAIN

    %% Intermediate Data Store 2
    FILE2["Intermediate Store\n(reconstructed, classified\n3D model + trajectories)"]:::datastore

    PRE_MAIN -->|"reconstruction output"| FILE2

    %% Rendering Module
    subgraph "Rendering Module"
        direction TB
        RENDER_MAIN["render.py"]:::render
        RENDER_APP["renderApp.py"]:::render
        FRAME_MGR["frameManager.py"]:::render
        RENDER_POSE["pose.py"]:::render
        RENDER_TRAJ["trajectory.py"]:::render
        RENDER_TRANS["transform.py"]:::render
        RENDER_UTILS["utils.py"]:::render
        subgraph "Shaders"
            direction TB
            VERT["vertex.c"]:::shader
            VERT_INT["vertex_intensity.c"]:::shader
            FRAG["fragment.c"]:::shader
            FRAG_CIRC["fragment_circle.c"]:::shader
            FRAG_ELL["fragment_ellipsis.c"]:::shader
            FRAG_ELL_T["fragment_ellipsis_turbo.c"]:::shader
            FRAG_VIR["fragment_viridis_intensity.c"]:::shader
        end
    end

    FILE2 -->|"classified point clouds\n+ poses"| RENDER_MAIN
    RENDER_MAIN -->|"initializes"| RENDER_APP
    RENDER_APP -->|"manages frames"| FRAME_MGR
    RENDER_APP -->|"uses"| RENDER_POSE
    RENDER_APP -->|"uses"| RENDER_TRAJ
    RENDER_APP -->|"uses"| RENDER_TRANS
    RENDER_APP -->|"uses"| RENDER_UTILS
    RENDER_APP -->|"loads shaders"| VERT
    RENDER_APP -->|"loads shaders"| VERT_INT
    RENDER_APP -->|"loads shaders"| FRAG
    RENDER_APP -->|"loads shaders"| FRAG_CIRC
    RENDER_APP -->|"loads shaders"| FRAG_ELL
    RENDER_APP -->|"loads shaders"| FRAG_ELL_T
    RENDER_APP -->|"loads shaders"| FRAG_VIR

    %% Final Output
    OUTPUT["Depth Images\n(per-pixel ground truth)"]:::datastore
    RENDER_APP -->|"dense depth maps"| OUTPUT

    %% Click Events
    click ING1 "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/extract_frame_from_bag.py"
    click ING2 "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/extract_images_from_bag.py"
    click CAL_APP "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/app_calib.py"
    click CAL_CAM "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/src/calib_lidar_camera.py"
    click CAL_CAMERA "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/src/camera.py"
    click CAL_LIDAR "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/src/lidar.py"
    click CAL_CHESS "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/src/extract_chessboard.py"
    click CAL_COLOR "https://github.com/simondemoreau/doc-depth/blob/main/Calibration/src/colorize_pc.py"
    click PRE_MAIN "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/camera_trajectory.py"
    click PRE_POSE "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/src/pose.py"
    click PRE_TRAJ "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/src/trajectory.py"
    click PRE_TRANS "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/src/transform.py"
    click PRE_UTILS "https://github.com/simondemoreau/doc-depth/blob/main/Preprocessing/src/utils.py"
    click RENDER_MAIN "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/render.py"
    click RENDER_APP "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/renderApp.py"
    click FRAME_MGR "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/frameManager.py"
    click RENDER_POSE "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/pose.py"
    click RENDER_TRAJ "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/trajectory.py"
    click RENDER_TRANS "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/transform.py"
    click RENDER_UTILS "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/src/utils.py"
    click VERT "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/vertex.c"
    click VERT_INT "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/vertex_intensity.c"
    click FRAG "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/fragment.c"
    click FRAG_CIRC "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/fragment_circle.c"
    click FRAG_ELL "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/fragment_ellipsis.c"
    click FRAG_ELL_T "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/fragment_ellipsis_turbo.c"
    click FRAG_VIR "https://github.com/simondemoreau/doc-depth/blob/main/Rendering/shaders/fragment_viridis_intensity.c"

    %% Styles
    classDef ingest fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef calib fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef pre fill:#90EE90,stroke:#333,stroke-width:1px
    classDef render fill:#FFA500,stroke:#333,stroke-width:1px
    classDef shader fill:#FFD580,stroke:#333,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef datastore fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
