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:
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:
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_statetrigger 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.pyreports a hand-editeduiblock 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: truein 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: falsein 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 refusesonce: falseon them. - One actor reacting to another is a reference, not a coincidence.
"Swerve once NPC1 has cut in" is a
Lane Changeclip on the ego track whose trigger is an Action state condition naming NPC1's cut-in and the statecompleteState. 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 aposition: stickywrapper, and sticky creates a stacking context whatever its ownz-indexis -- so az-indexleft 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 abound, 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. /staticis served withCache-Control: no-cache.StaticFilessends anETagbut noCache-Control, which lets a browser invent a freshness lifetime and keep running an oldeditor.jswithout asking -- an editor visibly missing a feature the server is already serving. TheETagstill 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 |
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 logical scenario: the route search¶
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
boolfield whose default isNoneand that is notrequired(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 storesNone, and a post that leaves the field out keeps the stored value. Any otherboolis a checkbox, whose absence from a post means off. Either way the editor stores a realtrue,falseor (for the select)null. A hand-edited document may also spell aboolas1/0,true/false,on/offoryes/no(any case), and leave it blank ornullfor its default -- for a nullable one, the run's. Anything else (ture,enabled,2,keep) is a validation error, not a quietfalse; write "keep the run's" asnull, not as a word. - A
selectfield with no value shows a placeholder rather than its first option. When the field isrequiredthe 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.
requiredmeans 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:
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 not1.2.3+local, which no index serves), or the export fails.- The framework's own git checkout, pinned to
HEAD's commit SHA (with the framework's directory in the repository assubdirectory).
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,PATCHorDELETEfrom another site is refused with 403, and changes nothing: one whoseSec-Fetch-Siteheader iscross-siteorsame-site, or whoseOriginheader is not the editor's own scheme, host and port (Origin: nullincluded). A request with neither header, as curl or a script sends it, is served. - Two
GETroutes do more than read, and are refused the same way: the map library with a repository (/maps?repo=...), which runsgit ls-remoteagainst it and may clone or fetch it, and the map panel (/draft/<id>/map-view), which parses the map withload_map=1and 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 sendSec-Fetch-Site: same-origin, and a URL typed in the address bar or opened from a bookmark sendsSec-Fetch-Site: none; both are served, and so is a request with neither header. Every otherGETonly reads drafts and files already on disk. This rests on the browser sendingSec-Fetch-Site, which current browsers do forlocalhostand 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
Hostheader is notlocalhost, a loopback address (127.0.0.1,::1) or the--hostthe editor is bound to, on any port, is refused with 400. Bound to every interface (0.0.0.0or::), the editor was asked to answer whatever name it is reached under, and checks noHost; theOrigincheck 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 on127.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-Ltunnel to a loopback port keeps working. - Against clickjacking, every response carries
X-Frame-Options: DENYandContent-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:
# @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.