# mazenmtulab/the-barn-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/mazenmtulab/the-barn-challenge
- Repository: https://github.com/mazenmtulab/the-barn-challenge

## Overview

1. This repo is a ROS-based navigation benchmark and submission harness for the ICRA BARN Navigation Challenge. The core purpose is not a standalone robot app, but a controlled simulation/evaluation environment for running a navigation stack against many predefined Gazebo worlds.

2. The top-level orchestrator is `run.py`. It appears to be the main entry point used in both local and containerized runs. Its job is to select a world by index, bring up the simulation, and initialize one navigation stack implementation. The README explicitly says the user should only customize the navigation-stack initialization section in this file.

3. `gazebo_simulation.py` likely encapsulates simulation startup and world loading. Together with `jackal_helper/launch/gazebo_launch.launch`, it forms the simulation boundary: Gazebo world + Jackal robot + ROS interfaces. This is where the environment is instantiated before any planner runs.

4. The repository supports at least two planner families. The `jackal_helper/launch/move_base_DWA.launch` and `move_base_eband.launch` files configure ROS `move_base` with different local planners. In parallel, `navigation_pkg/scripts/Nav-VFH.py` and `navigation_pkg/scripts/navigation_utils.py` implement a separate VFH-based navigation stack. This gives the repo multiple interchangeable “navigation backend” paths under the same simulation harness.

5. The `jackal_helper` ROS package is the simulation support package. Its `configs/params/*.yaml` files provide `move_base`, costmap, local planner, and odometry-navigation parameters. This package is the configuration and robot-integration layer between the simulator and planner nodes.

6. `jackal_helper/src/collision_publisher.cpp` is the only compiled C++ source shown, so it is likely a small ROS node/plugin responsible for collision detection or collision-state publication during benchmark runs. Architecturally, it sits on the simulator side and feeds termination/evaluation signals back to the harness.

7. `jackal_helper/worlds/BARN` and `jackal_helper/worlds/DynaBARN` are the benchmark assets. The many `.world` files are Gazebo environments, while the BARN `path_files/*.npy` set likely stores reference paths or scenario metadata used for evaluation. DynaBARN is explicitly noted as an extension with dynamic environments.

8. The navigation stack boundary is intentionally loose: `run.py` launches whichever planner is being tested, but the repo does not enforce a single API beyond the ROS ecosystem. `move_base`-based stacks consume ROS topics/services and planner parameters; the VFH stack is a Python implementation with its own utilities. The common contract is the simulated robot in Gazebo and the benchmark episode outcome.

9. Evaluation is handled outside the live simulation loop by `test.sh` and `report_test.py`. `test.sh` appears to batch multiple runs across sampled worlds, while `report_test.py` aggregates outcomes into average time, metric, success, collision, and timeout rates. This means the repo separates episode execution from score computation.

10. Containerization is a first-class deployment path. `Singularityfile.def`, `entrypoint.sh`, and `singularity_run.sh` define the reproducible runtime used for challenge submission. The container boundary matters because it packages ROS, Python dependencies, and the navigation code so the same `run.py` entry point can run consistently on the evaluator’s machine.

11. External dependencies that materially shape the architecture are ROS, Gazebo, Jackal robot simulation packages, and `move_base`/`eband_local_planner`. The README also requires Python packages like `numpy`, `rospkg`, `netifaces`, and `defusedxml`, which supports the Python orchestration and evaluation scripts.

12. A clean way to draw the architecture is: benchmark assets and world files on one side; simulation/orchestration in the middle (`run.py`, Gazebo, ROS launch/config, collision node); navigation stack as a swappable module set (`move_base` DWA/Eband or Python VFH); and evaluation/container tooling around the edges (`test.sh`, `report_test.py`, Singularity scripts).

Main entry points: [`run.py`](https://github.com/mazenmtulab/the-barn-challenge/blob/development/run.py) (run.py), [`jackal_helper`](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper) (Jackal helper), [`jackal_helper/launch/move_base_DWA.launch`](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_DWA.launch) (move_base DWA), [`jackal_helper/launch/move_base_eband.launch`](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_eband.launch) (move_base eband)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Orchestration"]
  node_n1["run.py<br/>entrypoint<br/>[run.py]"]
end

subgraph group_g2["Simulation"]
  node_n2["gazebo sim<br/>runtime wrapper"]
  node_n3["Gazebo launch<br/>ros launch"]
  node_n4["Collision node<br/>ros cpp node"]
  node_n10[("Jackal helper<br/>ros package")]
  node_n11["move_base params<br/>yaml config"]
  node_n12["costmap params<br/>yaml config"]
  node_n13["local planner<br/>yaml config"]
  node_n14["odom nav<br/>yaml config"]
end

subgraph group_g3["Navigation"]
  node_n5["move_base DWA<br/>ros launch"]
  node_n6["move_base eband<br/>ros launch"]
  node_n7["VFH launch<br/>ros launch<br/>[VFH_launch.launch]"]
  node_n8["Nav-VFH<br/>python planner<br/>[Nav-VFH.py]"]
  node_n9["Nav utils<br/>python support"]
end

subgraph group_g4["Benchmark Assets"]
  node_n15[("BARN worlds<br/>benchmark assets")]
  node_n16[("DynaBARN<br/>benchmark assets")]
  node_n17["Path files<br/>npy metadata"]
  node_n18["World files<br/>gazebo worlds<br/>[world_0.world]"]
end

subgraph group_g5["Evaluation"]
  node_n19["Batch test<br/>shell runner<br/>[test.sh]"]
  node_n20["Dynamic test<br/>shell runner<br/>[test_dynamic.sh]"]
  node_n21["Report<br/>python evaluator<br/>[report_test.py]"]
  node_n22["Container<br/>singularity"]
  node_n23["Entrypoint<br/>[entrypoint.sh]"]
  node_n24["Run script<br/>shell wrapper<br/>[singularity_run.sh]"]
end

node_n1 -->|"boots"| node_n2
node_n1 -->|"can launch"| node_n5
node_n1 -->|"can launch"| node_n6
node_n1 -->|"can launch"| node_n7
node_n2 -->|"uses"| node_n3
node_n3 -->|"part of"| node_n10
node_n4 -->|"signals outcome"| node_n1
node_n5 -->|"loads"| node_n11
node_n5 -->|"loads"| node_n12
node_n6 -->|"loads"| node_n11
node_n6 -->|"loads"| node_n12
node_n7 -->|"starts"| node_n8
node_n8 -->|"depends on"| node_n9
node_n10 -->|"owns"| node_n11
node_n10 -->|"owns"| node_n12
node_n10 -->|"owns"| node_n13
node_n10 -->|"owns"| node_n14
node_n15 -->|"contains"| node_n18
node_n15 -->|"contains"| node_n17
node_n16 -.->|"extends"| node_n18
node_n19 -->|"feeds"| node_n21
node_n20 -->|"feeds"| node_n21
node_n22 -->|"starts"| node_n23
node_n23 -->|"invokes"| node_n1
node_n24 -->|"wraps"| node_n22

click node_n1 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/run.py"
click node_n2 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/gazebo_simulation.py"
click node_n3 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/gazebo_launch.launch"
click node_n4 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/src/collision_publisher.cpp"
click node_n5 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_DWA.launch"
click node_n6 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_eband.launch"
click node_n7 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/launch/VFH_launch.launch"
click node_n8 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/scripts/Nav-VFH.py"
click node_n9 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/scripts/navigation_utils.py"
click node_n10 "https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper"
click node_n11 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/move_base_params.yaml"
click node_n12 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/costmap_common_params.yaml"
click node_n13 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/base_local_planner_params.yaml"
click node_n14 "https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/configs/params/odom_nav_params"
click node_n15 "https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/BARN"
click node_n16 "https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/DynaBARN"
click node_n17 "https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/BARN/path_files"
click node_n18 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/worlds/BARN/world_0.world"
click node_n19 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/test.sh"
click node_n20 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/test_dynamic.sh"
click node_n21 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/report_test.py"
click node_n22 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/Singularityfile.def"
click node_n23 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/entrypoint.sh"
click node_n24 "https://github.com/mazenmtulab/the-barn-challenge/blob/development/singularity_run.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n4,node_n10,node_n11,node_n12,node_n13,node_n14 toneAmber
class node_n5,node_n6,node_n7,node_n8,node_n9 toneMint
class node_n15,node_n16,node_n17,node_n18 toneRose
class node_n19,node_n20,node_n21,node_n22,node_n23,node_n24 toneIndigo
```

## Components

### Orchestration

Top-level run control and simulation bootstrapping

- [run.py](https://github.com/mazenmtulab/the-barn-challenge/blob/development/run.py): entrypoint · Main harness entrypoint that selects worlds and starts a navigation stack · `run.py`

### Simulation

Gazebo, robot integration, and benchmark runtime services

- [gazebo sim](https://github.com/mazenmtulab/the-barn-challenge/blob/development/gazebo_simulation.py): runtime wrapper · Python wrapper for launching Gazebo and loading the chosen world · `gazebo_simulation.py`
- [Gazebo launch](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/gazebo_launch.launch): ros launch · Launches the Gazebo simulation boundary for the Jackal benchmark · `jackal_helper/launch/gazebo_launch.launch`
- [Collision node](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/src/collision_publisher.cpp): ros cpp node · Compiled node that publishes collision state or termination signals · `jackal_helper/src/collision_publisher.cpp`
- [Jackal helper](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper): ros package · Simulation support package connecting planners, robot interfaces, and benchmark settings · `jackal_helper`
- [move_base params](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/move_base_params.yaml): yaml config · Core move_base and planner parameters · `jackal_helper/configs/params/move_base_params.yaml`
- [costmap params](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/costmap_common_params.yaml): yaml config · Shared costmap configuration for navigation stacks · `jackal_helper/configs/params/costmap_common_params.yaml`
- [local planner](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/configs/params/base_local_planner_params.yaml): yaml config · Base local planner tuning for move_base · `jackal_helper/configs/params/base_local_planner_params.yaml`
- [odom nav](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/configs/params/odom_nav_params): yaml config · Odometry-navigation costmap parameters · `jackal_helper/configs/params/odom_nav_params`

### Navigation

Swappable planner backends tested inside the harness

- [move_base DWA](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_DWA.launch): ros launch · Configures move_base with the DWA local planner · `jackal_helper/launch/move_base_DWA.launch`
- [move_base eband](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/launch/move_base_eband.launch): ros launch · Configures move_base with the eband local planner · `jackal_helper/launch/move_base_eband.launch`
- [VFH launch](https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/launch/VFH_launch.launch): ros launch · Launches the Python VFH-based navigation stack · `navigation_pkg/launch/VFH_launch.launch`
- [Nav-VFH](https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/scripts/Nav-VFH.py): python planner · VFH navigation controller used as an alternate backend · `navigation_pkg/scripts/Nav-VFH.py`
- [Nav utils](https://github.com/mazenmtulab/the-barn-challenge/blob/development/navigation_pkg/scripts/navigation_utils.py): python support · Shared helpers for the VFH navigation implementation · `navigation_pkg/scripts/navigation_utils.py`

### Benchmark Assets

Worlds and reference path data used for episodes

- [BARN worlds](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/BARN): benchmark assets · Static benchmark Gazebo worlds for episode sampling · `jackal_helper/worlds/BARN`
- [DynaBARN](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/DynaBARN): benchmark assets · Dynamic benchmark world set · `jackal_helper/worlds/DynaBARN`
- [Path files](https://github.com/mazenmtulab/the-barn-challenge/tree/development/jackal_helper/worlds/BARN/path_files): npy metadata · Reference paths or scenario metadata for BARN evaluation · `jackal_helper/worlds/BARN/path_files`
- [World files](https://github.com/mazenmtulab/the-barn-challenge/blob/development/jackal_helper/worlds/BARN/world_0.world): gazebo worlds · Indexed benchmark world definitions · `jackal_helper/worlds/BARN/world_0.world`

### Evaluation

Batch runs, reporting, and container entrypoints

- [Batch test](https://github.com/mazenmtulab/the-barn-challenge/blob/development/test.sh): shell runner · Runs repeated benchmark episodes across sampled worlds · `test.sh`
- [Dynamic test](https://github.com/mazenmtulab/the-barn-challenge/blob/development/test_dynamic.sh): shell runner · Batch runner focused on dynamic benchmark episodes · `test_dynamic.sh`
- [Report](https://github.com/mazenmtulab/the-barn-challenge/blob/development/report_test.py): python evaluator · Aggregates run results into benchmark metrics and success rates · `report_test.py`
- [Container](https://github.com/mazenmtulab/the-barn-challenge/blob/development/Singularityfile.def): singularity · Reproducible submission runtime definition · `Singularityfile.def`
- [Entrypoint](https://github.com/mazenmtulab/the-barn-challenge/blob/development/entrypoint.sh): shell entrypoint · Container startup script for the benchmark harness · `entrypoint.sh`
- [Run script](https://github.com/mazenmtulab/the-barn-challenge/blob/development/singularity_run.sh): shell wrapper · Convenience wrapper for launching the containerized benchmark · `singularity_run.sh`

## Connections

- run.py → gazebo sim: boots · run.py delegates simulation startup and world selection
- run.py → move_base DWA: can launch · run.py selects a move_base-based backend when configured
- run.py → move_base eband: can launch · run.py selects the alternative move_base backend when configured
- run.py → VFH launch: can launch · run.py can initialize the VFH navigation stack
- gazebo sim → Gazebo launch: uses · Simulation wrapper calls the Gazebo launch boundary
- Gazebo launch → Jackal helper: part of · Gazebo launch belongs to the Jackal helper ROS package
- Collision node → run.py: signals outcome · Collision state feeds benchmark termination and scoring
- move_base DWA → move_base params: loads · DWA move_base launch consumes planner settings
- move_base DWA → costmap params: loads · DWA stack consumes shared costmap settings
- move_base eband → move_base params: loads · Eband move_base launch consumes planner settings
- move_base eband → costmap params: loads · Eband stack consumes shared costmap settings
- VFH launch → Nav-VFH: starts · VFH launch starts the Python planner
- Nav-VFH → Nav utils: depends on · Planner logic uses shared VFH utilities
- Jackal helper → move_base params: owns · Jackal helper provides navigation parameter sets
- Jackal helper → costmap params: owns · Jackal helper provides shared costmap parameters
- Jackal helper → local planner: owns · Jackal helper provides local planner parameters
- Jackal helper → odom nav: owns · Jackal helper provides odometry-navigation parameters
- BARN worlds → World files: contains · BARN benchmark set includes Gazebo world files
- BARN worlds → Path files: contains · BARN benchmark set includes reference path data
- DynaBARN → World files: extends · Dynamic benchmark family is a related world collection
- Batch test → Report: feeds · Batch test results are summarized by the report script
- Dynamic test → Report: feeds · Dynamic batch results are summarized by the report script
- Container → Entrypoint: starts · Container definition uses the entrypoint script
- Entrypoint → run.py: invokes · Container startup ultimately runs the benchmark entrypoint
- Run script → Container: wraps · Convenience script runs the singularity container
