How castacks/mapex works
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)