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:

.. code-block:: bash

   .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:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - 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``):

.. code-block:: bash

   .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):

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - 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()``):

.. code-block:: bash

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

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - 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``

.. code-block:: bash

   .venv/bin/python -m viz.render_utility_assets