lime_path_explainer

Explaining local path plans using LIME — a ROS2 (Humble) reconstruction of:

Amar Halilovic and Felix Lindner. Explaining Local Path Plans Using LIME. Advances in Service and Industrial Robotics (RAAD 2022), Springer.

The robot follows a global plan while a local planner avoids obstacles. This package explains why the local plan deviates from the global plan by applying LIME to the local costmap: it segments the costmap into obstacles, perturbs them (turns them on/off), asks a deterministic local planner what local plan results, measures how far that plan deviates from the global plan, and fits a weighted Ridge surrogate. Each obstacle is then coloured green (its presence increases the deviation) or red (its presence decreases it).

C1: the right wall (green) pushes the robot away from the doorway, the left wall (red) squeezes it back — reproducing the paper's Figure C1 explanation.

---

What runs now vs. what is scaffolded

	Needs	Status
Headless reproduction (the core, the 3 paper scenarios, the evaluation figures)	a Python venv with numpy/scipy/scikit-learn/scikit-image/matplotlib/opencv	Runs out of the box
Live ROS2 node (lime_path_node)	ROS2 Humble + the ML deps importable together	Optional
Full Gazebo + Nav2 + real TEB	Nav2, Gazebo, teb_local_planner (apt)	Scaffolded, see sim/

The headless path is the supported, reproducible one. The original TEB planner is replaced by a deterministic elastic-band planner (core/planner/elastic_band.py) so the whole pipeline runs anywhere; the PlannerBackend seam lets you swap in the real Nav2/TEB controller for exact numbers (see docs/ALGORITHM.md).

Quickstart (headless)

# 1. dependencies (into the Python env that will run the pipeline)
python -m venv ~/venvamar           # or reuse an existing venv
source ~/venvamar/bin/activate
pip install -r requirements.txt

# 2. (re)bake the three RAAD scenarios from the paper's costmap figures
pip install -e .                     # makes the console scripts available
lpe_build_scenarios                  # data/scenarios/C{1,2,3}_paper/

# 3. explain a scenario  ->  outputs/C1_paper/{explanation.png,coefficients.csv,...}
lpe_explain_scenario --scenario C1_paper --mode one_off --out outputs/

# 4. reproduce the evaluation figures (quality / robustness / runtime)
lpe_reproduce_figures --scenario C1_paper --out outputs/figures/

Scenarios: C1_paper, C2_paper, C3_paper (baked from the paper figures) and the synthetic doorway, blocked_doorway, clutter builders.

Architecture

lime_path_explainer/
  core/            framework-agnostic LIME engine (no ROS)
    costmap.py       value convention + world<->pixel transforms
    segmentation.py  SLIC obstacle segments (+ split/merge to N)
    perturbation.py  turn obstacle segments on/off
    kernel.py        cosine distance + exponential kernel
    ridge_explainer.py  weighted Ridge surrogate + feature selection
    trajectory.py    deviation metric (the LIME target)
    coloring.py      coefficients -> green/red image
    pipeline.py      LimePathExplainer.explain(instance)
    planner/         PlannerBackend + deterministic ElasticBandPlanner
  scenarios/       baked-scenario loader + synthetic builders + paper bake
  evaluation/      quality / robustness / runtime + figure rendering
  apps/            console scripts (headless)
  ros/             OPTIONAL rclpy node (degrades gracefully)
data/scenarios/    the three RAAD scenarios (costmap + plan + meta)
sim/               OPTIONAL full Gazebo+Nav2+TEB scaffold
docs/              PAPER_MAP, ALGORITHM, SHARED_CORE

Mapping to the paper

See docs/PAPER_MAP.md for a section/figure → module/test table. In short:

• LIME on the costmap → core/{segmentation,perturbation,kernel,ridge_explainer}.py
• TEB black box → core/planner/elastic_band.py (deterministic stand-in)
• Deviation target → core/trajectory.py
• Green/red explanation → core/coloring.py
• Quality / robustness / runtime figures → evaluation/

Tests

pip install pytest
pytest -q

Optional: the live node

source /opt/ros/humble/setup.bash
colcon build --packages-select lime_path_explainer
source install/setup.bash
ros2 launch lime_path_explainer lime_path_explainer.launch.py

The node needs rclpy and the ML deps importable in the same interpreter. On a machine where rclpy is in the system Python and the ML libs are in a venv, create the venv with --system-site-packages (or install the ML deps where rclpy is visible). If they are not both present, lime_path_node prints a clear message and exits cleanly — colcon build is never broken.

Limitations

• The deterministic elastic-band planner reproduces TEB's behaviour qualitatively (the sign of each obstacle's effect on deviation, hence the colour), not its exact numbers. The route to exact numbers is the documented Nav2/TEB backend (sim/).
• The RAAD lab bag files were not available, so the three scenarios take their costmaps from the paper's own figures; the robot pose and global plan are a reconstruction (noted in each scenario's meta.json).

License

MIT — see LICENSE. Please cite the paper (CITATION.cff).