Rendering README Assets¶

The PNG figures committed under docs/assets/ are generated by viz.render_readme_assets. They are produced from the real TrackGen runtime pipeline with fixed seeds and default geometry parameters, then written to disk so they can be displayed by GitHub.

How to regenerate¶

Run the module from the repository root:

.venv/bin/python -m viz.render_readme_assets

The script prints the path of each file it writes.

What gets written¶

render_readme_assets() regenerates all committed figures in one call. The figures it produces are:

File	Contents
`docs/assets/readme-generator-grid.png`	Five representative raw centerlines from each of the six standard generators (30 panels total), rendered at fixed seeds.
`docs/assets/readme-pipeline-stages.png`	A single Bezier sample shown at four pipeline stages: raw generated centerline, constant-spacing resample, XPBD-relaxed band, and the final inflated road.
`docs/assets/readme-generator-strip.png`	One representative raw centerline per standard generator in a single horizontal strip.
`docs/assets/readme-gate-strip.png`	Gate self-collision relaxation illustrated for each gate generator (`bezier`, `checkpoint`, `hull`, `polar`, `voronoi` — `repulsive` is not a registered gate generator, so it is not in this strip): raw anchors (top row) and separated gates with tangent frames and gate-width bars (bottom row).
`docs/assets/batch-of-tracks.png`	The eight roundest valid, inflated track bands from one deterministic CPU batch at the track tutorial’s default geometry (`half_width=0.03`), shown as filled constant-width road bands. CPU, deterministic.
`docs/assets/generator-<name>.png` (six files)	Per-generator panel showing five representative raw centerline outputs. One file per standard generator (`bezier`, `checkpoint`, `hull`, `polar`, `voronoi`, `repulsive`).
`docs/assets/relaxation-before-after.png`	Same seeds, top row raw constant-spacing centerlines (`relax_enable=False`, centerline-only), bottom row the relaxed and inflated constant-width band, in the metric benchmark regime.
`docs/assets/relaxation-same-seeds.png`	Identical seeds through the old relax solver (plain Jacobi, 150 sweeps) and the new default solver (Chebyshev, 50 sweeps) — the visual same-fixed-point comparison.
`docs/assets/relaxation-smoothing.png`	The four noisiest valid tracks generated twice with identical seeds — without the post-solve smoothing tail (top row) and with the defaults (bottom row) — plus a zoom on the worst rippled border segment. Each panel is titled with its curvature-noise metric (dkappa RMS). CPU, deterministic.
`docs/assets/relaxation-convergence.png`	Measured valid-track yield vs `relax_iters` for the old and new relax solvers (library defaults, E=2048). This one figure is a real CUDA measurement: on a GPU-free machine `render_relaxation_convergence()` prints a note and is skipped, so the committed asset must come from a GPU run.

Warning

render_readme_assets() rewrites every figure unconditionally. If you run it and only one figure was supposed to change, all the others are still overwritten (with fresh but deterministic content). Review git diff --stat docs/assets/ before committing, and stage only the files you actually intended to update.

Implementation notes¶

The function lives in viz/render_readme_assets.py. It calls TrackGenerator on the cpu device with a small batch (24 environments) and fixed seeds, so results are deterministic and GPU-free — with one exception: relaxation-convergence.png is a real yield measurement and requires CUDA (it is skipped, with a printed note, when no GPU is available). Individual helper functions — render_generator_panels(), render_gate_assets(), and render_relaxation_assets() — can be called independently if only a subset of assets needs to be rebuilt; all are defined in the same module.

Relaxation iteration-evolution video¶

The relaxation convergence page embeds a short video, rendered by a separate standalone script (it is not part of render_readme_assets() because it requires ffmpeg):

.venv/bin/python -m viz.render_relaxation_video

It writes two files under docs/_static/ (which Sphinx copies verbatim into the build, unlike docs/assets/ which is not reachable from raw-HTML <video> tags):

File	Contents
`docs/_static/relaxation-iterations.mp4`	Four deeply self-overlapping tracks evolving from the raw centerline through the pure iterative XPBD solve (sweeps 0–50, tail off) and then the smoothing tail (passes 0–5), on fixed per-track axes. libx264, `-crf 23`, ~9 s.
`docs/_static/relaxation-iterations-poster.png`	The final converged frame, used as the `<video>` poster.

Each frame is regenerated with relax_iters=k and is a true snapshot of the same deterministic trajectory; the script asserts the raw (k=0) centerlines are bit-identical across two generations and aborts otherwise. Requires a CUDA device or CPU (either works) plus ffmpeg on PATH.

Gate relaxation iteration-evolution video¶

The gate relaxation page embeds the same deliverable for the gate self-collision relaxation, rendered by the same module’s --gates entry point (main_gates()):

.venv/bin/python -m viz.render_relaxation_video --gates

File	Contents
`docs/_static/relaxation-gates-iterations.mp4`	Five bezier gate sequences with heavily overlapping raw anchors evolving round by round through the per-env Gauss-Seidel sphere separation (illustrative `gate_radius=0.13`, `gate_width=0.16`), with per-panel `converged` tags once an env’s state stops changing. libx264, `-crf 23`, ~6 s.
`docs/_static/relaxation-gates-iterations-poster.png`	The final separated frame, used as the `<video>` poster.

Each frame is regenerated with gate_solve_iters=k and is a true snapshot of the same trajectory (the coincident-pair tie-break is indexed by the round, not the total budget); the script asserts the raw anchors are bit-identical across two generations, shows only envs whose state at the round cap matches a much longer run, and verifies no shown env leaves its converged state once reached. Requires a CUDA device or CPU (either works) plus ffmpeg on PATH.

Utilities overview figure¶

The utilities module renders FOUR figures via viz.render_utility_assets (same conventions: fixed seeds, cpu device, deterministic output):

docs/assets/utilities-overview.png — the four-panel figure in the API reference showing track_gen.props cones/walls/spacing and the track_gen.collision SDF + box classification
docs/assets/checkpoints-overview.png — track-sourced virtual gates and gate-sourced checkpoints from track_gen.checkpoints
docs/assets/progress-tracking.png — agent path colored by progress state from track_gen.progress
docs/assets/disc-collision.png — disc obstacles and box contacts from track_gen.collision.DiscChecker

.venv/bin/python -m viz.render_utility_assets