This file is auto-generated by
scripts/validation/render_examples_readme.py. Edit the manifest or supporting scripts instead of modifying this README directly.
The examples are organized into learning tiers. Start with Quickstart for an introductory walkthrough, explore Advanced Features for targeted demos, runtime evaluation tooling lives under Benchmarks, and plotting resources reside in Plotting & Analysis. Archived scripts remain available for reference but are excluded from CI by default.
- Need a five-minute tour? Run the quickstart trio in order:
01_basic_robot.py→ learns the factory pattern and random rollout.02_trained_model.py→ replays the bundled PPO agent.03_custom_map.py→ swaps in an SVG map for custom layouts.
- Looking for a specific capability? Jump to Advanced Features and
filter by tags such as
image,pedestrian, orbackend. - Validating performance? Use the Benchmarks tier to produce JSONL episode logs for aggregation.
- Visualizing results? Try the Plotting & Analysis scripts to convert benchmark outputs into figures.
uv run python examples/quickstart/01_basic_robot.py
uv run python examples/quickstart/02_trained_model.py
uv run python examples/quickstart/03_custom_map.pyEach command runs headless and finishes in under two minutes. The sequence introduces factory-based environment creation, benchmark automation, and map customization without requiring additional assets beyond the repository.
Many examples are intentionally thin wrappers around reusable helpers. Before copying setup, policy-loading, recording, or output-directory code into a new example, check the helper catalog for the canonical helper surface and expected usage pattern.
Pending classification into the new tiered structure.
No examples assigned yet.
Foundational walkthroughs for first-time users.
| Example | Summary | Prerequisites | Tags | CI |
|---|---|---|---|---|
| 01 Basic Robot Rollout | Run a basic Robot SF environment with a random policy. | None | quickstart | ✅ |
| 02 Trained PPO Benchmark | Run the Robot SF benchmark with the pre-trained PPO baseline. | configs/baselines/example_matrix.yaml configs/baselines/ppo.yaml |
quickstart, benchmark | ✅ |
| 03 Custom SVG Map | Load an SVG map into Robot SF and simulate random navigation. | maps/svg_maps/debug_06.svg | quickstart, maps | ✅ |
| 04 Occupancy Grid | Enable occupancy grid observations, run a center query, and step a short rollout. | None | quickstart, occupancy, grid | ✅ |
Feature-focused demos for developers exploring capabilities.
| Example | Summary | Prerequisites | Tags | CI |
|---|---|---|---|---|
| 01 Backend Selection | Switch Robot SF backends using unified config. | None | backend | ✅ |
| 02 Factory Options | Compare environment factory options for rendering and recording. | None | factory | ✅ |
| 03 Image Observations | Enable image-based observations in the robot environment. | None | image | ✅ |
| 04 Feature Extractors | Run PPO demos with different feature extractors. | uv sync --all-extras | training, feature-extractor | |
| 05 Fast-pysf Speed Fix | Inspect the fast-pysf pedestrian speed fix output. | None | analysis, fast-pysf | ✅ |
| 06 Pedestrian Env Factory | Compare factory and legacy pedestrian environment creation. | maps/svg_maps/debug_06.svg model/pedestrian/ppo_ped_02.zip model/run_043 |
pedestrian, factory | |
| 07 Single Pedestrian | Spawn and simulate single pedestrians with custom maps. | None | pedestrian | ✅ |
| 08 Multi-Pedestrian | Build a multi-pedestrian scenario using map definitions. | None | pedestrian | ✅ |
| 09 Defensive Policy | Replay defensive PPO policy with observation adapters. | model/run_023 | policy, ppo | |
| 10 Offensive Policy | Replay offensive PPO policy in the robot environment. | model/run_043 | policy, ppo | |
| 11 Ego Pedestrian Policy | Run ego pedestrian simulation with recording playback. | maps/svg_maps/narrow_corridor2.svg model/run_043 |
pedestrian, recording | |
| 12 Social Force Planner | Explore Social Force planner scenarios and options. | uv sync --all-extras fast-pysf subtree (bundled) |
planner, social-force | ✅ |
| 13 SVG Map Validation | Validate and summarize SVG maps from the repository. | None | maps, tooling | ✅ |
| 14 Trajectory Visualization | Visualize trajectories during interactive playback sessions. | recordings/.pkl | visualization, playback | |
| 15 View Recording | Record a simulation from an SVG map and replay it. | maps/svg_maps/02_simple_maps.svg | recording, maps | ✅ |
| 16 Imitation Learning Pipeline | End-to-end imitation learning workflow: expert training → trajectory collection → BC pre-training → PPO fine-tuning. | uv sync --all-extras configs/training/ppo_imitation/*.yaml |
training, imitation, ppo, behavioral-cloning | |
| 20 Global Planner Demo | Demonstration of global planner integration with environment factory. | None | planning, routing, poi | |
| 21 Occupancy Grid Workflow | Standalone grid generation, spawn validation queries, and occupancy-based reward shaping. | None | occupancy, reward, observation | ✅ |
| 22 Occupancy Grid Playthrough | Interactive occupancy grid playthrough demonstration. | None | occupancy, interactive | |
| 23 POI Routing Demo | Sample POIs and route through them with the global planner on an SVG map. | None | planning, routing, poi, sampling | |
| 24 Planner Bottleneck Test | Analyze planner clearance behavior on a bottleneck corridor map. | maps/svg_maps/planner_test_corridor.svg | planning, diagnostics, clearance | |
| 25 Planner Diagnostic | Visualize inflation and visibility-graph internals for planner debugging. | maps/svg_maps/planner_test_corridor.svg | planning, diagnostics, visualization | |
| 26 Telemetry Pane | Live telemetry visualization with docked charts in the Pygame window showing FPS, reward, collisions, and pedestrian distance. | None | telemetry, visualization, pygame, interactive | |
| 27 Telemetry Headless Smoke | Headless telemetry smoke test producing JSONL and summary PNG/JSON artifacts without rendering. | None | telemetry, visualization, headless, ci | |
| 32 Demo Adversarial Pedestrian | Run a modernized debug rollout for pedestrian PPO policies with factory-based setup. | maps/svg_maps/masterthesis/intersection.svg model/run_043 model/pedestrian/ppo_intersection.zip |
pedestrian, policy, debug, ppo | |
| 33 Three.js Recording Viewer | Export a JSONL or pickle recording to a static browser viewer. | None | visualization, recording, threejs | ✅ |
| 34 Trace Three.js Viewer | Export a simulation_trace_export.v1 trace to a static browser viewer. | None | visualization, trace, annotation, threejs | ✅ |
| Occupancy Reward Shaping | Derive a clearance penalty from occupancy grid observations in a short rollout. | None | occupancy, reward, grid | ✅ |
Benchmark runners and evaluation workflows.
| Example | Summary | Prerequisites | Tags | CI |
|---|---|---|---|---|
| Demo Aggregate | Aggregate episode metrics with optional bootstrap confidence intervals. | None | benchmark, aggregation | ✅ |
| Demo Full Classic Benchmark | Run the full classic interaction benchmark via programmatic helper. | None | benchmark | ✅ |
| Demo Social Nav Scenarios | Run social navigation SVG scenarios sequentially. | None | benchmark, scenario | ✅ |
| SNQI Full Flow | End-to-end SNQI figure generation flow. | None | benchmark, snqi |
Visualization and analysis scripts built atop benchmark outputs.
| Example | Summary | Prerequisites | Tags | CI |
|---|---|---|---|---|
| Coverage Example | Coverage tools programmatic usage example. | None | coverage, tooling | ✅ |
| Data Analysis Example | Perform a showcase on how to use the data analysis module. | None | analysis | ✅ |
| Paper Figure: PPO Observation Grid | Build a PPO occupancy-grid observation figure from rendered scenario videos. | None | paper, figures, plotting, benchmark | |
| Paper Figure: Planner Trade-off | Build the mandatory planner safety–efficiency tradeoff figure for the AMV paper. | None | paper, figures, plotting, benchmark | |
| Paper Figure: Runtime Scene Panels | Build publication-ready runtime scene panel figures from benchmark videos/frames. | None | paper, figures, plotting, benchmark | |
| Paper Table: Scenario Coverage Matrix | Build a manuscript-facing AMV scenario coverage matrix. | None | paper, figures, plotting, benchmark | |
| Paper Figure: Scenario SVG Overview | Build a scenario-map overview figure from source SVG files. | None | paper, figures, plotting, benchmark | |
| Plot Force Field | Plot a sampled social-force field using matplotlib. | None | visualization, force-field | ✅ |
| Plot Force Field Normalized | Plot normalized force vectors with a magnitude colormap and save PNG+PDF. | None | visualization, force-field | ✅ |
| Plot Force Field Save | Generate and save static images of the force field for documentation. | None | visualization, force-field | ✅ |
| Plot Pareto | Generate Pareto front plots from benchmark episodes or synthetic data. | None | visualization, pareto | |
| Plot Pedestrian Position KDE | Plot a KDE of pedestrian positions on top of the source map. | None | visualization, pedestrian | ✅ |
| SNQI Figures Example | Generate publication-ready SNQI figures via the orchestrator script. | None | visualization, snqi |