A scenario-testing framework for validating Autoware
on the CARLA simulator. A Hydra-driven scenario runner
loads an OpenDRIVE map into CARLA, drives an Autoware ego vehicle, evaluates
pass/fail conditions, and records JSON results and a trajectory log of every
run (seen in the Rerun viewer: with the rerun extra and rerun.enabled=true,
each run's log becomes a .rrd recording as the run ends). It ships a FastAPI viewer
for browsing runs and a FastAPI editor for authoring scenarios and exporting
them as reproducible packages.
The maps are typically produced by
autoware_lanelet2_to_opendrive,
which converts Lanelet2 .osm maps to OpenDRIVE. This framework used to live in
that repository as a second workspace member, but it does not depend on the
converter: a Lanelet2 map and an OpenDRIVE map are loaded side by side as two
independent coordinate systems, related only through CARLA world coordinates.
Any OpenDRIVE file that describes the same place as the Lanelet2 map will do.
.
├── autoware_carla_scenario/ # The framework package (uv workspace member)
├── data/ # nishishinjuku fixture map used by the tests and examples
├── examples/scenario_package_template/ # A standalone scenario package to copy
├── .github/actions/ # Composite actions (incl. scenario image packing)
├── pyproject.toml # uv workspace root
└── uv.lock
To test a driving policy in a project of your own -- no ROS 2, no Autoware, one command once CARLA is downloaded:
uv add autoware-carla-scenario
uv run scenario-setup # downloads CARLA's nightly build into ~/.autoware_carla_scenario/bin
uv run scenario scenario=cut_in/left map=town10hd_opt \
ego.spawn_lanelet_id=324 scenario.npc_lanelet_id=446 \
ego.entity=carla_driver driver.policy=route_followerThe last command launches CARLA, serves the policy in its own process and runs the
scenario. docs/quickstart.md walks
through it, your own policy included.
Python 3.10 to 3.14. Every dependency installs from a wheel or from git — no apt
packages, no C++ toolchain, no container. git has to be on PATH: pre-commit
fetches its hooks with it, the map-cache tests and the git map sources run it,
and on Python 3.10 to 3.12 uv also clones
t4-devkit, the dev dependency the T4
dataset tests read their datasets back with (it supports only Python 3.10 to
3.12, so 3.13 and 3.14 skip it).
uv sync --devThe CARLA client is typesafe_carla
(CARLA UE5: 0.10.0 and ue5-dev; Linux x86_64 and aarch64), imported as
import typesafe_carla.carla as carla. Its PyPI wheel carries the CPython
package prebuilt, so the sync above is the whole install; see
installation for the cases that
build it instead. The official carla wheels, and CARLA 0.9.16 (UE4), are no
longer used.
Run a scenario against the bundled nishishinjuku map. Its OpenDRIVE file,
data/nishishinjuku_carla.xodr, is committed next to the Lanelet2 one; it was
generated once with the converter's convert CLI, which this repository does
not install:
uv run scenario scenario=intersection_passing/straight map=nishishinjukuBefore it runs, every scenario is compiled with Codon
against a typed model of the framework and typesafe_carla's CARLA API, and one that does
not type-check is refused before CARLA starts. uv run scenario-check makes the same check without
running anything; see
docs/typecheck.md.
See autoware_carla_scenario/README.md and
the documentation under autoware_carla_scenario/docs/
for the full guide.
uv run pytest -n auto -o addopts= -m "not slow" # what CI's fast job runs
uv run pre-commit run --all-files # what CI's lint job runsReleases are cut by .github/workflows/release.yml when a pull request is
merged into master with exactly one version bump label (bump patch,
bump minor or bump major). The workflow bumps version in
autoware_carla_scenario/pyproject.toml, re-locks, tags v<version>, creates
the GitHub Release with the documentation attached, and deploys the docs to
GitHub Pages. It then builds the wheel and sdist, installs the wheel on every
supported Python (3.10 to 3.14), and publishes both to
PyPI as
autoware-carla-scenario. A merge without a label releases nothing.
GitHub Pages keeps the docs of dev and the newest 20 releases only
(.github/scripts/publish-docs.sh); a site over 1 GB fails to deploy. Every
release keeps its full documentation as the .zip and .pdf assets of its
GitHub Release.
PyPI uploads use Trusted Publishing, so no API token is stored. Before the
first release, add a (pending) trusted publisher on PyPI with owner
autowarefoundation, repository autoware_carla_scenario, workflow
release.yml and environment pypi, and create the pypi environment in
this repository's settings.
If a labelled merge bumped the version but a later step failed, run the
workflow by hand (Actions → Release → Run workflow) with that version, e.g.
2.63.0. A manual run does not bump: it builds from the version's tag, or else
from its chore: bump version to X commit on master, so merges that landed
since do not leak in, and it reuses any tag, Release or asset the failed run
already created and uploads to PyPI only the files that are not there yet. Do
not re-run the failed push run: it would bump a second time from the old merge
commit.
The version line continues from autoware_lanelet2_to_opendrive, where this
package started: it was split out at 2.62.0, so the first release here is
2.62.1. The workflow pushes with the GH_PAT repository secret when there is
one, and with GITHUB_TOKEN otherwise.
Apache-2.0. See LICENSE.