Skip to content

Scenario Editor

The Scenario Editor is a web UI for authoring scenarios declaratively and exporting them as self-contained wheelhouses. It runs as its own application:

uv run scenario-editor          # http://localhost:9100
uv run scenario-editor --help   # its options (Configuration below)

It is deliberately separate from the Scenario Result Viewer (uv run viewer). Neither mounts the other, and running one does not start the other; integrating the two is a later phase.

What it edits

The editor never edits Python. Its canonical representation is the Scenario IR -- a ScenarioDocument stored as YAML -- which the framework compiles into the existing runtime primitives:

ScenarioDocument -> ScenarioCompiler -> BaseAction / BaseCondition -> BaseScenario

There is no editor-only runtime. Every action a document names is built by autoware_carla_scenario.actions, every condition by autoware_carla_scenario.conditions, and every spawn constraint is evaluated by the same sweeper.constraints engine a --multirun sweep uses.

An entity is of one of four kinds, picked when it is added (+ Actor): the ego, a vehicle, a motorcycle or a pedestrian. A motorcycle is spawned as a MotorcycleEntity, by default on whichever motorcycle the running CARLA has (vehicle_type: auto), and its track offers every action a vehicle's does; the traffic backends drive it as a motorcycle (docs/traffic_backends.md).

Which map: the Map library

A scenario's map is named by a source URI pointing at a git repository, and the editor fetches and caches it. Map library in the header browses a repository -- HuggingFace, GitHub, your own -- and lists every map in it; the Scenario inspector shows, per scenario, whether the map is downloaded and whether its revision is pinned.

See HD Maps from a Git Repository. Two things are worth knowing here: a map Autoware's own setup already downloaded is used as it sits, and OpenDRIVE is not needed to author a scenario -- lanelets are.

A scenario on a map from the library (or a Map directory) is exported with a map group of its own, conf/map/<id>_map.yaml in the package, and run with map=<id>_map -- see Running an authored scenario.

Where it happens: the places panel

One map carries every lanelet the scenario names -- each entity's spawn, the ego's goal, and the lanelet every condition watches. The canvas says what happens and in what order; it has no way to say where, and until this panel existed the answer was a scatter of ids across lane heads and condition cards that only meant something with the map open in another window.

It sits at the top of the right-hand rail, over the inspector:

+------------------------------------------+---------------------------+
| Arrangement (the timeline, full width)    | Places      < 1/133 >     |
| ACTOR | Init | 1  | 2  | 3  | 4  | 5      |   (o) NPC1 spawn BOUND    |
| Ego   |      | [] |    |    |    |        |   (o) Ego goal            |
| NPC1  |      | [] | [] |    |    |        |   (o) Ego spawn           |
| Env   |      |    | [] |    |    |        | [Ego spawn][Ego goal][..] |
| PASS  | ...                               +---------------------------+
| FAIL  | ...                               | Inspector                 |
+------------------------------------------+---------------------------+

Three things had to be true at once -- the map, the timeline and the inspector all on screen without scrolling -- and this is the arrangement that gets there without taking width from the thing that needs it. The timeline's axis is width: a card further right is later in the story, so narrowing it costs steps you can see. The map is roughly square and the inspector is a column, so both fit the rail; and "where" then sits directly over "what", which is what makes clicking a place and reading its object one movement of the eye.

The whole editor is one CSS grid (.ed-stage) for that reason. #editor-body stays the single htmx swap target and simply does not draw a box -- display: contents lifts the timeline and the inspector into that grid -- so the map can sit beside either of them while every edit still re-renders one element. Moving the panel is a change to one block of editor.css, not to a template.

Which glyph a place gets is the field's own declaration, not a guess from whatever holds it: FieldSpec.place is spawn, goal or watched, so the Set Goal action's lanelet draws as a destination exactly as the ego's own goal does. A primitive that registers a new lanelet field is drawn without the map learning anything about it.

Each place is a pin in its actor's track colour -- the same hue that actor's lane head and every condition naming it already wear -- with a glyph for what the place is: a target for a spawn, a flag for a goal, an eye for a lanelet something watches. The viewer has one highlight channel, so the outline says "this scenario touches here" and the pins say which of them is which.

Under the map the same places are chips, in document order. Clicking one opens the object that named it in the inspector and points the map at it; clicking a place on the map does the same, because the overview draws places the document already names and the only thing a click there can mean is "show me what named this". Nothing is edited here -- a lanelet is still set where it is written, in the picker its own field opens.

A label reads away from its dot, except on the right half of the map, where it reads back towards the middle: that edge is also where the viewer keeps its own zoom buttons, and a label running under them is a label nobody can read.

Areas: ground chosen by what it is

A Distance to an area card (area_distance, EntityAreaDistanceCondition) measures from an entity's body to an area. The area is not drawn by hand. It is chosen by what the ground is:

Field What it chooses
Ground Lanelets by subtype (crosswalks, walkways, road shoulders, roads), the lanes through a junction (tagged turn_direction), any lanelet, polygons of the map's polygon layer by type (Autoware's intersection, detection, no-stopping and no-parking areas, parking lots, any polygon), or the raised or grooved parts of the roads' surface, from the OpenDRIVE map's OpenCRG grids
Only these lanelets Narrows lanelet ground to lanelets picked on the map, which must each be of the ground. Not for polygons
Attributes key=value tags every element must have, apart by commas: turn_direction=left, location=urban. A bare key asks only that the tag is there. Not for the road surface
Surface counts from For the road surface: how far above or below its design the surface has to stand to count. Empty: 0.01 m

The places panel outlines an area whole rather than pinning it: every lanelet it matches is outlined, and it is listed under the places with how many lanelets that is. A pin per crosswalk of a city would bury the places above. The viewer outlines lanelets only, so polygons of the polygon layer are counted and not drawn, and so are the raised and grooved parts of the road surface. Those come from the OpenDRIVE map, not the Lanelet2 one. They are counted on every render, without parsing the Lanelet2 map, and any OpenCRG grid that cannot be read is listed under the row. The match uses the framework's own matcher (conditions.map_area.area_shapes), so the outline is the ground the run measures to. Matching waits on the map being parsed, like binding a search pattern: Outline areas asks for it.

Some mistakes only the map can show: a picked lanelet of another ground or missing from the map, or a ground the map has none of (a parking lot on a map with none). The panel says so on the area's row. The validator cannot see the map and accepts such a card. The run then says it once as a warning, and the condition never holds, with the problem in its details. The validator does refuse what no map could hold: picked lanelets for a ground of polygons, and an attribute written without its key or value.

The run's result keeps the closest the entity came (closest_m, closest_at_s, and which lanelet or polygon it was nearest) in the card's details, whether or not the card fired.

An abstract scenario draws one bound pattern

A scenario whose lanelet is a constraint search does not name a place: it names a set, and the sweeper runs it once per member. Outlining all 133 matches draws the search, and none of those 133 runs looks like that picture. So one match is bound -- through the same swept_slot the exported config sweeps and the same constraint engine the sweep evaluates -- and the panel says which of how many is on screen. The arrows step through the runs a --multirun sweep would perform, one concrete scenario at a time.

A spawn whose s is derived from the map (a stop_line_offset, say) is placed by that binding, resolved for the bound match by the sweeper's own code: a match too short for the offset walks the spawn back onto a predecessor, and the pin goes there with the offset the run gets. A match the binding fails on is one the sweep drops, so the panel says so rather than drawing a run that never happens (#1524). The arrows step through the matches: when the swept spawn itself walks back, two matches can walk back to the same place, and the sweep runs that case once (#1950).

Everything else keeps the id stored beside it, because that is exactly what a run that does not sweep uses: the sweeper enumerates a single target key, so at most one lanelet in a document is ever bound.

Binding means parsing the map on the server, which is measured in seconds, so it is a button (Bind a pattern) rather than something every page load pays for. Once the map is cached every later render binds without being asked, including the panel's own refresh after an edit.

Where a pin goes

The labels are the server's -- rendered with the panel, beside the list that repeats them -- and only the coordinates are the viewer's. editor.js asks it through its public API: focusOn(id) centres the view on a primitive, so focusing one and reading getView() back reports that lanelet's centre in the map's own coordinates, and the view is then put back where it was. The alternative was projecting the .osm a second time in JavaScript, which is a second answer to "where is this" that can disagree with the drawing it is laid over. Each lanelet is measured once and kept on the frame, which is the frame reuseMap() parks across a re-render, so an edit re-places the pins without asking the map anything.

The panel frames itself on the places rather than on the whole city when the map loads, and a pan or zoom after that is the person's: a re-render carries it across, exactly as the picker's does. Tilted into the viewer's 3D view the pins hide themselves, because getView() then reports drawing coordinates and a point on a hill and the ground behind it are drawn in the same place.

This is a second parse of the same .osm while a picker is open, which is the cost the inspector's own map was removed to avoid. It is a different drawing rather than the same one twice: the picker answers "which lanelet is this field", and the overview answers "where is this scenario" -- a question nothing else on the page answers at all.

The canvas

The main view is a swimlane DAG drawn as a DAW arrangement: one track per actor, with the horizontal axis reading as scenario progression, not time. Under the actors sits the Environment track, for actions no vehicle performs.

STEP >      | 1          | 2                 | 3
------------+------------+-------------------+------------------
Ego         | Drive      |                   |
------------+------------+-------------------+------------------
NPC1        | Follow     |                   | # Lane Change Left
            |            |                   |         ^
            |            |                   |   +-----+-----+
            |            |                   |   |    ALL    |
            |            |                   |  NPC1->Ego  NPC1->Ego
            |            |                   |  Distance   TTC
            |            |                   |  < 20 m     < 4 s
------------+------------+-------------------+------------------
Environment |            | Set Traffic Signal|
------------+------------+-------------------+------------------
PASS        | NPC1 enters the ego lane
FAIL        | Collision  | Timeout 30 s

Which track an action belongs to

The action type decides, never the author. ActionSpec.scope is either actor or environment, and an environment action -- setting traffic lights, for instance -- is drawn in the Environment track whatever its actor field says. Nothing reads that field when such an action is built, so honouring it put the card in some vehicle's lane and claimed a relationship the run does not have. The editor no longer offers the field for one, refuses it on the way in, and drops a stale value on the next save; each track's + action menu offers only the actions that belong in it.

Which entities may perform an actor action is the type's too (ActionSpec.actor_kinds): a track's + action menu offers only the actions its entity's kind may perform, the inspector's Actor picker lists only the entities of those kinds, and the validator refuses any other actor -- on a card that may leave its actor out (Spawn, Despawn) as on one that needs it. So neither a Spawn nor a Despawn card takes the ego: it is in the scene from the start and stays there.

The Environment track is drawn even when it is empty, because it is where you go to add the first one. An action that merely has no actor yet is drawn there too: it is invalid, and a card nothing draws cannot be corrected.

The sequencer furniture is what makes the direction readable: track headers down the left, a numbered ruler across the top, a bar line before every slot and every other slot shaded. The ruler counts steps and not seconds, which is the whole reason it is a step ruler -- see the first rule below.

What a step is

Nothing in Python has a "step". The runtime arms every action from the first tick and ticks them all every frame:

for action in scenario._pre_tick_actions:
    action.tick(world, elapsed)

An action fires when its own trigger says so, not when its column comes up, and an action with no trigger gets AlwaysTrueCondition -- so it fires on tick 1 however far right it is drawn. column_hint is read by nothing outside this editor: compiler.py, declarative.py and the exporters contain no reference to ui at all.

So a step is not a point in time. It is a set of actions nothing orders, and the canvas draws it that way:

  • Several actions can share one step, stacked in the same column. That is the honest picture of two actions that are both armed and neither waiting on the other -- spreading them across two columns would draw a sequence the runtime does not have.
  • An action may not share a step with anything its trigger waits on. Within a step nothing is ordered, so a dependency has to be visibly earlier. Adding an action_state trigger pushes the dependent right on the spot, moving a dependency right carries its dependents with it, and a move that would break the rule is repaired rather than refused -- the card lands as close to where it was aimed as its dependencies allow. validator.py reports a hand-edited ui block that says otherwise.

That makes the step axis mean exactly one thing: left of is "already finished, and something here is waiting on it". It still says nothing about how much earlier.

A step number means the same column on every lane, so there is no leading column an actor track has and the Environment or verdict lanes do not. A spawn is not a step -- it is the state a track starts in -- so it is stated in the lane head rather than given a slot on the ruler.

An action with no trigger fires on the first tick, wherever it is drawn. BaseAction defaults to AlwaysTrueCondition, so a card in step 5 with an empty trigger runs immediately and its position is simply wrong about it. The canvas writes "fires immediately" under the card, and the validator warns -- never errors, because a position is presentation.

Three rules make it readable:

  • The distance between cards means nothing. Column position is ui.column_hint, which is presentation only and never reaches the runtime. A clip in step 3 may only start after one in step 2 if something says so; how much later is not on screen because the document does not know.
  • There is no separate event lane. A condition is a trigger, drawn under the action it fires and joined to it by a solid line, so cause and effect are next to each other instead of being correlated across the screen. A Set Goal card can also hold conditions on its waypoints -- waypoint conditions, edited in its inspector with the same condition controls.
  • Two cards may not steer one entity at once. A card that commands an entity's speed, steering or lights takes that control domain while it runs, and a second card firing on the same domain ends the run in error. Tick Override a running action in the second card's inspector to have it stop the first instead (the canvas marks it overrides; overrides: true in the document). Cards that command no entity do not offer it.
  • A card fires once unless told otherwise. Untick Fire only once to have it fire again each time its trigger holds (once: false in the document). Cards whose action cannot fire again (Stalled Object, Construction Zone, Urban Construction Zone, Adversarial Traffic (NADE)) do not offer it, and the validator refuses once: false on them.
  • One actor reacting to another is a reference, not a coincidence. "Swerve once NPC1 has cut in" is a Lane Change clip on the ego track whose trigger is an Action state condition naming NPC1's cut-in and the state completeState. That reference lives in the document (params: {action: a_..., state: completeState}), so it is a fact the scenario contains rather than something the canvas infers.

The canvas draws that reference as a dashed line in the causing actor's track colour, running from the action to the condition waiting on it. The cut-in example reads as one chain across two tracks:

NPC1   ... [Cut in] ......
                     :         <- dashed: Cut in -> the condition waiting on it
Ego    ..............:...  [Evade right]
                          ^ Cut in · NPC1 | Action | completeState
                            solid: fires this action

Both line types are named in the legend above the canvas, because a dash pattern is not self-explanatory. Crucially the dashed line is drawn only from data-caused-by, the document's own reference -- never from where two cards happen to sit. Moving a clip can therefore neither invent a causal link nor erase one, and a condition that names no action (a distance check, say) is never drawn as caused by anything.

Action states

The states are ASAM OpenSCENARIO 1.2's StoryboardElementState, applied to a single action:

State Meaning
standbyState Instantiated, waiting for its start trigger
startTransition The trigger fired and execute() ran -- held for one tick
runningState The work is under way -- only for an action that runs on (below)
endTransition The completion criteria were met -- held for one tick, only for an action that runs on (below)
completeState Finished (a repeating action returns to standbyState)

completeState is the one that makes "after the cut-in" verifiable. A forced lane change stays in runningState until the vehicle has actually settled onto the next lane -- a different lane id, within LANE_CHANGE_CENTER_TOLERANCE_M of its centre and LANE_CHANGE_HEADING_TOLERANCE_DEG of its heading. A lane id change alone is not enough: a car whose centre has just crossed the boundary is still diagonal, and a reaction triggered on that would fire mid-manoeuvre.

There is deliberately no failure state and no action-level timeout, because OpenSCENARIO has neither. A manoeuvre that never happens stays in runningState forever, so completeState cannot be reached by a lane change that did not occur; ending such a run is the scenario timeout's job, which is already a FAIL condition. The two transition states are each held for exactly one tick, so a condition watching startTransition sees it.

runningState and endTransition are only reached by an action that runs on: one whose completion criteria the world takes time to meet (a lane change settling, a trajectory being followed), or one that re-sends its command every tick. An action with neither -- a traffic light set, say -- is over the moment it is commanded: on the tick after startTransition it goes straight to completeState (back to standbyState when it repeats), so waiting on Running or End for it never holds. Wait on Complete instead (architecture, "Action lifecycle").

Which is also why a card can be moved into an empty step rather than only swapped with its neighbour: a reaction has to be placeable to the right of the cause on another track, and its own track is usually empty in between.

Every condition reads as subject -> target | metric | rule value, e.g. NPC1 -> Ego | Distance | < 20 m or Ego -> Lanelet 183 | Position | inside.

A target that is not an actor is named for the coordinate system it is in. This framework speaks both Lanelet2 and OpenDRIVE and their ids are written the same way, so Ego -> 183 would say nothing about which 183 is meant.

Position: pick a frame, not a mixture

There are two position conditions, one per coordinate system, because the two need different fields:

Address Reads as
Position (Lanelet2) a lanelet NPC1 -> Lanelet 183 \| Position \| inside
Position (OpenDRIVE) a road, optionally a lane NPC1 -> Road 80 \| Position \| lane 2 \| inside

Either can be narrowed to a stretch of that lane with s from / s to and t from / t to. The runtime has always accepted these comparisons; the editor used to discard them. They are the abstract way to say "in the last 20 m before the junction": unlike an absolute region, s and t are measured along and across the lane, so the condition keeps its meaning wherever a constraint sweep puts the entity.

A lanelet already names one lane, so the Lanelet2 condition resolves it to an OpenDRIVE road and lane and there is nothing further to pin. An OpenDRIVE road does not: a road carries several lanes, so road and lane together are what address a place uniquely, and a road left without a lane says so on the card (any lane) rather than looking like a precise address.

Lanelet2 ids are picked, never typed

Every field naming a Lanelet2 lanelet is edited only on the map. The number beside it is a readout, not an input: nobody knows lanelet ids by heart, so typing one is guesswork the map answers exactly, and making the map the single editor leaves one path a value can arrive by instead of two to keep in step. Edit opens the viewer over the whole window -- the inspector column is 384px wide, and a city map that size cannot be picked from -- and clicking a lanelet fills the field and closes it. This comes from the field's declared kind (lanelet), so any field naming a lanelet gets the picker without touching a template.

There is no "type it instead" fallback for a viewer that will not load, for the same reason the SVG map fallback was removed: the page fetches htmx from a CDN too, so an editor that cannot reach the network has no working controls at all.

Three fields still take typed ids, each because their value is not only a lanelet id, and a test in test_authoring_registry.py fails if a new one appears without being listed there with its reason:

Field Why it is not picked
equals.value (spawn constraint) any matches every lanelet -- a sentinel the sweeper parses, not an id
in_set.values (spawn constraint) accepts ${map.no_3d_model_lanelet_ids}, a reference resolved at sweep time
traffic_signal regulatory element ids the viewer's regulatory layer reports the id of the linestring that draws a sign, not of the regulatory element -- a picker there would save a confidently wrong number

Two implementation notes, both of which cost an afternoon to find:

  • The picker is moved to <body> before it is shown. The inspector sits inside a position: sticky wrapper, and sticky creates a stacking context whatever its own z-index is -- so a z-index left in place ranks only against its siblings, and the canvas lanes (z-index: 2) paint straight over a modal asking for 80.
  • A set of lanelets works the same way, toggling on each click, and saves when the picker is closed -- sending the form on every toggle would re-render the inspector and tear the map down mid-selection.
  • Which viewer layers a click may land on is the editor's LANELET_PICK_LAYERS (editor/app.py): the renderer's layer names, not part of a field's declaration. The layers overlap: a click on a road usually lands on the direction arrow, and a hair to the side lands on a bound, which reports the id of a linestring, not of either lanelet it separates. Only the layers whose id is the lanelet's own are accepted.
  • /static is served with Cache-Control: no-cache. StaticFiles sends an ETag but no Cache-Control, which lets a browser invent a freshness lifetime and keep running an old editor.js without asking -- an editor visibly missing a feature the server is already serving. The ETag still makes the check a 304.

They are separate conditions rather than one with a coordinate-system switch because offering a lanelet and a lane on the same condition is what let the two contradict each other: on the nishishinjuku map lanelets 183 and 184 are lanes 2 and 1 of road 80, so pinning lanelet 183 and lane 1 asked for a place that does not exist. Compose them with ALL, ANY, NOT, Sticky and Persistent, which map onto AndCondition, OrCondition, NotCondition, StickyCondition and PersistentCondition. The validator warns on a Persistent card whose child is a Collision, Off the road, Exists or Timeout card: those only ever report a failure, and Persistent counts only the ticks its child passes, so it would never fire. Use a Collision or Timeout on its own: it keeps its failure once it has fired, so under a NOT it would only fail the run later. Put Off the road or Exists, which check again on every tick, under a NOT first.

Fixed or searched: every lanelet, one question

Edit on any lanelet field opens the map, and the panel beside it asks the same thing wherever you opened it from — Fixed or Constraint search:

Where a lanelet is named Slot Hydra key a sweep writes
An entity's spawn ego.spawn, npc1.spawn ego.spawn_lanelet_id, scenario.spawn_overrides.npc1.lanelet_id
The ego's goal ego.goal ego.goal_lanelet_id
A lanelet parameter of an action or a condition <node id>.<field> scenario.param_overrides.<node id>.<field>

Because a node id is part of these keys -- and a run looks the node a param_overrides entry names up among the actions first, then the conditions -- the validator refuses an action or condition id that is not lower_snake_case starting with a letter (npc.in_lane would split the Hydra key), and one used by two nodes, an action and a condition included. The ids the editor makes (a_1f2e3d4c, p_5b6a7988) always pass; only a hand-edited document can trip it, and it still opens, with the errors shown.

A constraint is a statement about the map, so it is written with the map it searches in view, and the matches are outlined on that same map as they are counted. That is why the choice is in the picker and not in the 384px inspector column, which only states which mode is in force and offers Edit.

A set of lanelets — stop_lanelets, the map's exclusion list — is picked by hand and gets no such panel: a search names one lanelet per run, because that is what the sweeper enumerates, so offering the choice there would promise that a search fills the whole set.

Fixed pins the lanelet the field shows. For a spawn that is a lanelet and an offset:

Field Value Where
Lanelet ID 183 the picker, by clicking the map
Offset 12.5 m the picker, under the same heading

Constraint search hands the choice to the existing lanelet-constraint sweeper. The tree is edited in the picker, each node with its own parameters — the inspector column is behind the map while it is open — with the match count beside it outlining what it found on that same map, and is serialised straight into sweep.constraints under whichever key addresses the slot:

sweep:
  constraints:
    ego.spawn_lanelet_id:
      - type: and
        constraints:
          - type: has_adjacent
            value: left
          - type: lanelet_length
            rule: greater_than_or_equal
            value: 10.0
          - type: not
            constraint: {type: is_junction}
          - type: not
            constraint:
              type: in_set
              values: ${map.no_3d_model_lanelet_ids}

The id the field shows stays in the document under a search: it is the default a run that does not sweep falls back to, and the value the exported config declares so that Hydra's struct mode accepts the override at all.

Excluded lanelet IDs (Scenario inspector) is what ${map.no_3d_model_lanelet_ids} means for this scenario. Left empty, it inherits the map group's own list (conf/map/nishishinjuku.yaml's, for the starter), resolved by Hydra at run time. A list typed there replaces the group's. On a built-in group the map keys a scenario config writes lose to the group, composed after the scenario, so the export writes such a list in place of every reference instead -- values: [1, 2] where the document says ${map.no_3d_model_lanelet_ids} -- and a map.no_3d_model_lanelet_ids=... override on the command line no longer reaches those constraints. A scenario on its own map group (a source or a Map directory, below) writes its list, empty or not, into that group. The match count below follows the same rule, reading the built-in group's list from its file when the field is empty, so it counts what the sweep will enumerate.

One search per run. The sweeper enumerates a single target key, so a document may search for one lanelet; a second search is a validation warning rather than an error — the scenario still runs, with everything else pinned to its default — and names which slot is being driven.

Preview matches evaluates that tree against the real Lanelet2 map and reports, for example, 121 matched of 979 lanelets. It is counted when the picker is opened, not on every render: each lanelet field on the inspector has a picker in the page at once, and counting means parsing a city. Loading a map is opt-in and cached; if the map files are missing the count is unavailable but the constraint editor keeps working.

The map

The drawing comes from simple_lanelet2's wasm map viewer — the same project that provides the lanelet2 Python API this framework runs on. The editor serves the scenario's .osm at /draft/<id>/map.osm, the viewer parses and renders it in the browser, and the editor drives it through two calls: setHighlight() with the matched IDs, and a select listener that turns clicking a lanelet into setting whichever lanelet field the picker was opened from.

Constraint evaluation stays on the server, in the framework's own sweeper — the viewer only draws. That split is deliberate: a second constraint engine in JavaScript could disagree with the sweep the scenario will actually run.

The module is loaded from the project's GitHub Pages build, because the wasm is built rather than committed. Point SCENARIO_EDITOR_MAP_VIEWER at the output of simple_lanelet2's tools/build_web.sh to serve it yourself. When it cannot be fetched the panel says so; the match count and the matched-ID list come from the server and are unaffected.

The map is parsed once

htmx replaces the whole inspector on every edit, so the server sends a brand-new, empty map frame each time. Mounting that frame refetched the .osm and parsed it again in wasm — one fetch per edit, for a map that had not changed.

The frame that already holds the parsed scene carries a data-viewer-key, and reuseMap() in editor.js swaps it back in over the fresh one, copying across only what actually differs: which lanelets are outlined. The whole frame moves rather than the canvas inside it — the viewer keeps a reference to the element it was constructed with and observes it for resizes, so lifting the canvas out would leave it measuring a node that is no longer on the page. Panning and zooming survive an edit as a consequence, which re-mounting had been silently throwing away.

That is what makes the picker editable. An edit in its side panel — the fixed or searched choice, the constraints, a spawn's offset along the lanelet — posts like every other control and swaps the whole editor body, which builds a fresh copy of the modal while the open one hangs off <body>. The fresh copy is swapped in behind the person using it, and the key carries the parsed map across, pan and zoom included.

It is the only renderer. A server-rendered SVG used to sit behind it as an offline fallback, but the page loads htmx from a CDN and every control here is an hx- attribute, so an editor that cannot reach the network does not work at all — the fallback bought no offline capability while costing a second drawing of the same map on screen at once.

The viewer has a single highlight channel — one outline colour, no second class — so what is outlined follows the mode: a constraint search outlines its matches, a pinned lanelet outlines itself. The caption under the map names which of the two it is, rather than showing colour swatches the viewer does not use.

Derived offsets

The longitudinal offset can be Fixed or Derived from the map. A derived offset is a sweep.bindings entry -- currently StopLineOffsetBinding:

Field Value
Position on matched lanelet Derived
Derived from Before stop line
Distance 15 m
sweep:
  bindings:
    ego.spawn_s:
      type: stop_line_offset
      offset: 15.0

The sweeper enumerates a single target key per run, so one entity's spawn can be searched per scenario; the editor warns when a document asks for more.

The ego reaches the runner through the framework's own ego.spawn_lanelet_id / ego.spawn_s keys, with its lateral offset and heading as ego.spawn_t / ego.spawn_heading. Other entities get a declared scenario.spawn_overrides.<entity> sub-tree so they are addressable by exactly the same plain key=value overrides. None of these keys copies the document: an exported package runs its document as it is when the run starts -- edited after the export, or another one named by <PKG>_DOCUMENT_PATH -- and only an override replaces what it says. The scenario.spawn_overrides.<entity> keys, scenario.param_overrides.<node id> and scenario.timeout_seconds are written as null, and the ego.* keys, which the runner reads before the scenario is built, as ${scenario_document:<scenario id>,<path>}: the value at that path of the document the package registered (ego.spawn.lanelet_id, say), read when the key is. The resolver exists in every process that has loaded the scenario packages -- the scenario CLI, a SLURM task, the viewer, scenario-check -- since a package's register() registers it with its document. Hydra saves a run's .hydra/config.yaml unresolved, so that file keeps the interpolation, not the value the run read: reading it elsewhere needs the package installed, and resolves against its document as it is then. A run checks what such an override sets: only null keeps the document's value, lanelet_id must be a whole number (2 or 2.0, not 2.7, a boolean or a blank) and s a finite number (not a boolean or a blank), and an entity's or a node's override (scenario.spawn_overrides.<entity>, scenario.param_overrides.<node id>) must be a mapping of fields; anything else is refused, naming the full key.

An entity's spawn offsets, heading, goal s, size and initial speed must be finite numbers, and its initial speed 0 or more: the validator refuses another value on the entity's path (entities[1].initial_speed_kmh), where the run would refuse it only once CARLA was running.

A document may describe the ego's drive as a pattern of road instead of lanelets -- a logical scenario. The scenario inspector's Route search section lists the pattern one segment per line ("lane 30-60 m, opposite lane: yes", "junction, turn left, traffic light: yes") with where the ego spawns and is sent, and edits it as the YAML the document stores (an empty box removes it; a malformed one is refused with the reason). A Set Goal card's Path then offers Along the scenario's route, whose Route vertices are edited as text, one kind key=value ... per line, and the Route progress condition is offered for triggers, assertions and waypoint conditions. Progress is clamped to the route, so the validator warns about a Route progress card whose target lies before the route's start or past its end: it holds from the first tick the entity is on the map, or never. It also warns about a strict rule pointing off the route from a target on a bound (< the start, > the end), which never holds (logical scenarios). A Spawn card (a vehicle or a pedestrian, never the ego) brings a hidden entity in (or, with no actor, adds a prop by name); trigger its Set Goal card on the Spawn card's action state.

The Gate section below it says when the logical scenario passes over all its runs -- minimum runs, success rate, case and cover coverage, trajectory consistency -- each threshold a row with a checkbox (judged or not), a bar and a number, the shares in percent (Gates for Logical Scenarios).

Ego: who drives, and where to

The ego's inspector opens with Driven by — the stack that drives it, exported as ego.entity:

Driven by ego.entity Goal
TrafficManager (CARLA autopilot) autopilot optional — it reads none
Autoware autoware required — it plans its route to the goal and will not move without one

(The framework's other values -- carla_driver (driver interface), ros2 (ROS 2) and hils (HILS) -- are configured by the driver, ros2 and hils config groups, which the editor does not author; a run can still select them from the command line.)

The Goal section sits beside the spawn, because the two are the ends of the same thing: where the run starts, and where the ego is meant to get to. A goal is picked from the map like a spawn is, and may be searched for like one — the sweep then writes ego.goal_lanelet_id. An Autoware ego without one is a validation error; an ego the TrafficManager drives may be given none — a cut-in or a red-light run is about what happens on the way — and Clear goal puts it back to that.

A goal is not a card. A card happens during a run, and a goal is what the ego needs before one can start: Autoware localizes at the spawn, plans a route to the goal, and only then engages. The framework asks the same of a hand-written scenario — BaseScenario.require_goal(), asked by register_route_to_goal and by ScenarioRunner once setup() returns — so the editor stores the goal on the ego and exports it as the framework's own keys, each reading the document (for a scenario cut_in):

ego:
  spawn_lanelet_id: ${scenario_document:cut_in,ego.spawn.lanelet_id}
  spawn_s: ${scenario_document:cut_in,ego.spawn.s.value}
  spawn_t: ${scenario_document:cut_in,ego.spawn.t}
  spawn_heading: ${scenario_document:cut_in,ego.spawn.heading}
  entity: ${scenario_document:cut_in,ego.driven_by}
  goal_lanelet_id: ${scenario_document:cut_in,ego.goal.lanelet_id}
  goal_s: ${scenario_document:cut_in,ego.goal.s}

An ego with no goal reads as null, the ego group's own; a run sets any of them with the usual override (ego.goal_lanelet_id=265).

The Set Goal card still exists, for changing a destination mid-run or for a vehicle that is not the ego. One owned by the ego and left in the initialization phase is warned about: the ego's own goal is already delivered there, so the card sends a second destination in the same phase, and its goal (and waypoints) replace the ego's own before the run starts. Only a vehicle that plans its own route reads a goal at all, so a goal stored on any other entity is a validation error rather than something quietly dropped at export.

The Set Goal card is also how any road user moves through waypoints (written out, each with a time or a waypoint condition) and Driven by says who moves it: its own driver, a controller, or a replay (Routes, Trajectories and Recorded-Scene Replay). The Despawn card (despawn, a vehicle or a pedestrian, never the ego) takes a road user out of the world when its trigger holds -- typically an Action state condition on its own Set Goal card reaching Complete, so it leaves where its route ends instead of driving on wherever its traffic takes it.

Metadata-driven GUI

Actions, conditions, constraints and bindings keep growing, so the templates render metadata, never a type switch. Adding a primitive is a Python-side change in autoware_carla_scenario.authoring.registry:

register_action_spec(
    ActionSpec(
        type_id="lane_change",
        title="Lane Change",
        category="Vehicle / Motion",
        builder="build_lane_change_action",
        target="..actions:LaneChangeAction",
        visual_kind="instant",
        fields=(FieldSpec("direction", "Direction", "select", "left", _DIRECTIONS),),
    )
)

target names the framework's own class the card builds, and the builder named by builder is generated from that class's constructor signature into authoring._builders_generated by authoring.codegen -- no factory is written by hand. A field whose name differs from the constructor keyword is mapped with argmap, and an argument assembled from several fields is described with builds. After adding or changing a spec, regenerate the builders:

uv run python -m autoware_carla_scenario.authoring.codegen          # write
uv run python -m autoware_carla_scenario.authoring.codegen --check  # verify

The inspector, the canvas, validation and the compiler all pick it up with no template edit. test_authoring_registry.py fails if the committed generated module is not what the specs generate, if a spec names a builder that does not exist, or a visual that names a field the primitive lacks.

A field with no value yet

The inspector posts its whole form on every change, so a control has to be able to show a field's stored value, or the next unrelated edit stores whatever the control showed instead:

  • A bool field whose default is None and that is not required (such as Lane changes on Traffic Parameters, where unset means "keep the run's") is a select of keep the run's / On / Off, not a checkbox. The blank choice stores None, and a post that leaves the field out keeps the stored value. Any other bool is a checkbox, whose absence from a post means off. Either way the editor stores a real true, false or (for the select) null. A hand-edited document may also spell a bool as 1/0, true/false, on/off or yes/no (any case), and leave it blank or null for its default -- for a nullable one, the run's. Anything else (ture, enabled, 2, keep) is a validation error, not a quiet false; write "keep the run's" as null, not as a word.
  • A select field with no value shows a placeholder rather than its first option. When the field is required the placeholder cannot be picked back, and the browser posts nothing for it, so the field stays unset and the validator's "is required" is what the author sees. A stored value that is not one of the options is shown as such, and kept.

A number's bounds

A number or int field states the range its runtime constructor accepts: minimum (inclusive), exclusive_minimum and maximum (inclusive). The validator refuses a value outside it, in the constructor's words, so a document it accepts does not fail only when the scenario starts:

FieldSpec("stop_duration", "Held for", "number", 1.0, unit="s",
          exclusive_minimum=0.0)  # "Held for must be positive."
FieldSpec("speed_threshold", "Counts as stopped below", "number", 0.1,
          minimum=0.0)            # "... must not be negative."

A field whose constructor raises for a value needs the matching bound; test_authoring_accepted_builds.py checks each bound is refused, a value on it (or just inside an exclusive one) is accepted and builds, and each default lies inside it. It also tries every field with no bound on values well outside its usual domain (-1, -0.001, 101, 1e12): each one the validator accepts must build, so a missing bound shows up there. A spawn or lanelet binding's fields are held to the same rule against the sweeper's parse_binding.

A list of records

A field of kind record_list holds an ordered list of records, each a mapping of its own item_fields -- for a list whose order means something and whose entries repeat, such as NADE's adversities, where the first to fire wins:

FieldSpec(
    name="adversities",
    label="Adversities",
    kind="record_list",
    default=(),
    item_fields=(
        FieldSpec("kind", "Kind", "select", "brake_check", _KINDS),
        FieldSpec("probability", "Probability", "number", 0.01),
    ),
)
  • Inspector: one block of controls per record, with buttons to add one and to remove or move each.
  • The buttons are submits of the inspector's own form.
  • The form posts each record's fields as <field>.<i>.<sub>, the row count as <field>.__rows, and the button pressed as <field>.__op.
  • Validation and compiling: each record is validated and coerced by its fields, as a node's params are.
  • required means at least one record.
  • An unset list is an empty one.
  • Entity references inside a record are resolved as top-level ones are.
  • Generated builder: it builds one item per record. The item class comes from the constructor's annotation (list[AdversitySpec]), and each item field feeds the item constructor's keyword of the same name, enums lifted.
  • Restrictions: a record holds no lanelet field, whose map lives outside the form, and no record list.
  • Overrides: a run overrides one record's field with scenario.param_overrides.<node id>.<field>.<index>.<sub>=<value>.

"=" compares within a tolerance

A card that measures a continuous quantity -- Speed, Acceleration, Relative speed, Distance, Distance to a place, Distance to an area, TTC, TTC to a place, Time headway, Route progress, Metric -- offers = among its predicates, and a measured value practically never lands exactly on a threshold. Each of these cards has an optional Tolerance (=) field, in the card's own unit: = holds while the value is within that much of the threshold, either side, so "Speed = 10 m/s, tolerance 0.05" holds from 9.95 to 10.05 m/s. The other predicates ignore it, and an = card shows its tolerance as ± 0.05 beside the value.

Left blank, the tolerance is the runtime's 1e-6, so a document written before the field existed loads and runs as it did; the validator warns about such a card instead, since its rule would never fire. A negative tolerance is an error. Elapsed time and Road users matching have no tolerance field: the scenario clock advances in fixed steps, so = holds on the tick that reaches a duration that is a whole number of steps (use ≥ for any other), and a count is a whole number. The Lanelet length spawn constraint has none either, so = on it is warned about: bound the length with ≥ and ≤ instead.

The map path is a document field

/draft/<id>/map.osm serves the file the document names, and that name is typed by whoever is using the editor -- which may bind 0.0.0.0 (--host). Handed straight to a FileResponse it was an arbitrary local file read for anyone who could reach the port. A path is accepted only when it resolves inside SCENARIO_EDITOR_MAP_ROOTS (the working directory unless set) or the map cache (map_root(), always added) and names a .osm, so what the route can serve is bounded by where the editor was started rather than by what the process can read.

That is a bound, not authentication: the editor still has none, so it belongs on a network you trust.

An edit, a swap, a revision

Every inspector form is posted when a field changes (200 ms after it), and the answer replaces the whole editor body: canvas, inspector and validation, so they never disagree. The tab title and the crumb in the top bar sit outside it and come with the answer out of band, so a rename shows there at once.

Whatever the author is doing when that answer lands carries across it (editor.js): the field being typed in keeps its focus, its caret and what was typed, and a change made in another field in the meantime -- a lanelet picked on the map included -- is posted again from the new form rather than lost with the old one -- unless it was a choice in a list the new form no longer offers, when the server's value stands and nothing is posted. That needs the answer to show the same form again: a change still waiting its 200 ms when the author moves on to another object (opens another card, adds or removes one) is still lost.

A form posts all of its fields, so one rendered from an older copy of the draft would put back whatever was changed since. Each draft therefore has a revision, counted up by every save and stored in its file, and each inspector form carries the one it was rendered from (draft_revision). A post whose revision is out of date is refused with 409 Conflict and nothing is applied; the page says the draft was changed elsewhere and offers to reload. Two tabs' inspector forms therefore cannot undo each other's edits. One tab's own quick edits do not trip the check: a post sent while the answer to the one before is still on its way carries the revision before it, and is accepted as long as every save since came from the same page (editor.js names its page in an X-Editor-Client header). The editor remembers who made each of a draft's last 64 saves, for the 256 drafts saved most recently, in memory only, so such a post is refused like a stale one when a save it is behind was made before the editor restarted (or has dropped out of that memory); a reload puts the tab back in step.

A button that names a row by its position -- remove a signal group, a controller or a phase, move a phase, add a phase to a controller, remove a waypoint condition -- or that posts a whole order (/actors) carries the revision too, and is checked strictly: only the draft's current revision passes, with no allowance for the page's own saves. Any save since the button was rendered may have moved the rows it points at, so a stale tab's click is refused rather than removing or moving the wrong row, and so is the second of two quick clicks in one tab, sent before the answer to the first renumbered the page. The refusal is the same 409 with its Reload button. Every answer re-renders the buttons with the revision it was rendered from, so a click after the swap goes through. A post without a draft_revision -- another button (add, remove by id), a script -- is not checked, so it acts on the draft as it is now.

The forms of those rows -- a signal group's, a controller's, a phase's, the vertex of a waypoint condition -- post to a URL holding the row's position too, but are checked like any other inspector form, so a page's own quick edits pass. One of those edits may be the removal of a row before it, so each such form also names its row as it was rendered (row: the group's, controller's or phase's name, or the vertex; a phase also names its controller, parent_row), and is refused with the same 409 when the row now at its position is another -- unless the form is renaming its own row. A change pending in such a form when the answer lands is not carried across onto the row that took its place: it is dropped, as a change pending while the author moves on to another object is.

Save Draft writes nothing when the draft is already stored as it is (every edit is saved as it is made), so pressing it leaves the revision, and the forms on the page, current.

Save Draft vs Export Wheelhouse

Save Draft writes the working document to scenario_drafts/<id>.yaml.

A document -- a draft, an exported scenario/document.yaml, one written by hand -- is read with YAML 1.2's booleans: only true and false are booleans, so a documented option such as a signal state Off, a turn indicator OFF or a phase's off may be written unquoted. A bool field still takes yes / no / on / off, and a route segment's yes / no reads as written.

Export Wheelhouse produces a .zip the browser downloads, holding every wheel the scenario needs:

my_cut_in-wheelhouse.zip
`-- my_cut_in_scenario_wheelhouse/
    |-- my_cut_in_scenario-0.1.0-py3-none-any.whl  # the scenario itself
    |-- autoware_carla_scenario-*.whl              # the framework, at the pinned commit
    |-- typesafe_carla-*.whl                       # the CARLA client, CPython package prebuilt
    |-- typesafe_carla_toolchain-*.whl             # the Codon compiler it pins
    |-- ... every transitive dependency, ~94 wheels
    |-- requirements.txt                           # the whole set, pinned
    |-- manifest.yaml                              # provenance: the framework pin, the Python, the export's warnings
    `-- README.md                                  # how to install it

Install it with pip and nothing else -- no uv, no git, no network, no resolution:

unzip my_cut_in-wheelhouse.zip
python3 -m venv .venv
.venv/bin/pip install --no-index --find-links my_cut_in_scenario_wheelhouse my-cut-in-scenario
.venv/bin/scenario scenario=my_cut_in map=nishishinjuku

The CARLA client is typesafe_carla, and the typesafe-carla wheel in the wheelhouse is the released one from PyPI, which carries its CPython package (typesafe_carla.carla) prebuilt -- one build for every Python 3.10+. So pip is the whole installation, here as everywhere: nothing is compiled on the target, and an offline vehicle needs neither cc nor a build step. Only if that prebuilt package does not match the installation -- a typesafe-carla-toolchain other than the one the wheel was built with, say -- does the first import typesafe_carla.carla, the first scenario run, build it with the Codon compiler from the toolchain wheel (15 to 50 minutes, about 14 GB of RAM, cc, but no network) into ~/.cache/typesafe_carla/pycarla (TYPESAFE_CARLA_PYCARLA_DIR moves it); typesafe-codon pycarla does that ahead of time, and reports that there is nothing to build when the prebuilt package applies.

That is the point of the format. Where scenarios run is often a venv built from python3-venv and python3-pip -- the two things rosdep can resolve -- with neither uv nor, on a vehicle, a network route. A uv project needs all three; a wheelhouse needs none.

The scenario's document and Hydra config travel inside its wheel, so an installed scenario is self-contained: there is no directory that has to be kept beside it.

The scenario id names the package

The package is named after the document's id, which is lower-case letters, digits and _, starting with a letter (^[a-z][a-z0-9_]*$, ASCII only: scaffold/names.py's SCENARIO_NAME_PATTERN, the rule scenario-new holds a --scenario to, so both paths make names Hydra's override grammar can select). The id is the name scenario=<id> selects, and the exported package is named after it with _scenario added: my_cut_in (the Cut-in example starter's id) exports the module my_cut_in_scenario (distribution my-cut-in-scenario, directory my_cut_in_scenario/), and the id itself stays the scenario's name (scenario=my_cut_in). The suffix is added even to an id that already ends in it, so new_scenario is exported as new_scenario_scenario, never as the package of the id new.

The validator (authoring/package_names.py) refuses an id whose package would be the framework's own, autoware_carla_scenario: the id autoware_carla (and autoware__carla or autoware_carla_). Such a package depends on itself and replaces the installed framework, so it is an id error, shown before an export starts, by the same rule scenario-new refuses that name with.

It also refuses an id that names a built-in scenario (adversity, cut_in, intersection_passing, lane_change, pedestrian_dart_out, temporary_stop, traffic_light_compliance: scaffold/names.py's BUILTIN_SCENARIO_NAMES). The id is the name the package registers its builder under, so once installed the package would replace the built-in builder while the built-in configs (scenario=cut_in/left, ...) still select it and hand it the built-in's config keys. It is an id error, The id 'cut_in' is reserved: it names a built-in scenario ..., worded as scenario-new's refusal of the same --scenario.

Unlike scenario-new, the editor does not refuse an id that names a built-in scenario config group that is no builder, such as lane_change_fail. scenario-new writes a config group, conf/scenario/<name>/, which would merge with the built-in group of that name; an export writes a single config, conf/scenario/<id>.yaml, which Hydra selects as scenario=<id> and keeps apart from the built-in group's scenario=<id>/left and the rest.

export_package and names_for_id, called directly, refuse both too, before writing anything. That is why the Cut-in example starts as my_cut_in, not cut_in. A draft saved from the Cut-in example before this change has the id cut_in: rename it in the Scenario inspector before exporting it.

Package installers compare distribution names with every run of _, - and . folded into one -, so an id that differs from another only in its underscores would be the same package -- installing one would silently uninstall the other. export_package refuses these ids, writing nothing; the validator reports them as warnings on the id field, so the draft -- and a package exported with such an id before #1358 -- still compiles and runs:

Id Would be packaged as Use instead
stop__line (a __) stop_line_scenario, the package of stop_line stop_line
stop_line_ (a trailing _) stop_line_scenario, the package of stop_line stop_line

A draft that already uses such an id still opens and saves; rename it before exporting. Every id the export accepts gets a package of its own.

Ids ending in _scenario are exported under a new name since #1358

Earlier exports did not add the suffix to an id that already ended in _scenario, so stop_line_scenario and stop_line both became the package stop_line_scenario. Re-exporting such an id -- the editor's default new_scenario among them -- now gives it a package of its own. For the id new_scenario:

Before Now
Distribution (pip install ...) new-scenario new-scenario-scenario
Import module and src/ directory new_scenario new_scenario_scenario
Entry point in autoware_carla_scenario.scenarios new_scenario new_scenario_scenario
Export directory and wheelhouse directory new_scenario/, new_scenario_wheelhouse/ new_scenario_scenario/, new_scenario_scenario_wheelhouse/
Document override variable NEW_SCENARIO_DOCUMENT_PATH NEW_SCENARIO_SCENARIO_DOCUMENT_PATH

What selects and configures the scenario does not change: it is still scenario=new_scenario, from the conf file conf/scenario/new_scenario.yaml whose scenario.name is new_scenario, and the downloaded archive is still new_scenario-wheelhouse.zip.

Because the distribution name changed, installing the re-export does not replace the old one. Uninstall the old distribution first:

.venv/bin/pip uninstall new-scenario     # or: uv pip uninstall new-scenario
.venv/bin/pip install --no-index --find-links new_scenario_scenario_wheelhouse new-scenario-scenario

With both installed, both register a builder named new_scenario and both ship scenario/new_scenario.yaml. The entry points load sorted by distribution name, so new-scenario loads before new-scenario-scenario: the old package keeps the name, and the re-export is not loaded at all -- its builder, document and conf/ directory are undone, with a warning naming both entry points -- so a run uses the old package's builder and config together. The re-export is not used until the old distribution is uninstalled.

The id autoware_carla_scenario, refused before because it exported as the framework's own package, now exports as autoware_carla_scenario_scenario and is accepted. Every id that does not end in _scenario keeps exactly the package name it always had.

What the wheelhouse is built from

The exporter still generates the uv project it always did -- pyproject.toml with the framework pinned to an exact commit, uv.lock, the document, the Hydra config, the package's own tests -- and still runs uv sync --locked and those tests against it. That project is now a build input: the wheels are resolved from its lockfile and the project itself does not leave the server.

The CARLA client needs no special handling: typesafe-carla is a plain dependency of the framework, published on PyPI, so the package requests no extra, vendors no wheel, and the lock resolves the client like any other dependency.

There is no destination field. The editor is routinely used from another machine on the LAN, where a path typed into it would name a directory on the host running the server -- not one the person exporting can reach. Everything is built in a temporary directory, the wheelhouse is zipped, and the build tree is removed, so the only thing that outlives the request is the archive, and re-exporting never has to overwrite a half-written one.

The response is still the report -- warnings, the tool log, whether the package's own tests passed, failed or were not run -- with the download link in it. Making the response the file itself would throw away the very things an export is checked for.

One platform, every supported interpreter

A wheelhouse is resolved for a platform: the wheels are the ones the exporting machine selected, so installing them on a different platform fails on the first wheel with no matching tag -- export from a matching machine instead.

The interpreter is not that kind of constraint. Resolution is done once per interpreter the package supports, all into the same directory. Which interpreters those are is the CI-tested range -- 3.10 through 3.14 -- narrowed to what the package's requires-python admits; the package inherits the framework's, so normally all five. The pure-Python wheels are shared between the passes and the compiled ones sit side by side with their own tag, so pip installs whichever matches. That is what lets one export serve ROS 2 Humble, whose Python is 3.10, and Jazzy, whose Python is 3.12: the alternative is a python3.12 that Ubuntu 22.04 does not package at all.

It is large -- the CARLA client and its Codon toolchain, OpenCV and the lanelet2 bindings, the compiled ones once per interpreter. That is the cost of not needing a network at install time, and of not needing to know which Python the target runs before exporting.

Reproducibility

What Pinned by
autoware-carla-scenario exact version, or an exact commit SHA (see How the framework is pinned)
typesafe-carla the framework's own requirement (>=0.8.1,<0.9), locked in uv.lock like everything else
Python .python-version, exact patch version
uv [tool.uv] required-version, when uv's version could be read
Everything else uv.lock, and then the wheels built from it

A branch is never emitted -- main, master and HEAD all move, so a package pinned to one stops being the package that was tested as soon as somebody pushes. When no immutable pin can be determined the export fails rather than guessing. A local-path dependency is only produced by an explicit development export, which says so in its README and manifest.

How the framework is pinned

The export takes the first of these that applies:

  1. SCENARIO_EXPORT_FRAMEWORK_VERSION, to pin a published release instead of the current checkout's commit. Surrounding whitespace is ignored and a blank value counts as unset; anything else must be a valid PEP 440 version without a local label (1.2.3, not a range and not 1.2.3+local, which no index serves), or the export fails.
  2. The framework's own git checkout, pinned to HEAD's commit SHA (with the framework's directory in the repository as subdirectory).

A commit pin, and a development export's path, are only taken from the framework's source tree: a directory whose pyproject.toml names autoware-carla-scenario. A framework installed from a wheel lives in a virtual environment, often a project's .venv inside that project's own git repository; that repository is not the framework's, so it is never pinned. Nor is such an install pinned to the version it reports: a wheel built from an unreleased commit -- the one in a wheelhouse, say -- carries the version of the last release, so == that version would silently resolve a different framework. To export from a framework installed from a wheel, set SCENARIO_EXPORT_FRAMEWORK_VERSION to the release it is; without it the export fails with a message saying so. A development export from a wheel install fails too, since there is no checkout to depend on by path.

Export is atomic

The exporter builds into a temporary directory and runs uv lock, then uv sync --locked, then the generated package's own tests, then the wheelhouse. If locking, verification or the wheelhouse fails, nothing is written -- a package whose dependencies never resolved, or that no environment can install, is not a successful export.

The manifest records only values that were actually observed:

format_version: 3
scenario: {id: my_cut_in, title: Cut in, document_version: 1, package: my-cut-in-scenario}
runtime: {python: 3.12.10, uv: 0.12.0, requires_python: '>=3.10,<3.15'}
wheelhouse:
  directory: my_cut_in_scenario_wheelhouse
  install: pip install --no-index --find-links my_cut_in_scenario_wheelhouse my-cut-in-scenario
  wheels: 104
  python: ['3.10', '3.11', '3.12', '3.13', '3.14']
autoware_carla_scenario:
  source: git
  repository: https://github.com/autowarefoundation/autoware_carla_scenario
  commit: 0123456789abcdef0123456789abcdef01234567
  subdirectory: autoware_carla_scenario
files:
  document: src/my_cut_in_scenario/document.yaml
  hydra_config: src/my_cut_in_scenario/conf/scenario/my_cut_in.yaml
notes: []

A scenario whose map is a source or a directory also lists map_config: src/my_cut_in_scenario/conf/map/my_cut_in_map.yaml, the map group it runs with (Running an authored scenario).

Anything that could not be determined is null with a note, never a plausible guess.

Configuration

Option Variable Default Meaning
--drafts SCENARIO_EDITOR_DRAFTS ./scenario_drafts Where drafts are stored
--export-dir SCENARIO_EDITOR_EXPORT_DIR ./scenario_packages Where an export's wheelhouse .zip is staged for download, in a directory per draft; it is kept, so the link can be followed again, until the draft is deleted or exported again
— SCENARIO_EDITOR_MAP_ROOTS the working directory Directories a Lanelet2 map may be read from, :-separated; the map cache (map_root(): $AUTOWARE_DATA_DIR/maps, ~/autoware_data/maps by default, or AUTOWARE_CARLA_SCENARIO_MAP_CACHE) is always added, set or not
--host SCENARIO_EDITOR_HOST 127.0.0.1 Bind address
--port SCENARIO_EDITOR_PORT 9100 Bind port, 1-65535 (the result viewer uses 9000)
— SCENARIO_EDITOR_MAP_VIEWER GitHub Pages build URL of simple_lanelet2's viewer.js

An option defaults to its variable, so a flag on the command line wins over the environment (uv run scenario-editor --host 0.0.0.0 --port 9200). An unknown option is an error (exit 2) and serves nothing, as is a port (--port or SCENARIO_EDITOR_PORT) that is not an integer within 1-65535: 0, which would have the system pick a port the editor does not report, is refused too.

The drafts directory holds every *.yaml the editor finds there, drafts or not. A file that is not a draft is left out of the list, and so is one the editor cannot read (a permission it lacks, a file that is not UTF-8), with a warning in the log naming it; opening either by its id is a 404 that says why. A drafts directory the editor may not write to -- or a read-only file system -- turns creating, saving or deleting a draft into a page that names the directory (status 500; 507 when its disk is full) instead of a traceback, and the stored draft is left as it was.

The editor listens on this machine only by default

The editor has no authentication, so it binds 127.0.0.1 unless told otherwise. It used to bind 0.0.0.0, every interface; to serve other machines as before, pass --host 0.0.0.0 (or set SCENARIO_EDITOR_HOST=0.0.0.0) on a network you trust. The editor prints a warning when it listens on anything but a loopback address.

Binding loopback keeps other machines out, not a web page open in your own browser, which can post forms to 127.0.0.1 too. So the editor, like the viewer (usage), also refuses them:

  • A POST, PUT, PATCH or DELETE from another site is refused with 403, and changes nothing: one whose Sec-Fetch-Site header is cross-site or same-site, or whose Origin header is not the editor's own scheme, host and port (Origin: null included). A request with neither header, as curl or a script sends it, is served.
  • Two GET routes do more than read, and are refused the same way: the map library with a repository (/maps?repo=...), which runs git ls-remote against it and may clone or fetch it, and the map panel (/draft/<id>/map-view), which parses the map with load_map=1 and binds patterns on it. A link from another site to either is answered with 403 and reaches no git server and loads no map. The editor's own links, forms and htmx requests send Sec-Fetch-Site: same-origin, and a URL typed in the address bar or opened from a bookmark sends Sec-Fetch-Site: none; both are served, and so is a request with neither header. Every other GET only reads drafts and files already on disk. This rests on the browser sending Sec-Fetch-Site, which current browsers do for localhost and loopback addresses but not for plain HTTP on another address (--host 0.0.0.0, a LAN address), and which older browsers (Safari before 16.4, Firefox before 90) never send; a link or image from another site then carries neither header and is served.
  • Against DNS rebinding, a request whose Host header is not localhost, a loopback address (127.0.0.1, ::1) or the --host the editor is bound to, on any port, is refused with 400. Bound to every interface (0.0.0.0 or ::), the editor was asked to answer whatever name it is reached under, and checks no Host; the Origin check still applies. A page served from a rebound name then passes both checks, so a wildcard bind gives up the rebinding protection, even inside a container published only on 127.0.0.1. Behind a reverse proxy or a remote port forwarder that serves it under another name or over HTTPS, the editor refuses requests unless it is bound to every interface; an SSH -L tunnel to a loopback port keeps working.
  • Against clickjacking, every response carries X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none', errors and static files included, so no page can load the editor in a hidden frame and trick you into clicking Export. The editor never frames its own pages either.

Running an authored scenario

An exported scenario plugs in through the same entry point any scenario package uses (see Architecture) -- installed from its wheelhouse, the scenario command is on the venv's PATH:

.venv/bin/scenario scenario=my_cut_in map=nishishinjuku

# Sweep every lanelet the spawn constraints match:
.venv/bin/scenario --multirun scenario=my_cut_in map=nishishinjuku \
    hydra/sweeper=lanelet_constraint

map=nishishinjuku is the starter's map, the scenario's Hydra map group. A scenario whose map is named by a source (picked from the Map library) or a Map directory is on no built-in group, so its package ships one of its own, src/<package>/conf/map/<id>_map.yaml, and is run with it -- the export log, the package's README and the Scenario inspector all name it:

.venv/bin/scenario scenario=my_cut_in map=my_cut_in_map
# @package _global_
map:
  name: Town10HD_Opt
  source: git+https://huggingface.co/datasets/AutowareFoundation/carla-ue5-maps@<commit>#autoware_maps/Town10HD_Opt
  directory: null
  lanelet2_path: null
  xodr_path: null
  projector_type: null
  overwrite_xodr: false
  no_3d_model_lanelet_ids: []

It sets every map key, the ones the document leaves empty as null. A run that selects a built-in group instead -- or none, which selects the default, nishishinjuku -- would put that group's map under the scenario: the framework composes the map group after the scenario one, so the group's name, Lanelet2 and OpenDRIVE paths and exclusion list win over the map keys the scenario's own config writes (and a scenario config cannot select another group, as Hydra refuses an override /map from a group composed before it). So the run refuses it before anything starts -- a single run, a batch (naming the case) and a lanelet sweep alike -- and names the group to run with. So do the paths that search the map without running: a --multirun batch and scenario-expand before their sweep reads any map (Error: <name>: ..., exit 1), the viewer's Run of a sweep, and scenario-odd route (the scenario is not planned):

Error: scenario 'my_cut_in' runs on the map its document names, but map.name is
'NishishinjukuMap', not the document's 'Town10HD_Opt'.  Run it with
map=my_cut_in_map, the map group its package ships

The package's register() registers its document with its builder (register_scenario_document), and the run compares the composed map with it: the CARLA map (map.name) must be the document's, and so must where the map comes from -- map.source, unless a map.directory is set, which no built-in group sets and so is the run's own local copy of the map. A source other than the document's is another map, or another revision whose lanelet ids are not the ones the document names: move the pin in the document and export again. map.lanelet2_path and map.xodr_path are not compared, since an explicit file is how a run points at its own copy of the same map (map=my_cut_in_map map.xodr_path=/tmp/patched.xodr).

The group never installs an OpenDRIVE into CARLA (overwrite_xodr: false), even when the document names its own .xodr: that file is what the run reads the road geometry from, and replacing the simulator's road network is an opt-in only the built-in nishishinjuku group makes, for CARLA assets that ship without one. A map whose CARLA assets need it installed is run with map.overwrite_xodr=true on the command line.

The CARLA client needs no separate install: typesafe-carla is a dependency of the framework, so it is in the lock and in the wheelhouse alongside everything else, with its CPython package prebuilt, so nothing has to be compiled on the machine that runs the scenario (see Save Draft vs Export Wheelhouse).

Offline

Only two things in the editor come from the network. htmx is load-bearing -- every control goes through it, so an editor that cannot fetch it has no working controls at all -- and the map viewer is not:

htmx every interaction; the editor needs it
simple_lanelet2's map viewer the map drawing only — the panel says so when it cannot be fetched

The stylesheet is served by the app itself rather than by a CDN, so a blocked egress rule cannot take the layout with it.