CrowdNav

CrowdNav is a research framework for training and evaluating socially-aware robot navigation policies in crowded environments. A robot learns to navigate to a goal among multiple humans (controlled by unknown policies such as ORCA) while avoiding collisions and behaving in a socially acceptable way.

The project bundles an OpenAI Gym simulation environment (crowd_sim/) with a set of learning/classical navigation policies (crowd_nav/), and includes a vendored copy of the Python-RVO2 library used for human motion simulation.

Project Layout

crowdnav-dip/
├── crowd_sim/           # OpenAI Gym simulation environment (humans + robot)
│   └── envs/
├── crowd_nav/           # Policies, training, and testing code
│   ├── configs/         # env.config, policy.config, train.config
│   ├── policy/          # cadrl, lstm_rl, sarl, multi_human_rl
│   ├── utils/           # trainer, explorer, replay memory
│   ├── data/            # trained models and outputs (e.g. data/output_trained)
│   ├── train.py
│   └── test.py
├── Python-RVO2-main/    # Vendored Python-RVO2 library (ORCA solver bindings)
└── setup.py

Available Policies

Implemented in crowd_nav/policy/ — see crowd_sim/README.md for more detail.

• ORCA — reciprocal, collision-free velocity (classical baseline)
• CADRL — value network predicting action for the most important human
• LSTM-RL — LSTM encoder over human states
• SARL — pairwise interaction module + self-attention over humans
• OM-SARL — SARL extended with a local occupancy map for intra-human interaction

Setup

Prerequisites

• conda — install from Miniconda if missing.

• ffmpeg — required for video export (crowdnav-baseline, --video_file).

• cmake + a C++ toolchain — needed once to build the vendored Python-RVO2.

  • Linux: sudo apt install ffmpeg cmake build-essential
  • macOS: brew install ffmpeg cmake

One-command install

./scripts/setup_env.sh
conda activate navigate

The script is idempotent (safe to re-run) and performs:

1. Creates the navigate conda env on Python 3.10 (conda-forge).
2. Builds the vendored Python-RVO2 with CMAKE_POLICY_VERSION_MINIMUM=3.5 for CMake ≥ 4.
3. Installs the crowdnav package editable with the [test] extra (PyQt5 + pytest-qt + pytest-cov).
4. Runs crowdnav-preflight to verify rvo2, ffmpeg, gymnasium, and the trained SARL model.

Verify the install

crowdnav-preflight    # should exit 0 with all four checks green (rvo2, ffmpeg, gymnasium, model)
pytest -m smoke -v    # end-to-end smoke for WP-1/3/4/5 (~2–3 min)

Manual setup (if you prefer not to use the script)

conda create -n navigate --override-channels -c conda-forge python=3.10
conda activate navigate
pip install "cython<3"

# Python-RVO2 (CMake >= 4 requires the policy flag)
export CMAKE_POLICY_VERSION_MINIMUM=3.5
(cd Python-RVO2-main && python setup.py build && python setup.py install)

pip install -e ".[test]"
crowdnav-preflight

Getting Started

The repository is organized in two parts: crowd_sim/ contains the simulation environment and crowd_nav/ contains the training and testing code. Simulation framework details: crowd_sim/README.md. Commands below should be run from inside crowd_nav/.

Console scripts

Installed by ./scripts/setup_env.sh:

Command	Purpose
crowdnav-preflight	Verify rvo2, ffmpeg, gymnasium, trained model
crowdnav-gui	Launch the PyQt5 main window (interactive demo)
crowdnav-baseline	Reproduce R1 → exports/baseline.mp4

For custom rollouts, drop to python test.py ... — see below.

Visualize a rollout

Three paths, pick the one that matches what you're doing:

1. Interactive GUI (recommended for demos)

crowdnav-gui

Launches the PyQt5 main window (slide-14 demo). Load a model via File → Load Model, pick a scenario with the toolbar, then Run to animate. Supports pausing, stepping, obstacle editing, and exporting the current rollout to MP4. See crowd_nav/gui/.

2. Scripted baseline (reproducible video)

crowdnav-baseline        # → exports/baseline.mp4

Runs the trained SARL policy on test case 0 under seed 42 and writes exports/baseline.mp4. Deterministic across runs on the same machine. Equivalent to ./scripts/run_baseline.sh.

3. Flag-driven test.py (custom rollouts)

cd crowd_nav
python test.py --policy sarl --model_dir data/output_trained --phase test --visualize --test_case 0

Useful flags (see crowd_nav/test.py):

• --policy {orca, cadrl, lstm_rl, sarl} — policy to evaluate
• --model_dir <path> — directory containing rl_model.pth and config files
• --phase {train, val, test} — dataset phase
• --test_case <int> — specific scenario id to visualize
• --visualize — show an animated rollout (matplotlib)
• --video_file <path> — save the rollout to MP4 (requires ffmpeg)
• --traj — overlay trajectories
• --gpu — run on GPU

Train a policy

cd crowd_nav
python train.py --policy sarl

Useful train.py flags (see crowd_nav/train.py):

• --policy {cadrl, lstm_rl, sarl} — policy to train
• --output_dir <path> — where checkpoints and logs are written (default data/output)
• --resume — resume from a previous run in --output_dir
• --gpu — train on GPU
• --debug — enable debug logging

Training parameters live in crowd_nav/configs/train.config; environment parameters (number of humans, scenario type, reward shaping) in crowd_nav/configs/env.config; policy hyperparameters in crowd_nav/configs/policy.config.

Reproducing R1 (baseline + video)

R1 means: install the env, re-run the given DRL policy, export a simulation video.

./scripts/run_baseline.sh
# → exports/baseline.mp4

Verify end-to-end with the smoke test:

pytest -m smoke -v

What this covers:

• Loads the trained SARL policy from crowd_nav/data/output_trained/rl_model.pth (no retraining — per R7).
• Runs test case 0 under seed 42 — deterministic log lines are byte-identical across runs on the same machine (NF3).
• Writes exports/baseline.mp4 (~500 KB–1 MB, ffmpeg-encoded).

See docs/R1_VERIFICATION.md for the full manual checklist.

Troubleshooting

• Python-RVO2 build fails — make sure cython is installed in the active env and cmake/build-essential are on the system. On CMake 4+, setup_env.sh exports CMAKE_POLICY_VERSION_MINIMUM=3.5 to keep the vendored build compatible.
• gymnasium API errors — the CrowdSim env keeps non-standard reset(phase, test_case) and 4-tuple step() signatures from the original gym-based design. Call sites instantiate CrowdSim() directly rather than going through gymnasium.make() so the OrderEnforcing/PassiveEnvChecker wrappers don't reject the legacy signatures.
• CUDA/GPU — omit --gpu to run on CPU; all scripts work without a GPU.
• ffmpeg not found — --video_file will error with "ffmpeg not found on PATH". Install ffmpeg (Linux apt install ffmpeg, macOS brew install ffmpeg) and re-run. The render module autodetects via shutil.which at import time.