Usage Guide¶

This guide explains how to use the autoware-carla-scenario package to run autonomous driving scenario tests in CARLA simulator.

CLI Commands Overview¶

The package provides these CLI commands:

Command	Framework	Purpose
`scenario`	Hydra	Run autonomous driving scenario tests in CARLA
`scenario-new`	argparse	Scaffold a standalone scenario package
`scenario-check`	Hydra compose	Compile scenarios with Codon without running them (the static check the runner makes before a run)
`scenario-odd`	argparse	Check an ODD and show its buckets; `scenario-odd route` checks scenarios' planned routes against it on the Lanelet2 map
`detect-no-3d-model`	argparse	Detect lanelets without a matching 3D ground model in CARLA
`viewer`	FastAPI + Uvicorn	Web UI for browsing and monitoring scenario test results
`scenario-editor`	FastAPI + Uvicorn	Web UI for authoring scenarios and exporting reproducible packages

viewer and scenario-editor are separate applications on separate ports, and neither starts the other.

`scenario` - Scenario Runner¶

Runs autonomous driving scenario tests in CARLA. Uses Hydra for configuration management. Requires a running CARLA server.

How It Works¶

Parses the scenario=... argument (supports glob patterns for batch execution)
Composes a Hydra config from map, server, ego, entity, and scenario configs
Compiles the scenario with Codon and refuses it if it does not type-check (Static Check; typecheck=off skips it)
Connects to the CARLA server and loads the specified map (OpenDRIVE or built-in)
Spawns the ego vehicle at the configured Lanelet2 position (converted to CARLA coordinates)
Enables synchronous mode (fixed 20 Hz tick rate) and starts the native CARLA recorder
Runs a warm-up phase (5 ticks for physics stabilization)
Enables autopilot and applies initial speeds
Executes the main tick loop, checking pass/fail conditions each tick
Writes results as JSON and optionally renders a video from the recording
Reloads the CARLA world for clean state between scenarios

Basic Usage¶

# Run a single scenario
uv run scenario scenario=intersection_passing/straight

# Run a left-turn variant
uv run scenario scenario=intersection_passing/left_turn

# Run traffic light compliance scenario
uv run scenario scenario=traffic_light_compliance/traffic_light_compliance

# Run a lane change scenario
uv run scenario scenario=lane_change/left

# Run a temporary stop scenario
uv run scenario scenario=temporary_stop/temporary_stop

Batch Execution with Glob Patterns¶

When the scenario= value contains glob metacharacters (*, ?, [), all matching scenario configs are executed sequentially in a single CARLA session:

# Run all intersection-passing variants
uv run scenario scenario='intersection_passing/*'

# Run all scenarios matching a partial pattern
uv run scenario scenario='intersection_passing/left_*'

# Run all lane-change scenarios
uv run scenario scenario='lane_change/*'

# Run everything
uv run scenario scenario='*/*'

Batch constraints:

All scenarios in a batch must share the same map (CARLA loads one map per session)
Results are written to outputs/YYYY-MM-DD/HH-MM-SS/batch_results.json
A summary table is printed at the end with per-scenario pass/fail status
A scenario with a sweep: section runs once, as configured; add --multirun to run every case of it (see Running every sweep case in a batch)

Running every sweep case in a batch¶

With --multirun, a batch expands each scenario's sweep: -- lanelet constraints, a route search, the ODD sampler -- into its cases, the same ones scenario-expand prints, and runs them all in the one queue, against one CARLA session (and, with autoware.launcher, a fresh Autoware per case):

# Every lanelet case of both cut-in scenarios
uv run scenario --multirun 'scenario=cut_in/*' map=town10hd_opt

# 10 cases per scenario drawn from the ODD
uv run scenario --multirun 'scenario=cut_in/*' map=town10hd_opt \
  +sweep.odd_sample.count=10 +sweep.odd_sample.strategy=coverage

Scenarios that draw from one ODD go on from each other's draws rather than each draw the same cases: with strategy: coverage a later scenario aims at what the earlier ones left uncovered (see Sampling scenarios from the ODD).

A scenario with more than one case is listed as name#k in the summary, and batch_results.json gives each case its overrides. hydra/sweeper=... may be given but is not needed: the batch is the sweeper.

Selecting a Published HD Map¶

A map group can name a git repository instead of local files, and the map is fetched into ~/autoware_data/maps on first use -- the same directory Autoware's own setup downloads maps into, so a machine that has run it clones nothing:

# Town10HD_Opt, as published for CARLA 0.10, pinned to a commit. The built-in
# scenario configs name Nishishinjuku lanelets, so place the ego on Town10's.
uv run scenario scenario=lane_change/left map=town10hd_opt \
  ego.spawn_lanelet_id=324 ego.spawn_s=10.0 ego.goal_lanelet_id=5650

# Any repository, any revision
uv run scenario map=town10hd_opt \
  map.source='git+https://huggingface.co/datasets/OWNER/NAME@REF#maps/T'

# A map directory on this machine, read in place
uv run scenario map=town10hd_opt map.directory=/path/to/autoware_maps/Town10HD_Opt

See HD Maps from a Git Repository.

Lanelet Constraint Sweeping¶

The package ships a Hydra Sweeper plugin (hydra/sweeper=lanelet_constraint) that expands a single scenario config into one job per lanelet that matches a set of constraints, optionally deriving per-job parameters via "bindings". Each scenario YAML may declare its own sweep: section (see traffic_light_compliance.yaml for an example).

# Run a Hydra multirun over every lanelet whose `ego.spawn_lanelet_id`
# satisfies the scenario's `sweep.constraints`.
uv run scenario --multirun scenario=traffic_light_compliance/traffic_light_compliance \
  hydra/sweeper=lanelet_constraint

# Resume a sweep from job number N (1-indexed; 0 disables).
uv run scenario --multirun scenario=traffic_light_compliance/traffic_light_compliance \
  hydra/sweeper=lanelet_constraint sweep.resume_from=10

Sweeps write results under multirun/YYYY-MM-DD/HH-MM-SS/<job-index>/, not outputs/. The result viewer scans both directories.

To get the concrete scenarios without running them (for example, to fan them out over a cluster), use scenario-expand. It takes the same arguments as scenario and prints JSON with one list of Hydra overrides per concrete scenario. These are the same cases, in the same order, that the sweeper runs:

uv run scenario-expand scenario=traffic_light_compliance/traffic_light_compliance
# {"scenario": "...", "cases": [["ego.spawn_lanelet_id=5", "ego.spawn_s=18.62..."], ...]}

A scenario without a sweep: section is already concrete, so it expands to a single empty case. Only the Lanelet2 map is needed, not a CARLA server.

A logical scenario -- a document with a route search, whose sweep: holds route: instead of constraints: -- expands to one case per route of the map that matches its pattern, each with the ego's spawn and goal and the match itself (scenario.route.*); see Logical Scenarios from Routes.

Resume from a Specific Scenario¶

When running large batches, you can skip already-completed scenarios. --resume-from N starts at the Nth scenario (1-indexed, as for a sweep); in a --multirun batch it counts the expanded cases:

# Resume from the 3rd scenario
uv run scenario scenario='intersection_passing/*' --resume-from 3

Overriding Configuration Parameters¶

Any nested Hydra parameter can be overridden from the command line:

# Select a different map
uv run scenario scenario=intersection_passing/straight map=nishishinjuku

# Connect to a remote CARLA server
uv run scenario scenario=intersection_passing/straight server.host=192.168.1.100 server.port=3000

# Change ego vehicle type and speed
uv run scenario scenario=intersection_passing/straight \
  ego.vehicle_type=vehicle.tesla.model3 \
  ego.initial_speed_kmh=30.0

# Override scenario-specific parameters
uv run scenario scenario=intersection_passing/straight scenario.timeout_seconds=15.0

# Change Traffic Manager port
uv run scenario scenario=intersection_passing/straight traffic_manager.port=8200

Hydra Configuration System¶

Configuration files are located in src/autoware_carla_scenario/examples/conf/:

conf/
├── config.yaml              # Root config (defines defaults and top-level overrides)
├── server/
│   └── localhost.yaml       # Server connection settings
├── ego/
│   └── default.yaml         # Ego vehicle settings
├── entity/
│   └── default.yaml         # Entity spawn and ground projection settings
├── traffic_manager/
│   └── default.yaml         # CARLA Traffic Manager settings
├── map/
│   └── nishishinjuku.yaml   # Map file paths and excluded lanelet IDs
└── scenario/
    ├── intersection_passing/
    │   ├── straight.yaml
    │   ├── left_turn.yaml
    │   ├── right_turn.yaml
    │   └── straight_3npc.yaml
    ├── lane_change/
    │   ├── left.yaml
    │   └── right.yaml
    ├── lane_change_fail/
    │   ├── left.yaml
    │   └── right.yaml
    ├── temporary_stop/
    │   └── temporary_stop.yaml
    └── traffic_light_compliance/
        └── traffic_light_compliance.yaml

Root Configuration (`config.yaml`)¶

Defines the default config group composition:

Default Group	Default Value	Description
`server`	`localhost`	CARLA server connection
`ego`	`default`	Ego vehicle configuration
`entity`	`default`	Entity spawn and ground projection
`traffic_manager`	`default`	CARLA Traffic Manager
`scenario`	`intersection_passing/left_turn`	Scenario to run
`map`	`nishishinjuku`	Map to load

Server Configuration¶

Parameter	Type	Default	Description
`server.host`	str	`localhost`	CARLA server hostname
`server.port`	int	`2000`	CARLA server port
`server.cooldown_seconds`	float	`2.0`	Wait time between consecutive scenario runs
`server.cooldown_max_retries`	int	`0`	Maximum retries on failure

Ego Vehicle Configuration¶

Parameter	Type	Default	Description
`ego.vehicle_type`	str	`vehicle.mini.cooper`	CARLA blueprint ID for ego vehicle
`ego.initial_speed_kmh`	float	`0.0`	Initial speed of ego vehicle (km/h)
`ego.spawn_lanelet_id`	int	`242`	Lanelet ID for spawn position
`ego.spawn_s`	float	`25.0`	Longitudinal offset along lanelet centerline (meters)

Entity Configuration¶

Controls ground projection (ray casting) and spawn retry behavior:

Parameter	Type	Default	Description
`entity.ground_projection_ray_distance_upper`	float	`5.0`	Ray search range above estimated z (meters)
`entity.ground_projection_ray_distance_lower`	float	`10.0`	Ray search range below estimated z (meters)
`entity.spawn_retry_max_count`	int	`10`	Maximum retry attempts for spawn
`entity.spawn_retry_t_step`	float	`0.1`	Lateral offset shift per retry (meters)
`entity.spawn_retry_z_step`	float	`0.5`	Vertical shift per retry (meters)

Traffic Manager Configuration¶

Parameter	Type	Default	Description
`traffic_manager.port`	int	`8100`	CARLA Traffic Manager RPC port

Map Configuration¶

Parameter	Type	Default	Description
`map.name`	str	required	CARLA map name (e.g., `NishishinjukuMap`)
`map.source`	str \| null	`null`	Git repository holding the HD map (see maps.md)
`map.directory`	str \| null	`null`	Local map directory, read in place. Wins over `map.source`
`map.xodr_path`	str \| null	`null`	Path to custom OpenDRIVE file. If `null`, loads built-in CARLA map by name
`map.lanelet2_path`	str \| null	`null`	Path to Lanelet2 .osm file (required for lanelet-based spawn)
`map.no_3d_model_lanelet_ids`	list[int]	`[]`	Lanelet IDs to exclude from sweeps (no ground geometry)

Map paths can use environment variables with Hydra's OmegaConf resolver:

xodr_path: ${oc.env:NISHISHINJUKU_XODR_PATH,path/to/default.xodr}

Supported Scenarios¶

Intersection Passing¶

Tests ego vehicle traversal through an intersection. Verifies that the ego passes through the expected OpenDRIVE road sequence.

Config	Turn Direction	Description
`intersection_passing/straight`	none	Drive straight through intersection
`intersection_passing/left_turn`	left	Left turn at intersection
`intersection_passing/right_turn`	right	Right turn at intersection
`intersection_passing/straight_3npc`	none	Straight with 3 NPC vehicles

Scenario-specific parameters:

Parameter	Type	Default	Description
`scenario.expected_route_lanelet_ids`	list[int]	varies	Lanelet IDs the ego must traverse
`scenario.timeout_seconds`	float	`5.0`	Maximum scenario duration
`scenario.min_speed_kmh`	float \| null	null	Minimum ego speed (fail if below). `null` disables check
`scenario.speed_check_delay_seconds`	float	`0.3`	Grace period before speed check starts
`scenario.turn_direction`	str \| null	null	`"left"`, `"right"`, or `null` for straight
`scenario.npc_vehicles`	list	`[]`	NPC vehicle configurations (see below)

NPC vehicle configuration:

npc_vehicles:
  - spawn_lanelet_id: 100
    spawn_s: 5.0
    vehicle_type: vehicle.mini.cooper
    initial_speed_kmh: 10.0

Behavior: - Sets all traffic lights to GREEN - Registers a TurnAction for left/right turns (applies steering via CARLA autopilot route) - Pass condition: ego traverses all expected OpenDRIVE road IDs (checked via StickyCondition + AndCondition) - Fail conditions: timeout, ego destroyed, speed below threshold

Lane Change¶

Tests ego vehicle lane change maneuvers. Can test both successful lane changes and expected failures.

Config	Direction	Expected Result
`lane_change/left`	left	success
`lane_change/right`	right	success
`lane_change_fail/left`	left	fail (no adjacent lane)
`lane_change_fail/right`	right	fail (no adjacent lane)

Scenario-specific parameters:

Parameter	Type	Default	Description
`scenario.direction`	str	`"left"`	Lane change direction: `"left"` or `"right"`
`scenario.expect`	str	`"success"`	Expected outcome: `"success"` or `"fail"`
`scenario.timeout_seconds`	float	`10.0`	Maximum scenario duration

Behavior: - Sets all traffic lights to GREEN - Immediately registers a LaneChangeAction - Derives the target lane from the current spawn position and direction - Pass condition: expect=success requires both road_id and lane_id to change; expect=fail passes when timeout is reached without a lane change - Checks via EntityLanePositionCondition

Traffic Light Compliance¶

Tests that the ego vehicle correctly stops at a red light and proceeds after green.

Config
`traffic_light_compliance/traffic_light_compliance`

Scenario-specific parameters:

Parameter	Type	Default	Description
`scenario.light_switch_delay_seconds`	float	`5.0`	Delay before switching red to green
`scenario.merging_time_seconds`	float	`3.0`	Margin subtracted from red phase duration
`scenario.timeout_seconds`	float	`8.0`	Maximum scenario duration
`scenario.moving_speed_kmh`	float	`1.0`	Speed threshold to detect "moving" (km/h)

Behavior: - Sets all traffic lights to RED initially - Registers a TrafficSignalAction to switch to GREEN after light_switch_delay_seconds - Pass conditions: ego is at standstill during red AND moves above moving_speed_kmh during green - Uses StickyCondition + AndCondition for combined checks

Temporary Stop¶

Tests that the ego vehicle stops at a designated stop line for a minimum duration, then restarts.

Config
`temporary_stop/temporary_stop`

Scenario-specific parameters:

Parameter	Type	Default	Description
`scenario.s_margin`	float	`5.0`	Arc-length margin around stop position (meters)
`scenario.speed_threshold`	float	`0.1`	Max speed considered as "stopped" (m/s)
`scenario.stop_duration`	float	`0.3`	Minimum consecutive seconds to remain stopped
`scenario.restart_speed_kmh`	float	`3.0`	Speed threshold for restart detection (km/h)
`scenario.timeout_seconds`	float	`5.0`	Maximum scenario duration

Behavior: - Sets all traffic lights to GREEN - Registers a TemporaryStopCondition at the configured stop position - Pass condition: ego stays within s_margin of stop line at speed below speed_threshold for at least stop_duration seconds, then accelerates above restart_speed_kmh

Scenario Evaluation¶

Each scenario registers pass conditions and fail conditions. The tick loop evaluates them every frame:

First pass condition satisfied → scenario passes
First fail condition triggered → scenario fails
Common fail conditions: TimeoutCondition (exceeded time limit), EntityExistenceCondition (ego destroyed)

ODD and Coverage¶

Every run is measured against an ODD, named by the odd key (default unless overridden). Its attributes are sampled on every tick and written, with the scenario's own cover items, to {ScenarioName}_coverage.json. scenario-coverage outputs/ merges those files into a report. See ODD and Coverage.

uv run scenario scenario=intersection_passing/left_turn odd=path/to/urban.yaml
uv run scenario-coverage outputs/ --markdown coverage.md

Before running, scenario-odd route plans each scenario's ego route on the Lanelet2 map (no CARLA server) and reports which parts of it are outside the ODD, which are undecided until run time, the metres it is expected to cover in each bucket, and the buckets no route reaches (Checking a planned route):

uv run scenario-odd route path/to/urban.yaml 'intersection_passing/*' lane_change/left

Output Files¶

Each scenario run generates output in outputs/YYYY-MM-DD/HH-MM-SS/:

File	Description
`{ScenarioName}.log`	CARLA native recording (replay format)
`{ScenarioName}_result.json`	Machine-readable result with condition statuses
`{ScenarioName}_coverage.json`	ODD and scenario coverage hits of the run (merge with `scenario-coverage`, see Coverage)
`{ScenarioName}_odd.tar.gz`	The run's ODD as the files it was read from (an ODD read from OpenODD YAML; openodd's transmission archive, named by its revision; see Versions of an ODD)
`{ScenarioName}_requirements.lock`	What the run ran with: every installed distribution pinned, in the requirements format (`pip install -r`), headed by the framework, the scenario's package, Python and the platform. A distribution from git is pinned to its commit; an editable one (a checkout) names its directory, commit and whether it had uncommitted changes
`{ScenarioName}_environment.json`	The same, structured; `_result.json` carries its summary (`environment`: the framework, the scenario's package, key dependencies, and the lock's id -- the SHA-256 of what it pins -- so runs on one environment can be found by it)
`{ScenarioName}.mp4`	Rendered video from recording (optional, if spectator is configured)
`batch_results.json`	Batch summary (glob/batch mode only)

Result JSON format:

{
  "scenario": "intersection_passing/straight",
  "passed": true,
  "message": "All pass conditions satisfied",
  "elapsed_seconds": 3.42,
  "condition_statuses": [
    {"label": "Road 5 visited", "satisfied": true, "message": "..."},
    {"label": "Road 12 visited", "satisfied": true, "message": "..."}
  ]
}

Exit Codes¶

Code	Meaning
0	All scenarios passed
1	One or more scenarios failed, or configuration/runtime error

Driving the Ego with an External Policy¶

By default CARLA's TrafficManager drives the ego. To hand it to an external driving policy over the egodriver gRPC contract instead, start the policy server and select the carla_driver entity:

# 1. Start the policy (in its own environment)
uv run carla-driver-interface serve --policy route_follower --port 50051

# 2. Run any scenario against it
uv run scenario ego.entity=carla_driver driver.address=localhost:50051

ego.entity accepts:

Value	Behaviour
`autopilot` (default)	CARLA's TrafficManager drives the ego
`autoware`	Autoware drives the ego, over the `AutowareBridge`; with `autoware.launcher` the framework starts a fresh Autoware per scenario (Autoware as the Ego)
`carla_driver`	An external policy drives the ego

Common overrides:

# Query the policy every simulation tick instead of every other one
uv run scenario ego.entity=carla_driver driver.policy_timestep_s=0.05

# Pin the rig origin offset when the derived value looks wrong (CARLA 0.9.x)
uv run scenario ego.entity=carla_driver driver.rear_axle_offset_m=-1.4

# Send a smaller, cheaper camera frame
uv run scenario ego.entity=carla_driver \
    driver.cameras.0.image_width=480 driver.cameras.0.image_height=302

See External Driver Interface for the full reference.

`detect-no-3d-model` - 3D Model Detection¶

Detects lanelets that do not have a matching 3D ground model in CARLA. Useful for identifying areas where vehicle ground-projection ray casting will fail. Requires a running CARLA server with the target map loaded.

How It Works¶

Reads the map configuration YAML to resolve xodr_path and lanelet2_path
Connects to the CARLA server
For each lanelet's center point, casts a vertical ray (upward and downward from estimated z) to detect ground geometry
Reports lanelets where the ray does not hit any 3D surface
Writes the detected IDs to the YAML configuration's no_3d_model_lanelet_ids field

Usage¶

# Basic detection using map config YAML
uv run detect-no-3d-model conf/map/nishishinjuku.yaml

# Connect to a remote CARLA server
uv run detect-no-3d-model conf/map/nishishinjuku.yaml --host 192.168.1.100 --port 3000

# Increase ray search range for hilly terrain
uv run detect-no-3d-model conf/map/nishishinjuku.yaml --ray-upper 10.0 --ray-lower 10.0

# Longer timeout for slow connections
uv run detect-no-3d-model conf/map/nishishinjuku.yaml --timeout 30.0

# Debug logging
uv run detect-no-3d-model conf/map/nishishinjuku.yaml -v

Command-Line Options¶

Option	Short	Required	Default	Description
`yaml_path`	-	Yes	-	Path to map configuration YAML (must contain `map.name`, `xodr_path`, `lanelet2_path`)
`--host`	-	No	`localhost`	CARLA server hostname
`--port`	-	No	`2000`	CARLA server port
`--ray-upper`	-	No	`5.0`	Ray search range above z estimate (meters)
`--ray-lower`	-	No	`5.0`	Ray search range below z estimate (meters)
`--timeout`	-	No	`10.0`	CARLA client timeout (seconds)
`--verbose`	`-v`	No	false	Enable DEBUG logging

Input YAML Requirements¶

The YAML file must contain at minimum:

name: NishishinjukuMap        # CARLA map name
xodr_path: path/to/map.xodr  # Path to OpenDRIVE file
lanelet2_path: path/to/map.osm  # Path to Lanelet2 file

Integration with Scenario Runner¶

The detected lanelet IDs are stored in the map config's no_3d_model_lanelet_ids field. The scenario runner's sweep feature uses this list to exclude problematic lanelets from automatic spawn point selection.

`viewer` - Scenario Result Viewer¶

Web UI for browsing and monitoring scenario test results. Starts a FastAPI server with Uvicorn.

How It Works¶

Scans the base path directory for scenario output files (outputs/YYYY-MM-DD/HH-MM-SS/)
Serves a web interface for browsing sessions, viewing individual scenario results, and watching recorded videos
Provides an API for triggering scenario runs and monitoring progress in real time

Usage¶

# Start with default settings (0.0.0.0:9000, current directory)
uv run viewer

# Custom host and port
VIEWER_HOST=127.0.0.1 VIEWER_PORT=8080 uv run viewer

# Specify results directory
VIEWER_BASE_PATH=/path/to/scenario/outputs uv run viewer

Then open http://localhost:9000 (or the configured host/port) in a browser.

Environment Variables¶

Variable	Default	Description
`VIEWER_BASE_PATH`	Current working directory	Base path for scanning scenario result files
`VIEWER_HOST`	`0.0.0.0`	Server bind address
`VIEWER_PORT`	`9000`	Server listen port

Web UI Pages¶

Route	Description
`/`	Session list — displays all test sessions grouped by date/time
`/session/{type}/{date}/{time}`	Session detail — shows all scenarios in a session with pass/fail status
`/session/{type}/{date}/{time}/{index}`	Scenario detail — condition tree, per-condition status, and video playback
`/video/{type}/{date}/{time}/{index}/{filename}`	Video file serving for MP4 playback

REST API Endpoints¶

The viewer also provides API endpoints for programmatic use and the web UI's interactive features:

Method	Endpoint	Description
`POST`	`/api/refresh`	Clear result cache and return updated session table HTML
`GET`	`/api/scenarios`	List all available scenario config names
`POST`	`/api/run/preview`	Preview the CLI command that would be executed
`POST`	`/api/run`	Start a scenario execution in the background
`GET`	`/api/run/status`	Get current run status (non-streaming)
`GET`	`/api/run/progress`	SSE (Server-Sent Events) stream for real-time progress

Run request body format:

{
  "scenario": "*/*",
  "extra_overrides": ["server.host=192.168.1.100"],
  "sweeper": ""
}

Progress SSE event format:

{
  "current": 2,
  "total": 5,
  "scenario_name": "intersection_passing/straight",
  "status": "running"
}

Where status is one of: "running", "idle", or "done".

Environment Variables¶

Variable	Used By	Description
`CARLA_EXECUTABLE`	scenario runner	Path to CARLA's launcher (`CarlaUnreal.sh`); defaults to the one `scenario-setup` installed
`AUTOWARE_CARLA_SCENARIO_HOME`	`scenario-setup`, scenario runner	Moves `~/.autoware_carla_scenario` (CARLA lives in `bin/carla`)
`NISHISHINJUKU_XODR_PATH`	map config	Override default OpenDRIVE file path for nishishinjuku
`NISHISHINJUKU_LANELET2_PATH`	map config	Override default Lanelet2 file path for nishishinjuku
`VIEWER_BASE_PATH`	viewer	Base path for scenario results
`VIEWER_HOST`	viewer	Viewer server bind address
`VIEWER_PORT`	viewer	Viewer server listen port
`SCENARIO_EDITOR_DRAFTS`	scenario editor	Directory holding scenario drafts
`SCENARIO_EDITOR_EXPORT_DIR`	scenario editor	Staging area for exported package archives
`SCENARIO_EDITOR_MAP_ROOTS`	scenario editor	Directories a Lanelet2 map may be served from
`SCENARIO_EDITOR_HOST`	scenario editor	Editor server bind address
`SCENARIO_EDITOR_PORT`	scenario editor	Editor server listen port
`SCENARIO_EDITOR_MAP_VIEWER`	scenario editor	URL of a self-hosted `simple_lanelet2` map viewer
`SCENARIO_EXPORT_FRAMEWORK_VERSION`	package export	Pin exported packages to a published framework release
`SCENARIO_EXPORT_FRAMEWORK_REPOSITORY`	package export	Repository URL recorded for a commit pin

Common Use Cases¶

Use Case 1: Run a Single Scenario¶

# Start CARLA server first, then:
uv run scenario scenario=intersection_passing/straight

Use Case 2: Run All Scenarios for a Map¶

uv run scenario scenario='*/*' map=nishishinjuku

Use Case 3: Test on a Remote CARLA Server¶

uv run scenario scenario=intersection_passing/left_turn \
  server.host=192.168.1.100 server.port=2000

Use Case 4: Detect Missing 3D Models Before Running Scenarios¶

# 1. Detect lanelets without ground geometry
uv run detect-no-3d-model conf/map/nishishinjuku.yaml

# 2. The detected IDs are written to no_3d_model_lanelet_ids in the YAML
# 3. Now run scenarios — sweep will skip these lanelets
uv run scenario scenario='intersection_passing/*' map=nishishinjuku

Use Case 5: Browse Results in the Web UI¶

# 1. Run scenarios
uv run scenario scenario='*/*'

# 2. Launch the viewer pointing to the outputs directory
VIEWER_BASE_PATH=outputs uv run viewer

# 3. Open http://localhost:9000 in a browser

Use Case 6: Resume a Failed Batch¶

# Original batch run (5 scenarios, failed at the 4th)
uv run scenario scenario='intersection_passing/*'

# Resume from the 4th scenario
uv run scenario scenario='intersection_passing/*' --resume-from 4

Troubleshooting¶

"Connection refused" or timeout when connecting to CARLA¶

Cause: CARLA server is not running, or host/port is incorrect.

Solution: - Verify the CARLA server is started and accessible - Check server.host and server.port overrides match the server - Increase --timeout for detect-no-3d-model

Cause: Glob pattern matched scenarios configured for different maps.

Solution: - Use map=<name> override to force all scenarios to use the same map - Or narrow the glob pattern to match scenarios for one map only

Ego vehicle falls through the ground¶

Cause: The spawn lanelet has no corresponding 3D ground geometry in CARLA.

Solution: - Run detect-no-3d-model to identify problematic lanelets - Add them to no_3d_model_lanelet_ids in the map config - Increase entity.ground_projection_ray_distance_lower for deeper ray casting - Increase entity.spawn_retry_max_count for more spawn attempts

Scenario times out unexpectedly¶

Cause: scenario.timeout_seconds is too short, or the ego vehicle is stuck.

Solution: - Increase scenario.timeout_seconds - Check ego.initial_speed_kmh — a value of 0.0 requires autopilot to start moving - Enable verbose logging and check condition statuses in the result JSON

"Unknown scenario name" error¶

Cause: The scenario.name field in the YAML does not match any registered scenario class.

Solution: - Supported scenario names: intersection_passing, lane_change, traffic_light_compliance, temporary_stop - Check the name field in your scenario YAML config

Next Steps¶

API Reference — Detailed API documentation for programmatic usage
Development Guide — Contributing and development setup

Usage Guide¶

CLI Commands Overview¶

scenario - Scenario Runner¶

How It Works¶

Basic Usage¶

Batch Execution with Glob Patterns¶

Running every sweep case in a batch¶

Selecting a Published HD Map¶

Lanelet Constraint Sweeping¶

Resume from a Specific Scenario¶

Overriding Configuration Parameters¶

Hydra Configuration System¶

Root Configuration (config.yaml)¶

Server Configuration¶

Ego Vehicle Configuration¶

Entity Configuration¶

Traffic Manager Configuration¶

Map Configuration¶

Supported Scenarios¶

Intersection Passing¶

Lane Change¶

Traffic Light Compliance¶

Temporary Stop¶

Scenario Evaluation¶

ODD and Coverage¶

Output Files¶

Exit Codes¶

Driving the Ego with an External Policy¶

detect-no-3d-model - 3D Model Detection¶

How It Works¶

Usage¶

Command-Line Options¶

Input YAML Requirements¶

Integration with Scenario Runner¶

viewer - Scenario Result Viewer¶

How It Works¶

Usage¶

Environment Variables¶

Web UI Pages¶

REST API Endpoints¶

Environment Variables¶

Common Use Cases¶

Use Case 1: Run a Single Scenario¶

Use Case 2: Run All Scenarios for a Map¶

Use Case 3: Test on a Remote CARLA Server¶

Use Case 4: Detect Missing 3D Models Before Running Scenarios¶

Use Case 5: Browse Results in the Web UI¶

Use Case 6: Resume a Failed Batch¶

Troubleshooting¶

"Connection refused" or timeout when connecting to CARLA¶

"batch scenarios must share the same map"¶

Ego vehicle falls through the ground¶

Scenario times out unexpectedly¶

"Unknown scenario name" error¶

Next Steps¶

`scenario` - Scenario Runner¶

Root Configuration (`config.yaml`)¶

`detect-no-3d-model` - 3D Model Detection¶

`viewer` - Scenario Result Viewer¶