Welcome to Robot SF, a Gymnasium-based social-navigation simulation and benchmarking framework for a robot moving through pedestrian-filled environments. This guide is the task-oriented entry point for anyone who wants to install, run, and use Robot SF without diving into internals or research methodology.
New to the terminology? Start with the Glossary — canonical definitions for acronyms and project terms (VRU, AMV, AMMV, SNQI, occluder, the evidence ladder, and more).
- Adoption path — the shortest install → doctor → demo → examples → recipes → gallery journey.
- Quickstart Map — first local checks, install, and one-command demos.
- Development Guide — full
uv sync --all-extrassetup, virtualenv, and pre-commit hooks. - Runtime Requirements — non-
uvhost tools, Docker, GPU/SLURM, and the local capability checker. - Environment Configuration — detailed host environment setup and usage.
- The Adoption path shows the complete beginner flow and the claim boundary for its local smoke/inspection artifacts.
- Examples Index — quickstart, advanced, benchmark, and plotting workflows.
examples/quickstart/01_basic_robot.py— minimal robot simulation.examples/quickstart/02_trained_model.py— run a trained model.examples/quickstart/03_custom_map.py— load a custom SVG map.
- Simulation View — visualization and rendering system.
- SVG Map Editor — SVG-based map creation tools and usage.
- OSM Map Generation — reproducible maps from OpenStreetMap data.
- Single Pedestrians — define individual pedestrians with goals or trajectories.
- Map Verification — validate SVG maps for structural integrity and runtime compatibility.
- SVG Inspection Workflow — check route/zone consistency with
scripts/validation/svg_inspect.py. - Scenario Zoo — maintained and emerging scenario families.
- Scenario Specification Checklist — authoring checklist for per-scenario/manifest files.
- Planner Zoo — runnable, diagnostic-only, learned-policy, and blocked planner rows.
- Planner Contribution Guide — minimum path to add a planner.
- Planner selection — visibility vs classic grid global planners.
- Global Planner quickstart — visibility-graph planner API, POI routing, integration guidance.
- Social Navigation Benchmark Quickstart — step-by-step experiment execution, visualization, and interpretation.
- Benchmark Runner And Metrics — episode schema, aggregation, metrics (collisions, comfort exposure, SNQI), and the local smoke benchmark demo.
- Local smoke benchmark demo:
uv run python scripts/demo/run_robot_sf_smoke.py. - Mechanism-aware diagnostic reproduction:
uv run python scripts/demo/reproduce_mechanism_report.py --case topology-primary-route.
- Trajectory Visualization — generate trajectory plots.
- Force Field Visualization — heatmap + quiver figures (PNG/PDF).
- Pareto Plotting — generate Pareto frontier plots.
- Planner Tradeoff Plotting — success/collision tradeoff figures.
- Benchmark Visual Artifacts — SimulationView & synthetic video pipeline.
- SNQI Figures (orchestrator usage) — SNQI-augmented figures from episodes.
- External Data Setup Assistant — license-safe staging and provenance manifests (Stanford Drone Dataset, SocNavBench, ETH/UCY, AMV calibration sources).
- ETH/UCY External Trajectory Data — acquisition, citation, expected layout.
- SocNav Asset Setup — license-safe SocNav third-party dataset staging.
- Real-World Trajectory Import — Stanford Drone Dataset importer.
- Debug Visualization — visual debugging aids.
- Telemetry Pane Display Fix — continuous graph rendering and buffer management.
- Runtime Requirements Checker — inventory missing host tools.
- Security Triage Guidance — vulnerability reporting and dependency scanning.
- Want to publish a trustworthy result? Move to the Research & Benchmark Guide.
- Want to extend the codebase (planners, scenarios, sim internals)? Move to the Developer Guide.