# castacks/mapex architecture

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

- Interactive diagram: https://gitdiagram.com/castacks/mapex
- Repository: https://github.com/castacks/mapex

## Overview

##### Project Type and Purpose
- MapEx is a robotics research toolkit for indoor structure exploration.
- It orchestrates:
- A planning engine (frontier‐ and information‐gain planners)
- A probabilistic raycast library (`range_libc`)
- A global map prediction model (`lama` submodule)
- Post‐processing scripts for metrics and visualization

##### Main Architectural Components
A. Data Inputs
- `kth_test_maps/`: Raw occupancy maps (`occ_map.npy`, `valid_space.npy`) for simulation environments
- `configs/base.yaml` (and other YAMLs under `configs/`): Experiment parameters (methods to test, file paths, initial poses)

B. Planning & Exploration Engine (Python scripts under `scripts/`)
- `explore.py`: Entry point. Reads configs, selects exploration mode (`visvarprob`, `nearest`, etc.), initializes planner.
- Planner modules:
- `rrt.py`, `rrt_star.py` (sampling‐based planners)
- `upen_baseline.py`, `hectoraug.py`, `topological.py` (baseline & ablation algorithms)
- Utility scripts (`sim_utils.py`, `simple_mask_utils.py`) for observation updates and masks

C. Raycasting & Observation Model (`range_libc` submodule)
- C++/CUDA core (`includes/`, `kernels.cu`), wrapped to Python via Cython (`pywrapper/RangeLibc.pyx`)
- Exposes API to compute visibility masks, occupancy updates, probabilistic information gain

D. Global Map Prediction (`lama` submodule)
- Pretrained deep models invoked via Python
- Input: partial observed maps (`global_obs`)
- Output: predicted occupancy (`global_pred`)

E. Batch & Cluster Orchestration (`clusters/`)
- Job scripts (`run_explore.job`, `batch_explore.batch`) for HPC submission

F. Results Storage (`experiments/`)
- Timestamped run directories:
- `global_obs/` (PNG visualizations of the partial map at each timestep)
- `run_viz/` (animated frames)
- `odom.npy` (robot trajectories)
- `global_pred/` (predicted maps)

G. Evaluation & Metrics (Python scripts under `scripts/`)
- `simple_lama_pred.py`: Runs the LAMA prediction over `global_obs` → writes `global_pred`
- `calc_metrics_subdirectory.py`: Computes coverage & Predicted IoU, generates plots

##### Component Relationships & Data Flow
- Start → Configuration loader (`configs/base.yaml`) → Planner initialization (`explore.py`)
- Planner queries `range_libc` for visibility & information‐gain values
- Planner reads raw maps (`kth_test_maps`) to simulate sensor observations
- As the robot “explores”, write out partial map frames to `experiments/.../global_obs`
- Post‐exploration:
- `simple_lama_pred.py` reads `global_obs`, calls `lama` to produce `global_pred`
- `calc_metrics_subdirectory.py` reads both `global_obs` & `global_pred` to compute metrics

##### Architectural Patterns & Design Principles
- Modular pipeline: clear separation of planning, raycasting, prediction, and evaluation
- Submodules for isolation:
- `range_libc` compiled C++ core with Python wrapper (performance‐critical raycasting)
- `lama` as an external deep‐learning component (encapsulates global map inference)
- Configuration‐driven: all experiment settings live in YAML, enabling reproducibility
- Batch HPC integration: cluster scripts allow scaling to many environments in parallel

##### Technology Stack & Key Dependencies
- Python 3.x (main orchestration)
- C++ / CUDA (in `range_libc`) wrapped via Cython
- Mamba/Conda environments for dependency management
- PyTorch (for LAMA prediction)
- NumPy, Matplotlib, pyastar2d, numba (utilities)
- CMake (for building `range_libc`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    ConfigLoader["Config Loader"]:::orchestration
    ClusterManager["Cluster Job Manager"]:::orchestration

    %% Data Stores
    DataInputs["Data Inputs<br/>(kth_test_maps)"]:::datastore
    Experiments["Experiments Storage"]:::datastore

    %% Core Compute Modules
    subgraph "Planner Engine" 
        direction TB
        Explore["explore.py"]:::compute
        subgraph "Sampling-Based Planners"
            direction TB
            RRT["rrt.py"]:::compute
            RRTStar["rrt_star.py"]:::compute
        end
        subgraph "Baseline & Ablation"
            direction TB
            UPEN["upen_baseline.py"]:::compute
            Topo["topological.py"]:::compute
        end
        subgraph "Planner Utilities"
            direction TB
            SimUtils["sim_utils.py"]:::compute
            MaskUtils["simple_mask_utils.py"]:::compute
        end
    end

    subgraph "range_libc (C++/CUDA + Python Wrapper)" 
        direction TB
        subgraph Includes
            CudaCode["includes/ (kernel .cu, headers)"]:::compute
            BuildScripts["CMakeLists.txt / main.cpp"]:::compute
        end
        subgraph PyWrapper
            Pyx["RangeLibc.pyx"]:::compute
            Setup["setup.py"]:::compute
            Compile["compile.sh / compile_with_cuda.sh"]:::compute
        end
    end

    subgraph "LAMA Prediction Model" 
        direction TB
        LamaDir["lama/"]:::compute
        SimpleLama["simple_lama_pred.py"]:::compute
        LamaUtils["lama_pred_utils.py"]:::compute
        Pretrained["pretrained_models/"]:::compute
    end

    %% Evaluation & Visualization
    Metrics["Metrics & Visualization"]:::evaluation
    CalcMetrics["calc_metrics_subdirectory.py"]:::evaluation
    VizUtils["visualize.py"]:::evaluation

    %% Connections
    ConfigLoader -->|"loads .yaml params"| Explore
    ClusterManager -->|"submits jobs"| Explore
    Explore -->|"reads raw maps (.npy)"| DataInputs
    Explore -->|"visibility queries (Cython API)"| Pyx
    Explore -->|"writes partial maps (.npy)"| Experiments
    Experiments -->|"global_obs frames"| SimpleLama
    SimpleLama -->|"invokes deep model"| LamaDir
    SimpleLama -->|"writes global_pred"| Experiments
    Experiments -->|"inputs maps"| CalcMetrics
    CalcMetrics -->|"generates plots"| Metrics
    CudaCode -->|"built by"| BuildScripts
    BuildScripts -->|"produces library"| Pyx
    VizUtils -->|"optional plots"| Metrics

    %% Click Events
    click ConfigLoader "https://github.com/castacks/mapex/blob/main/configs/base.yaml"
    click DataInputs "https://github.com/castacks/mapex/tree/main/kth_test_maps/"
    click Explore "https://github.com/castacks/mapex/blob/main/scripts/explore.py"
    click RRT "https://github.com/castacks/mapex/blob/main/scripts/rrt.py"
    click RRTStar "https://github.com/castacks/mapex/blob/main/scripts/rrt_star.py"
    click UPEN "https://github.com/castacks/mapex/blob/main/scripts/upen_baseline.py"
    click Topo "https://github.com/castacks/mapex/blob/main/scripts/topological.py"
    click SimUtils "https://github.com/castacks/mapex/blob/main/scripts/sim_utils.py"
    click MaskUtils "https://github.com/castacks/mapex/blob/main/scripts/simple_mask_utils.py"
    click CudaCode "https://github.com/castacks/mapex/tree/main/range_libc/includes/"
    click BuildScripts "https://github.com/castacks/mapex/blob/main/range_libc/CMakeLists.txt"
    click Pyx "https://github.com/castacks/mapex/blob/main/range_libc/pywrapper/RangeLibc.pyx"
    click Setup "https://github.com/castacks/mapex/blob/main/range_libc/pywrapper/setup.py"
    click Compile "https://github.com/castacks/mapex/blob/main/range_libc/pywrapper/compile.sh"
    click LamaDir "https://github.com/castacks/mapex/tree/main/lama/"
    click SimpleLama "https://github.com/castacks/mapex/blob/main/scripts/simple_lama_pred.py"
    click LamaUtils "https://github.com/castacks/mapex/blob/main/scripts/lama_pred_utils.py"
    click Pretrained "https://github.com/castacks/mapex/tree/main/pretrained_models/"
    click ClusterManager "https://github.com/castacks/mapex/blob/main/clusters/run_explore.job"
    click Experiments "https://github.com/castacks/mapex/tree/main/experiments/"
    click CalcMetrics "https://github.com/castacks/mapex/blob/main/scripts/calc_metrics_subdirectory.py"
    click VizUtils "https://github.com/castacks/mapex/blob/main/range_libc/visualize.py"

    %% Styles
    classDef compute fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef datastore fill:#ABEBC6,stroke:#1D8348,color:#0B5345;
    classDef orchestration fill:#F5CBA7,stroke:#B9770E,color:#78281F;
    classDef evaluation fill:#D7BDE2,stroke:#6C3483,color:#4A235A;
```
