Skip to content

Bring the cooperative-crossing docs and comments in line with the code - #14

Merged
schreck61 merged 5 commits into
mainfrom
claude/sweet-wilson-82a194
Nov 11, 2026
Merged

schreck61 merged 5 commits into
mainfrom
claude/sweet-wilson-82a194

Conversation

@schreck61

@schreck61 schreck61 commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

Several descriptions of the cooperative crossing, and two module comments, said things the 0.5.1 code doesn't do. Each change below was checked against the code first.

README, docs/insights.md and the app's text

  • Who asks for a slot: in each lane the manager considers only the first vehicle without a trajectory, and right turns never ask. Vehicles don't ask "when they enter the map".
  • First come, first served: of those lane heads, the one that could cross the stop line soonest goes next, not the first to arrive.
  • Nominal gap: it covers the two message latencies and the 0.3 s actuation delay (0.5 s), not latency alone. The app's label becomes Nominal: latency and actuation (no failures), and docs/architecture.md quotes the new label.
  • Switching cost: about 2.1 s, since the code's reservation zones are about 3.2 m at a right angle (2.2 s assumed 3.5 m).
  • Batch join window: the hover text says the window comes on top of the vehicle's own headway.
  • Ground-truth exceptions: pedestrians and emergency vehicles reach the SensorView straight from ground truth, whichever sensors are fitted. The README, sensors.rs and docs/architecture.md now all say so, and that controllers use the pedestrian figures (not camera counts) while only Sim's preemption reads the emergency vehicles.

docs/cooperative-intersections.md

  • The P2 gap at 40 km/h is 1.43 s throughout; cim_numbers.py notes why it prints 1.42 s at 11.1 m/s.
  • The median is 4 m and the slip lane leaves about 25 m before the stop line, as in network.rs.
  • Appendix A: P1 is 2δ + tᵣ without the extra max(0, …) term, and a new list gives where the code's parameters differ from the estimates (δ and tᵣ, the CACC gap, deceleration, P1 and the zone width).
  • A header note and short notes in sections 3.5, 6, 6.6–6.8 and 12.1 say what isn't built: the approach zones A–E and the authority point, the elevated ring and the roadside equipment.
  • plan-view.svg is titled "Reference design (section 6)", and the plan's caption says how the app's crossing differs.

ACCESSIBILITY.md

  • The pointer-only tasks are panning and zooming the map, selecting a vehicle, placing a pedestrian at a crosswalk corner and the charts' hover readouts. "Placing sensors" isn't a feature.
  • Reviewed for 0.5.1; the GUI didn't change between 0.5.0 and 0.5.1.

Comments

  • coop.rs: the module doc describes the lane-head queue; the gap doc says v / 2b, the time to cover the braking distance at entry speed, which is what the code computes.
  • sensors.rs: the module doc no longer credits the camera with pedestrian counts or lists the preemption receivers as a sensor; it gives the same ground-truth exceptions as the README and docs/architecture.md.

Screenshots

Every image that showed the old manager description or sensor note, or the Signal timing chart from before PR 15, was retaken from this branch on top of PR 15 with the scripted-screenshot settings in Appendix A of docs/architecture.md. They were found by OCR over docs/*.png and docs/images/architecture/*.png.

  • coop-manager.png and sensors.png: the same crops of new captures. coop-manager.png is 50 px taller for the longer description.
  • coop.png and overview.png: only the changed parts come from new captures (the manager section on coop.png; the sensor note and the bottom panel on overview.png), so the hand-drawn callouts stay. Callout 1 on coop.png is extended to frame the taller section. The new bottom panel matches timeline.png pixel for pixel, since both show the same moment.
  • In docs/images/architecture, coop-compare.png, compare.png and corridor.png, and the README's arterial.png, compare.png, corridor.png and cooperative.png: new captures with the same settings and framing. The README images came from an older UI, so they also pick up the current layout and spelling. Appendix A now lists their settings.
  • timeline.png is unchanged; PR 15 retook it.

Not in this PR

  • docs/roundabout.png isn't referenced anywhere and is left in place for now. It still shows the old sensor note.

Testing

  • cargo test --locked --release
  • cargo clippy --locked --release --all-targets -- -D warnings and the wasm32 clippy run
  • python3 docs/cooperative-scripts/make_figures.py <dir> reproduces both committed SVGs byte for byte
  • OCR over every image finds the old strings only in the unreferenced docs/roundabout.png

Several descriptions of the cooperative crossing said things the code
doesn't do. The README, the design notes, docs/insights.md, the app's
text and two module comments now say:

- In each lane the manager considers only the first vehicle without a
  trajectory, and right turns never ask; first come, first served takes
  whichever of those could cross the stop line soonest.
- The nominal gap is the two message latencies and the actuation delay
  (0.5 s), not latency alone. The app's label for it changes to match,
  and docs/architecture.md quotes the new label.
- A switch between conflicting paths costs about 2.1 s, since the
  reservation zones are about 3.2 m at a right angle.
- The batch join window comes on top of the vehicle's own headway.
- The fail-safe gap adds v / 2b, not the time to brake from v.
- Pedestrian counts reach the SensorView from ground truth, not from
  the camera. The emergency preemption receivers are exact and always
  fitted, and only the simulation's own preemption reads them.

In the design notes the P2 gap at 40 km/h is 1.43 s throughout, the
median is 4 m and the slip lane leaves about 25 m before the stop line.
Appendix A drops a P1 term nothing uses and lists where the code's
parameters differ from the estimates'. The notes now say which parts of
the reference design aren't built (the approach zones and authority
point, the elevated ring and the roadside equipment), and the plan view
carries a title saying it shows the reference design.

ACCESSIBILITY.md lists the real pointer-only tasks and says it was
reviewed for 0.5.1.

Signed-off-by: Jim Schreckengast <schreck@gmail.com>
The README and the sensors.rs module doc named only pedestrians as
reaching the SensorView from ground truth, and sensors.rs listed the
preemption receivers as an exact sensor, while docs/architecture.md
named pedestrians and emergency vehicles. All three now say the same:
both reach the SensorView straight from ground truth, whichever sensors
are fitted. Controllers use the pedestrian figures, and only Sim's
preemption reads the emergency vehicles, so controllers see those only
through their sensors.

Signed-off-by: Jim Schreckengast <schreck@gmail.com>
The manager's description and the note under the sensor settings
changed, so every screenshot that shows either was retaken with the
app's scripted-screenshot settings:

- coop-manager.png and sensors.png are the same crops of new captures;
  coop-manager.png is 50 px taller for the longer description.
- coop.png and overview.png keep their hand-drawn callouts. Only the
  changed part of the left panel comes from a new capture, and the
  first callout on coop.png is extended to frame the taller section.
- coop-compare.png and the README's arterial.png, compare.png,
  corridor.png and cooperative.png are new captures with the same
  settings and framing. Appendix A of docs/architecture.md now lists
  the README images' settings.

docs/roundabout.png, which nothing references, still shows the old
note.

Signed-off-by: Jim Schreckengast <schreck@gmail.com>
Brings in the 0.5.1 fixes, including the signal timing chart that now
shows each stage's yellow and all-red, so the screenshots can be
retaken on top of them.

Signed-off-by: Jim Schreckengast <schreck@gmail.com>
The Signal timing chart now draws each stage's yellow and all-red after
its green. Six full-window screenshots of signalized layouts still
showed the old chart, so they were retaken on top of that change:
overview.png, compare.png and corridor.png in docs/images/architecture,
and the README's arterial.png, compare.png and corridor.png.

overview.png keeps its hand-drawn callouts: only the inside of
callout 5, the bottom panel, comes from the new capture. That panel
matches timeline.png pixel for pixel, since both show the same moment.
The others are full captures with the same settings and framing.

Signed-off-by: Jim Schreckengast <schreck@gmail.com>
@schreck61
schreck61 enabled auto-merge (rebase) November 11, 2026 13:57
@schreck61
schreck61 merged commit 4b3e80f into main Nov 11, 2026
12 checks passed
@schreck61
schreck61 deleted the claude/sweet-wilson-82a194 branch November 11, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant