bikeped.scenarios¶
The scenario registry and generators. Scenarios explains the format and the suites.
cli
¶
Command line interface: python -m bikeped.scenarios COMMAND.
Run from the repository root so that decision_testbench is importable.
build_parser
¶
Argument parser for all subcommands.
Source code in bikeped/scenarios/cli.py
main
¶
Parse argv and run the chosen command; returns the exit status.
builders
¶
Path builders that emit the testbench waypoint format.
Every builder works in the scenario frame used by decision_testbench: metres, x along the
road (bikes ride along it), y across the road (pedestrians cross along it), crosswalk centre at
(5, 0). Times are seconds from the start of the scenario and speeds are metres per second.
The testbench interpolates paths linearly in time, so curved or speed-varying motion is sampled
densely (every step seconds, 0.25 s by default). Headings are in degrees, counter-clockwise
from +x: 0 rides towards +x, 180 towards -x (the direction of the conformance bikes),
90 walks towards +y.
The fluent :class:Path keeps scenario definitions short::
bike = (Path.start(34, 1.5, heading=180).ride(14, 6.0)
.arc(radius=6, angle=90).ride(8).build())
Path
¶
Path(
x: float,
y: float,
t: float = 0.0,
heading: float = 0.0,
speed: float = 0.0,
step: float = 0.25,
)
Fluent builder for one agent path.
The builder tracks the current position (x, y) in metres, time t in seconds, heading in
degrees and speed in m/s. Each motion primitive appends waypoints sampled every step
seconds and leaves the state at its end, so primitives chain. :meth:build returns the
waypoint list with strictly increasing times.
Source code in bikeped/scenarios/builders.py
start
classmethod
¶
start(
x: float,
y: float,
t: float = 0.0,
heading: float = 0.0,
speed: float = 0.0,
step: float = 0.25,
) -> Path
Start a path at (x, y) at time t (s), facing heading (deg).
Source code in bikeped/scenarios/builders.py
ride
¶
Move distance metres along the current heading at constant speed (m/s).
Source code in bikeped/scenarios/builders.py
to
¶
Move in a straight line to (x, y) at constant speed; the heading follows.
Source code in bikeped/scenarios/builders.py
face
¶
wait
¶
Stand still for duration seconds; the speed becomes zero.
appear
¶
Shift the whole path so that it begins at time t.
Use it for late emergence: the agent is absent (not detected) until t, as if hidden
behind a parked van or a crowd. Call it before any motion primitive.
Source code in bikeped/scenarios/builders.py
change_speed
¶
Accelerate or brake along the heading to v_end m/s at |accel| m/s^2.
The distance covered follows from constant acceleration; the path ends with
speed == v_end. Braking to zero leaves the agent stopped at the end point.
Source code in bikeped/scenarios/builders.py
accelerate
¶
brake
¶
brake_to
¶
Brake at constant deceleration so the agent reaches v_end at a given coordinate.
Give x (for agents moving along the road) or y (for agents moving across it). The
deceleration is whatever stops the agent exactly there.
Source code in bikeped/scenarios/builders.py
arc
¶
Turn on a circular arc of radius metres through angle degrees.
Positive angles turn left (counter-clockwise seen from above, +y up), negative angles
turn right. Speed is constant along the arc.
Source code in bikeped/scenarios/builders.py
lane_change
¶
Shift sideways by lateral metres (positive to the left) over length metres.
The lateral offset follows a half-cosine, which gives a smooth swerve or lane change; the heading is unchanged at the end.
Source code in bikeped/scenarios/builders.py
zigzag
¶
Weave about the current heading: sinusoidal lateral offset of amplitude metres.
The agent covers distance metres along the heading; one full weave takes
wavelength metres. Speed is the speed along the heading.
Source code in bikeped/scenarios/builders.py
through
¶
Follow a Catmull-Rom spline from the current position through points at speed.
The spline passes through every control point. Arc length is resampled so the speed is constant; the heading at the end follows the last segment.
Source code in bikeped/scenarios/builders.py
build
¶
Return the path as testbench waypoints [{'x', 'y', 't'}, ...] (rounded to mm, ms).
Source code in bikeped/scenarios/builders.py
catmull_rom
¶
Sample a centripetal-free (uniform) Catmull-Rom spline through points.
Returns an (N, 2) array in the same units as the input. End points are duplicated so the
curve starts and ends exactly at the first and last control points.
Source code in bikeped/scenarios/builders.py
straight
¶
straight(
x0: float, y0: float, x1: float, y1: float, speed: float, t0: float = 0.0
) -> list[Waypoint]
Constant-speed straight leg from (x0, y0) to (x1, y1) starting at t0.
Source code in bikeped/scenarios/builders.py
crossing
¶
crossing(
x: float = 5.0,
y0: float = -6.0,
y1: float = 6.0,
speed: float = 1.35,
t0: float = 0.0,
) -> list[Waypoint]
Pedestrian crossing along y at road position x at constant speed.
Source code in bikeped/scenarios/builders.py
shift
¶
shift(
path: Sequence[Waypoint], dx: float = 0.0, dy: float = 0.0, dt: float = 0.0
) -> list[Waypoint]
Return a copy of path translated by (dx, dy) metres and dt seconds.
Source code in bikeped/scenarios/builders.py
group
¶
group(
path: Sequence[Waypoint], offsets: Sequence[tuple[float, float, float]]
) -> list[list[Waypoint]]
Copies of path for a group that moves together, one per (dx, dy, dt) offset.
Source code in bikeped/scenarios/builders.py
platoon
¶
platoon(
path: Sequence[Waypoint],
n: int,
headway_s: float = 1.0,
lateral: float = 0.0,
jitter_m: float = 0.0,
jitter_s: float = 0.0,
seed: int = 0,
lateral_axis: str = "y",
) -> list[list[Waypoint]]
n riders on the same line, each headway_s seconds behind the previous one.
lateral staggers alternate riders sideways (metres along lateral_axis); jitter_m
and jitter_s add seeded uniform noise to each rider's lateral position and start time so
the group does not look cloned. The result is deterministic for a given seed.
Source code in bikeped/scenarios/builders.py
path_speeds
¶
Segment speeds (m/s) of a waypoint path, one per segment.
Source code in bikeped/scenarios/builders.py
path_accelerations
¶
Magnitude of the velocity change (m/s^2) at each interior waypoint.
The velocity change between consecutive segments is divided by the time between segment midpoints, so turns contribute their centripetal acceleration.
Source code in bikeped/scenarios/builders.py
catalog
¶
Catalog export: catalog.json, one SVG thumbnail per scenario, simulator data, markdown.
Thumbnails are 320x200 top-down sketches in the scenario frame: the road runs left to right
(+x to the right), +y points up, the crosswalk is the striped band at x = 5. The view
is the window x in [-12, 36], y in [-15, 15] (metres), widened at the same aspect ratio
when a scenario's paths leave it, so most thumbnails share one scale. Pedestrian paths are cyan,
cyclist paths amber; dash length grows with the agent's mean speed, a filled dot marks a start
in view and a hollow dot an agent that emerges within 15 m of the crosswalk after the start,
a ring marks an agent that stands still.
thumbnail_svg
¶
SVG source of the thumbnail for scenario s (320x200 viewBox, no text).
Source code in bikeped/scenarios/catalog.py
scenario_record
¶
JSON-ready metadata and paths of one scenario, as written to catalog.json.
Source code in bikeped/scenarios/catalog.py
export_catalog
¶
Write catalog.json and <id>.svg for every scenario of suites into out_dir.
Returns {'catalog': path, 'thumbnails': n, 'scenarios': n}.
Source code in bikeped/scenarios/catalog.py
export_simulator
¶
Write scenarios.extended.js for the browser simulator in sim_dir.
The file defines window.BIKEPED_SUITES = {suite: [scenario, ...]} with the simulator's
own scenario keys (name, expected, challenge, agents) plus id, family
and vehicle, so the page loads it with a plain <script src> even from file://.
Source code in bikeped/scenarios/catalog.py
catalog_markdown
¶
Markdown table of a suite: thumbnail, name, family, agents, duration, expected state.
Source code in bikeped/scenarios/catalog.py
conformance
¶
Metadata for the 24 conformance scenarios of the paper.
The scenario content lives in decision_testbench.SCENARIOS and is not copied here. This module
only adds the library metadata (slug, family, description, tags, per-agent model hints) and
:func:conformance_suite returns decorated shallow copies, leaving the originals untouched.
slugify
¶
Lower-case slug of a display name: 'High-Speed Near Miss' -> 'high-speed-near-miss'.
conformance_suite
¶
The paper's 24 scenarios in paper order, as decorated shallow copies.
Each copy shares the waypoint lists with decision_testbench.SCENARIOS; the agent dicts are
copied so that the model hints do not touch the originals.
Source code in bikeped/scenarios/conformance.py
evaluate
¶
Run scenarios through the testbench decision pipeline and summarise the outcome.
Everything is computed by decision_testbench.simulate_scenario with ideal perception (the
noise-free path, tracker on, no latency). This module only aggregates its per-frame states and
ground-truth dangers into per-scenario figures; the metrics themselves (danger labels,
false positives, sensitivity) are the testbench's.
The dominant state of a run is the most severe state (alert > warning > safe >
idle) that the pipeline holds for at least :data:MIN_STATE_S seconds in total. The same
rule applied to the ground truth gives :func:ground_truth_label: idle without pedestrians,
safe without cyclists, alert with at least :data:MIN_STATE_S of danger, else
warning.
dominant_state
¶
Most severe state held for at least min_s seconds in total (idle if none).
Source code in bikeped/scenarios/evaluate.py
ground_truth_label
¶
ground_truth_label(
scenario: dict, dangers: ndarray, fps: int = FPS, min_s: float = MIN_STATE_S
) -> str
State the ground truth calls for: see the module docstring for the rule.
Source code in bikeped/scenarios/evaluate.py
label_scenario
¶
:func:ground_truth_label from compute_ground_truth_danger alone (no pipeline run).
The frame times match simulate_scenario: t = k / fps up to the scenario duration.
Source code in bikeped/scenarios/evaluate.py
evaluate_scenario
¶
Simulate one scenario and summarise it.
Returned keys: id, name, suite, family, duration_s, agents,
danger_s and actionable_s (ground-truth time), alert_s, false_alert_s (alert
on frames the ground truth calls safe), danger_intervals (one dict per interval with
start, end, alerted and lead_s: seconds from alert onset to danger onset,
negative when the alert came late), sensitivity, specificity, dominant,
expected, ground_truth and match.
Source code in bikeped/scenarios/evaluate.py
is_known_hard
¶
True when the pipeline's dominant state is wrong or an alert is late or missing.
Late means the alert began more than :data:LATE_ALERT_S seconds after the danger interval.
Source code in bikeped/scenarios/evaluate.py
evaluate_suite
¶
:func:evaluate_scenario for each scenario.
format_table
¶
Plain-text table of :func:evaluate_scenario rows with a totals line.
Source code in bikeped/scenarios/evaluate.py
to_json
¶
JSON text of evaluation rows (non-finite numbers become null).
Source code in bikeped/scenarios/evaluate.py
extended
¶
The extended suite: hand-designed urban conflicts and deliberate negatives.
Same frame as the conformance scenarios: metres, x along the road, y across it, the
crosswalk centred on (5, 0) and about 3 m wide, kerbs near y = -6.5 and y = +6.5.
Through cyclists ride towards -x (heading 180 degrees) a metre or two either side of the
centre line, as in the paper's scenarios.
Speeds follow published ranges: walking 1.2-1.5 m/s, older adults 0.8-1.0, wheelchairs 1.0-1.3, children running 2-3, runners 3-4, commuter cyclists 4-7, fast road cyclists 8-11, e-bikes up to about 11, e-scooters 5-7, cargo bikes 3.5-5.5; comfortable cyclist braking about 2 m/s^2 and hard braking 4-6 m/s^2.
expected_dominant is the label the testbench ground truth implies
(:func:bikeped.scenarios.evaluate.ground_truth_label), checked by running each scenario.
Scenarios the default pipeline gets wrong carry the known-hard tag: its dominant state differs
from expected_dominant (a false alarm or a miss), or its first alert comes more than
:data:~bikeped.scenarios.evaluate.LATE_ALERT_S after a danger interval begins.
ped
¶
Pedestrian agent dict with a model hint.
Source code in bikeped/scenarios/extended.py
bike
¶
Cyclist agent dict with a model hint.
Source code in bikeped/scenarios/extended.py
across
¶
across(
speed: float = 1.4,
t0: float = 0.0,
x: float = 5.0,
y0: float = -6.5,
y1: float = 6.5,
) -> list[dict]
Pedestrian walking straight across the road at x from y0 to y1.
Source code in bikeped/scenarios/extended.py
along
¶
along(
speed: float,
t_at: float,
y: float = 1.0,
x_at: float = 5.0,
x_end: float = -8.0,
max_start: float = 34.0,
) -> list[dict]
Cyclist riding towards -x at speed that reaches x_at at time t_at.
It starts at t = 0 far enough back to arrive on time, or later if that would put it more
than max_start metres down the road.
Source code in bikeped/scenarios/extended.py
scenario
¶
scenario(
name: str,
family: str,
expected: str,
description: str,
agents: list[dict],
tags: tuple[str, ...] = (),
vehicle: str | None = None,
weather: str | None = None,
) -> dict
Assemble one scenario dict with library metadata.
Source code in bikeped/scenarios/extended.py
extended_suite
¶
All extended scenarios, grouped by family.
Source code in bikeped/scenarios/extended.py
generators
¶
Seeded parametric scenario families.
generate(family, n, seed) returns n scenarios of one family in the usual frame (metres,
x along the road, crosswalk centred on (5, 0)). Sweep families spread their parameter
evenly over the range in :data:FAMILIES and use the seed only for small jitter (start times
within 0.2 s, speeds within 5 %), so the sweep values themselves stay readable. The same family,
n and seed always give identical output.
expected_dominant of each generated scenario is computed from the testbench ground truth with
:func:bikeped.scenarios.evaluate.label_scenario.
generate
¶
n scenarios of family (a key of :data:FAMILIES), deterministic for seed.
Source code in bikeped/scenarios/generators.py
registry
¶
Scenario registry: named suites and lookup by slug, name or suite:index.
Suites are built lazily on first use and cached. conformance is the paper's 24 scenarios from
decision_testbench.SCENARIOS; extended and stress are defined in this package.
Callers receive the cached dicts, so treat them as read-only (copy before editing).
list_suites
¶
get_suite
¶
all_scenarios
¶
get_scenario
¶
Look up one scenario.
key is a slug ('fast-approach'), an exact display name ('Fast Approach') or
'suite:index' with a zero-based index ('conformance:7' is Fast Approach).
Source code in bikeped/scenarios/registry.py
schema
¶
Validation of scenario dicts.
:func:validate_scenario checks one scenario against the testbench format and the library
metadata; :func:validate_suites also checks that ids and names are unique across scenarios.
Both return a list of human-readable problems, empty when everything is fine.
Speed and acceleration limits are per agent model and deliberately generous: they catch typos (a pedestrian at 15 m/s, a waypoint with the wrong time) rather than judge realism. Speeds are segment speeds of the piecewise-linear path in m/s; accelerations are velocity changes between consecutive segments in m/s^2, so they include turning.
validate_scenario
¶
Problems found in one scenario (empty list when valid).
Source code in bikeped/scenarios/schema.py
validate_suites
¶
Validate every scenario and check that ids and names are unique among them.
Source code in bikeped/scenarios/schema.py
stress
¶
The stress suite: dense scenes for throughput and tracker-load testing.
Each scene puts many pedestrians and cyclists in view at once (12 to 24 agents) in the usual
scenario frame (metres, x along the road, crosswalk centred on (5, 0)). Positions and
start times are jittered with fixed seeds, so the suite is identical on every run.
expected_dominant is the ground-truth label from
:func:bikeped.scenarios.evaluate.ground_truth_label.
stress_suite
¶
Eight dense scenes, deterministic.