# dongjae0107/elite architecture

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

- Interactive diagram: https://gitdiagram.com/dongjae0107/elite
- Repository: https://github.com/dongjae0107/elite

## Overview

##### Project Type & Purpose
- ELite is an open-source, Python-based LiDAR continual mapping framework that incorporates *ephemerality* (local & global) into a multi-stage pipeline. It is neither a web application nor a microservice suite, but a domain-specific processing toolchain for aligning successive LiDAR “sessions,” removing dynamic elements, and incrementally updating a persistent map.

##### File Structure & Architectural Insights
- Top-level scripts & config:
- run_elite.py – single entry point
- config/*.yaml – per-session parameters
- Core modules (all under the Python package root):
- alignment/ – session alignment & scan matching
- dynamic_removal/ – ephemerality-based map cleaner
- map_update/ – incremental map builder
- utils/ – logging, session abstraction, I/O
- External dependencies & build:
- requirements.txt & setup.py – pip installation
- scripts/download_parkinglot.sh – data bootstrap

##### Main Components & Responsibilities
a. Input Layer
- Session Loader (utils/session.py & session_map.py)
- Configuration Parser (YAML → Python dict)
- Raw LiDAR scans (.pcd) and pose files
b. Alignment Module
- GlobalRegistration (alignment/global_registration.py) – coarse transform
- MapZipper (alignment/map_zipper.py) – merges sessions in time
- ScanMatcher sub-components (base_scan_matcher, open3d_scan_matcher, pygicp_scan_matcher) – fine ICP adjustments
c. Ephemerality Calculators
- Local & Global ephemerality scoring baked into alignment & dynamic_removal
d. Dynamic Removal Module
- MapRemover (dynamic_removal/map_remover.py) – filters out transient points
e. Update Module
- MapUpdater (map_update/map_updater.py) – fuses cleaned data into the persistent map
f. Output & Persistence
- Session outputs directory (prev_outputs_dir)
- Logs & intermediate files
g. External Libraries
- Open3D (point cloud operations)
- PyGICP or fast_gicp (CUDA-accelerated ICP)

##### Architectural Patterns & Principles
- Pipeline/Staged Processing: clear separation of alignment, filtering, and fusion steps
- Strategy Pattern: interchangeable ScanMatcher implementations (Open3D vs. PyGICP)
- Configuration-driven: YAML files determine branch logic (first vs. subsequent session)
- Modular & extensible: each submodule communicates via simple pointcloud + metadata objects

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Configuration Layer
    subgraph "Input & Configuration"
        direction TB
        Entry["Entry Point: run_elite.py"]:::module
        click Entry "https://github.com/dongjae0107/elite/blob/main/run_elite.py"
        SessionLoader["Session Loader"]:::module
        click SessionLoader "https://github.com/dongjae0107/elite/blob/main/utils/session.py"
        SessionMap["Session Map"]:::module
        click SessionMap "https://github.com/dongjae0107/elite/blob/main/utils/session_map.py"
        Config1["parkinglot.yaml"]:::config
        click Config1 "https://github.com/dongjae0107/elite/blob/main/config/parkinglot.yaml"
        Config2["parkinglot_first.yaml"]:::config
        click Config2 "https://github.com/dongjae0107/elite/blob/main/config/parkinglot_first.yaml"
        Config3["sample.yaml"]:::config
        click Config3 "https://github.com/dongjae0107/elite/blob/main/config/sample.yaml"
        DataBootstrap["download_parkinglot.sh"]:::config
        click DataBootstrap "https://github.com/dongjae0107/elite/blob/main/scripts/download_parkinglot.sh"
        Requirements["requirements.txt"]:::config
        click Requirements "https://github.com/dongjae0107/elite/blob/main/requirements.txt"
        Setup["setup.py"]:::config
        click Setup "https://github.com/dongjae0107/elite/blob/main/setup.py"
        Logger["Logger"]:::module
        click Logger "https://github.com/dongjae0107/elite/blob/main/utils/logger.py"
    end

    Entry -->|"loads"| Config1
    Entry -->|"loads"| Config2
    Entry -->|"loads"| Config3
    Entry -->|"initializes"| SessionLoader
    Entry -->|"initializes"| SessionMap
    Entry -->|"sets up logging"| Logger

    RawData["Raw LiDAR Scans\n(.pcd + pose.txt)"]:::datastore

    SessionLoader -->|".pcd + pose.txt"| RawData
    SessionMap -->|"session metadata"| RawData

    %% Processing Layer
    subgraph "Processing Pipeline"
        direction TB
        subgraph "Alignment Module"
            direction TB
            GlobalReg["GlobalRegistration"]:::module
            click GlobalReg "https://github.com/dongjae0107/elite/blob/main/alignment/global_registration.py"
            MapZipper["MapZipper"]:::module
            click MapZipper "https://github.com/dongjae0107/elite/blob/main/alignment/map_zipper.py"
            subgraph "ScanMatcher (Strategy Pattern)"
                direction TB
                BaseSM["BaseScanMatcher"]:::module
                click BaseSM "https://github.com/dongjae0107/elite/blob/main/alignment/matcher/base_scan_matcher.py"
                Open3DSM["Open3DScanMatcher"]:::module
                click Open3DSM "https://github.com/dongjae0107/elite/blob/main/alignment/matcher/open3d_scan_matcher.py"
                PyGICPSM["PyGICPScanMatcher"]:::module
                click PyGICPSM "https://github.com/dongjae0107/elite/blob/main/alignment/matcher/pygicp_scan_matcher.py"
            end
            GlobalReg -->|".pcd"| MapZipper
            MapZipper -->|"coarse aligned cloud"| BaseSM
            BaseSM -->|"fine aligned cloud"| GlobalReg
        end

        subgraph "Dynamic Removal Module"
            direction TB
            MapRemover["MapRemover"]:::module
            click MapRemover "https://github.com/dongjae0107/elite/blob/main/dynamic_removal/map_remover.py"
        end

        subgraph "Map Update Module"
            direction TB
            MapUpdater["MapUpdater"]:::module
            click MapUpdater "https://github.com/dongjae0107/elite/blob/main/map_update/map_updater.py"
        end
    end

    RawData -->|"raw scans"| GlobalReg
    GlobalReg -->|"coarse + fine aligned cloud"| MapRemover
    MapRemover -->|"cleaned cloud + ephemerality scores"| MapUpdater
    MapUpdater -->|"updated map"| PersistentMap

    %% Output & Persistence Layer
    subgraph "Output & Persistence"
        direction TB
        PersistentMap["Persistent Map Store"]:::datastore
        SessionOutputs["Session Outputs Dir"]:::datastore
        Logs["Logs & Intermediate Files"]:::datastore
    end

    MapUpdater -->|writes| PersistentMap
    MapUpdater -->|writes| SessionOutputs
    MapUpdater -->|writes| Logs
    PersistentMap -->|prev_outputs_dir| GlobalReg

    %% External Libraries
    Open3D["Open3D"]:::external
    PyGICP["PyGICP/fast_gicp"]:::external

    BaseSM -.->|uses| Open3D
    PyGICPSM -.->|uses| PyGICP

    %% Styles
    classDef module fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef datastore fill:#DFFFE0,stroke:#228B22,stroke-width:1px,stroke-dasharray: 2 2;
    classDef config fill:#FFF4D6,stroke:#FFA500,stroke-width:1px;
    classDef external fill:#EEEEEE,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2;
    class Entry,SessionLoader,SessionMap,Logger,GlobalReg,MapZipper,BaseSM,Open3DSM,PyGICPSM,MapRemover,MapUpdater module;
    class RawData,PersistentMap,SessionOutputs,Logs datastore;
    class Config1,Config2,Config3,DataBootstrap,Requirements,Setup config;
    class Open3D,PyGICP external;
```
