glplot 0.1.4__tar.gz → 0.1.5__tar.gz

{glplot-0.1.4 → glplot-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glplot
-Version: 0.1.4
+Version: 0.1.5
 Summary: High-performance OpenGL plotting library for Python
 Project-URL: Homepage, https://github.com/AkarisDimitry/GLPlot
 Project-URL: Repository, https://github.com/AkarisDimitry/GLPlot
@@ -251,6 +251,21 @@ gplt.plot_lines(a, b, x_range=(-2, 2))
 gplt.show(density=True)
 ```
 
+## Rendering Architecture
+
+GLPlot runs two parallel rendering pipelines — one for 2D primitives (lines, scatter, density) and one for 3D geometry (bars, surfaces, wireframes, `scatter3d`). The diagram below traces both from input data to saved figure, with the vertical rail marking where each stage runs: **CPU** setup/transfer, **GPU** shading, and the **export** readback.
+
+![GLPlot rendering pipeline](examples/dataflow.png)
+
+A few things worth noting from the diagram:
+
+- **2D density path (steps 7R–9R).** Overlapping primitives are additively accumulated into a single-channel `R32F` texture (`DENSITY_ACCUM_FS`), then resolved in one pass with a log-normalized colormap, `t = log(1 + D) / log(1 + Dmax)`, `RGB = apply_heatmap(t)` (`DENSITY_RESOLVE_FS`). `Dmax` is read back to the CPU to normalize the map.
+- **3D depth cues (step 9).** Cavity/rim shading (`ao = (1 − cavity)·rim`) is computed *inline* in `GEOMETRY3D_FS` from the per-vertex normalized depth `v_z_norm` — an SSAO-style effect, not a separate screen-space pass.
+- **Post-processing (2D step 10 / 3D step 11).** The scene renders into an `RGBA16F` framebuffer and passes through background → bloom → tone-map → grain before the HUD and export.
+- **CPU ↔ GPU boundary.** Only staging/upload (`glBufferData`) and the final `glReadPixels` readback touch the CPU; everything between runs on the GPU.
+
+See [GLPlot_Architecture_and_Mathematical_Formulation.md](GLPlot_Architecture_and_Mathematical_Formulation.md) for the full derivation of each stage.
+
 ## Example Gallery
 
 The ordered gallery lives in `examples/gallery` and writes rendered output into `examples/gallery/results`:

{glplot-0.1.4 → glplot-0.1.5}/README.md

@@ -209,6 +209,21 @@ gplt.plot_lines(a, b, x_range=(-2, 2))
 gplt.show(density=True)
 ```
 
+## Rendering Architecture
+
+GLPlot runs two parallel rendering pipelines — one for 2D primitives (lines, scatter, density) and one for 3D geometry (bars, surfaces, wireframes, `scatter3d`). The diagram below traces both from input data to saved figure, with the vertical rail marking where each stage runs: **CPU** setup/transfer, **GPU** shading, and the **export** readback.
+
+![GLPlot rendering pipeline](examples/dataflow.png)
+
+A few things worth noting from the diagram:
+
+- **2D density path (steps 7R–9R).** Overlapping primitives are additively accumulated into a single-channel `R32F` texture (`DENSITY_ACCUM_FS`), then resolved in one pass with a log-normalized colormap, `t = log(1 + D) / log(1 + Dmax)`, `RGB = apply_heatmap(t)` (`DENSITY_RESOLVE_FS`). `Dmax` is read back to the CPU to normalize the map.
+- **3D depth cues (step 9).** Cavity/rim shading (`ao = (1 − cavity)·rim`) is computed *inline* in `GEOMETRY3D_FS` from the per-vertex normalized depth `v_z_norm` — an SSAO-style effect, not a separate screen-space pass.
+- **Post-processing (2D step 10 / 3D step 11).** The scene renders into an `RGBA16F` framebuffer and passes through background → bloom → tone-map → grain before the HUD and export.
+- **CPU ↔ GPU boundary.** Only staging/upload (`glBufferData`) and the final `glReadPixels` readback touch the CPU; everything between runs on the GPU.
+
+See [GLPlot_Architecture_and_Mathematical_Formulation.md](GLPlot_Architecture_and_Mathematical_Formulation.md) for the full derivation of each stage.
+
 ## Example Gallery
 
 The ordered gallery lives in `examples/gallery` and writes rendered output into `examples/gallery/results`:

{glplot-0.1.4 → glplot-0.1.5}/docs/source/api/layers.rst

@@ -11,6 +11,8 @@ Internal layer abstraction for representing geometric primitives on the GPU.
    glplot.core.layers.ScatterLayer
    glplot.core.layers.PolylineLayer
    glplot.core.layers.PatchLayer
+   glplot.core.layers.FunctionLayer
+   glplot.core.layers.FractalLayer
    glplot.core.layers.TextLayer
    glplot.core.layers.Layer3D
 
@@ -41,6 +43,21 @@ Base Layer
    :members:
    :show-inheritance:
 
+View-Driven Layers
+------------------
+
+Layers whose contents are a function of the **current view** and are recomputed when it
+changes, rather than sampled once at creation. See :func:`glplot.pyplot.function` and
+:func:`glplot.pyplot.mandelbrot`.
+
+.. autoclass:: glplot.core.layers.FunctionLayer
+   :members:
+   :show-inheritance:
+
+.. autoclass:: glplot.core.layers.FractalLayer
+   :members:
+   :show-inheritance:
+
 3D & Text Layers
 -----------------
 

{glplot-0.1.4 → glplot-0.1.5}/docs/source/api/plotting.rst

@@ -21,6 +21,17 @@ High-level pyplot-style plotting interface, compatible with Matplotlib conventio
 .. autofunction:: glplot.pyplot.vlines
 .. autofunction:: glplot.pyplot.step
 
+View-Driven Plots
+-----------------
+
+Plots that are **recomputed from the current view** rather than stored as fixed samples,
+so zooming reveals detail that was never computed before. These have no matplotlib
+equivalent — matplotlib's zoom magnifies what it was given.
+
+.. autofunction:: glplot.pyplot.function
+.. autofunction:: glplot.pyplot.mandelbrot
+.. autofunction:: glplot.pyplot.julia
+
 Matrix & Grid Visualization
 -----------------------------
 

glplot-0.1.5/examples/ex_function_plot.py

@@ -0,0 +1,151 @@
+"""Screen-sampled function plots — zoom in and the curve is recomputed, not magnified.
+
+The idea
+--------
+``plot(x, y)`` stores a table. Zoom into it and you magnify the samples it was given: a
+thousand points over (-1, 1) hold *one* sample in the window (1e-3, 2e-3), so a deep zoom
+shows a straight line where the function actually oscillates eighty times. Zoom *out* and
+the opposite waste happens — a million stored points crammed into a thousand pixels.
+
+``function(f, xlim)`` stores the **function** and samples it against the **screen**: about
+one sample per pixel column of whatever x range is currently visible, re-evaluated every
+time the view moves. Three consequences, and they are the whole point:
+
+* **constant resolution** — always exactly what the display can show;
+* **constant cost** — ~2000 evaluations per frame at any zoom depth;
+* **unbounded detail** — features finer than any fixed sampling resolve as you approach.
+
+Compare with the live GPU fractal (``ex_mandelbrot.py --gpu``), the other view-driven layer
+here. Both recompute from the view, but the fractal evaluates per *pixel of area*, so it
+gets more expensive the deeper you go. A curve is one-dimensional: one sample per pixel
+*column* is enough, so it stays cheap forever. Different geometry, different budget.
+
+matplotlib has no equivalent — its zoom never re-samples, because there is nothing to
+re-sample from. Desmos and GeoGebra work this way, and Datashader re-aggregates per view
+for data, but within the scientific-Python plotting stack this is new.
+
+When *not* to use it: measured data. There is no ``f`` to re-evaluate, and resampling
+measurements would be inventing values that were never observed. ``plot`` is right there.
+
+Run it::
+
+    python examples/ex_function_plot.py            # sin(1/x) — scroll into x = 0
+    python examples/ex_function_plot.py --compare  # the same curve, stored vs live
+    python examples/ex_function_plot.py --zoo      # a page of hard functions
+    python examples/ex_function_plot.py --poles    # tan and 1/x: gaps, not spikes
+"""
+
+from __future__ import annotations
+
+import sys
+
+import numpy as np
+
+import glplot.pyplot as plt
+
+
+def topologist_sine() -> None:
+    """``sin(1/x)`` — the standard test for whether a plotter is sampling or storing.
+
+    Every zoom towards the origin brings out oscillations that were not in the previous
+    frame, because they were never computed until you asked to look there.
+    """
+    plt.figure("sin(1/x) — scroll into the origin", figsize=(10, 6))
+    plt.function(lambda x: np.sin(1.0 / x), (-1.0, 1.0), ylim=(-1.3, 1.3), label="sin(1/x)")
+    plt.title("sin(1/x) — scroll towards x = 0; the detail is computed on arrival")
+    plt.xlabel("x")
+    plt.ylabel("y")
+    plt.legend()
+    plt.show()
+
+
+def compare_stored_and_live() -> None:
+    """The same function, both ways, in one figure. Zoom in and they diverge.
+
+    The stored curve is a 2000-point table — a generous one, more than the live layer uses
+    per frame. It looks identical at the full view. Scroll towards the origin and it turns
+    into straight segments while the live one keeps resolving, because the table has
+    nothing left to show and the function always does.
+    """
+    xs = np.linspace(-1.0, 1.0, 2000)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        ys = np.sin(1.0 / xs)
+
+    plt.figure("stored table vs live function", figsize=(10, 6))
+    plt.plot(
+        xs, ys, color=(0.85, 0.30, 0.25, 0.9), linewidth=3.0, label="plot() — 2000 stored points"
+    )
+    plt.function(
+        lambda x: np.sin(1.0 / x),
+        (-1.0, 1.0),
+        ylim=(-1.3, 1.3),
+        color=(0.15, 0.45, 0.75, 1.0),
+        linewidth=1.5,
+        label="function() — resampled per view",
+    )
+    plt.title("identical at this zoom — scroll into x = 0 and watch the red one give up")
+    plt.legend()
+    plt.show()
+
+
+def zoo() -> None:
+    """Functions that punish a fixed sampling, each in its own panel."""
+    _fig, axes = plt.subplots(2, 2, figsize=(12, 8))
+
+    specs = [
+        ("sin(1/x)", lambda x: np.sin(1.0 / x), (-0.5, 0.5), (-1.3, 1.3)),
+        (
+            "x·sin(1/x) — the squeeze",
+            lambda x: x * np.sin(1.0 / x),
+            (-0.3, 0.3),
+            (-0.32, 0.32),
+        ),
+        (
+            "Weierstrass — continuous, nowhere differentiable",
+            lambda x: sum(0.5**k * np.cos(3.0**k * np.pi * x) for k in range(12)),
+            (-1.0, 1.0),
+            (-2.2, 2.2),
+        ),
+        (
+            "a chirp — frequency grows without bound",
+            lambda x: np.sin(x * x * 20.0),
+            (-4.0, 4.0),
+            (-1.3, 1.3),
+        ),
+    ]
+
+    for ax, (title, f, xlim, ylim) in zip(np.ravel(axes), specs):
+        plt.sca(ax)
+        plt.function(f, xlim, ylim=ylim, label=title)
+        plt.title(title)
+
+    plt.suptitle("each panel resamples its own function against its own view — zoom any of them")
+    plt.show()
+
+
+def poles() -> None:
+    """Non-finite values become gaps, which is what makes an asymptote readable.
+
+    ``1/x`` is infinite at zero. A stored table would either miss the pole entirely or draw
+    a vertical line across the whole plot joining +inf to -inf. Here the infinity is turned
+    into a gap, so the two branches stay separate — and because ``sqrt`` is only real on
+    the non-negatives, ``domain=`` stops it being evaluated where it is not defined at all.
+    """
+    plt.figure("poles and domains", figsize=(10, 6))
+    plt.function(lambda x: 1.0 / x, (-3.0, 3.0), ylim=(-6.0, 6.0), label="1/x")
+    plt.function(np.tan, (-3.0, 3.0), label="tan(x)")
+    plt.function(np.sqrt, (-3.0, 3.0), domain=(0.0, np.inf), label="sqrt(x) — domain x ≥ 0")
+    plt.title("1/x breaks at the pole; sqrt is simply not evaluated below zero")
+    plt.legend()
+    plt.show()
+
+
+if __name__ == "__main__":
+    if "--compare" in sys.argv:
+        compare_stored_and_live()
+    elif "--zoo" in sys.argv:
+        zoo()
+    elif "--poles" in sys.argv:
+        poles()
+    else:
+        topologist_sine()

glplot-0.1.5/examples/ex_mandelbrot.py

@@ -0,0 +1,160 @@
+"""Mandelbrot set — the recursive escape-time fractal, plotted and animated.
+
+The Mandelbrot set is the set of complex numbers ``c`` for which the recursion
+
+    z_{n+1} = z_n^2 + c,   z_0 = 0
+
+stays bounded forever. In practice a point is "in" the set if ``|z_n|`` has not exceeded 2
+after some iteration budget, and the *colour* of a point outside the set is how many
+iterations it took to escape — the escape time. That is the recursion the title asks for:
+one line, applied over and over, per point.
+
+How each point could be computed on the GPU
+--------------------------------------------
+The escape loop is embarrassingly parallel: every pixel is independent, so the natural GPU
+form is a **fragment shader** that runs the whole ``z = z*z + c`` loop for its own pixel
+and writes the escape count as the colour. That is how a real-time Mandelbrot explorer
+works — millions of pixels iterate at once, and a deep zoom stays interactive.
+
+GLPlot does not ship that shader yet, so this example computes the escape counts on the
+**CPU, vectorised with numpy** — every pixel of the grid iterated together as one array
+operation, which is the same data-parallel idea one step short of the GPU — and then hands
+the finished grid to GLPlot's GPU renderer as an image. The maths is identical; only *where
+the loop runs* differs. The building block for a GPU port already lives in
+``glplot.anim.processes`` as the ``mandelbrot_zoom`` process, whose ``mandelbrot_frame(t)``
+is exactly the per-frame escape grid a fragment shader would produce.
+
+There are now **two** ways to draw a Mandelbrot in GLPlot, and this file shows both:
+
+* **CPU-baked** (``plot_still`` / ``animate_zoom`` below): compute the escape grid with
+  numpy and hand the finished image to the renderer. Simple, portable, and what you do for
+  any field you can only express in Python — but the pixels are fixed once computed, so
+  zooming just magnifies them.
+* **Live on the GPU** (``--gpu``): ``gplt.mandelbrot()`` / ``gplt.julia()`` draw a
+  ``fractal`` layer whose fragment shader runs the escape loop per screen pixel every
+  frame. Scroll to zoom and the boundary refines to the new scale on its own — this is the
+  "recompute on zoom for more precision" version, and it is real-time. It is the GPU port
+  the "how could each be computed on the GPU?" question is about.
+
+Run it::
+
+    python examples/ex_mandelbrot.py           # CPU-baked still, coloured by escape time
+    python examples/ex_mandelbrot.py --zoom    # CPU-baked animated zoom into a seahorse
+    python examples/ex_mandelbrot.py --gpu     # LIVE GPU set — scroll to zoom, it refines
+"""
+
+from __future__ import annotations
+
+import sys
+
+import numpy as np
+
+import glplot.pyplot as plt
+
+
+def mandelbrot(width: int, height: int, centre: complex, span: float, max_iter: int):
+    """The escape-time grid over a window of the complex plane.
+
+    Vectorised: the whole grid iterates as one numpy operation per step, so the Python
+    loop runs ``max_iter`` times total, not ``max_iter * width * height`` times. A GPU
+    fragment shader would drop even the ``max_iter`` loop onto the hardware and run every
+    pixel's iterations concurrently — this is the CPU shadow of that.
+
+    Returns ``(extent, smooth_counts)``: the ``(x0, x1, y0, y1)`` the window covers and a
+    ``(height, width)`` array of smoothed escape values (continuous, so the colour bands do
+    not stair-step).
+    """
+    aspect = width / height
+    re = np.linspace(centre.real - span * aspect, centre.real + span * aspect, width)
+    im = np.linspace(centre.imag - span, centre.imag + span, height)
+    c = re[None, :] + 1j * im[:, None]
+
+    z = np.zeros_like(c)
+    count = np.zeros(c.shape, dtype=np.float64)
+    alive = np.ones(c.shape, dtype=bool)
+
+    for i in range(max_iter):
+        z[alive] = z[alive] * z[alive] + c[alive]
+        escaped = alive & (z.real * z.real + z.imag * z.imag > 4.0)
+        # Smooth (fractional) escape count: the standard renormalisation that turns the
+        # integer iteration bands into a continuous field, so the colormap does not
+        # stair-step. ``i`` is how many times the recursion has been applied so far.
+        zabs = np.abs(z[escaped])
+        count[escaped] = (i + 1) - np.log2(np.log(zabs + 1e-12))
+        alive[escaped] = False
+        if not alive.any():
+            break
+
+    count[alive] = float(max_iter)  # points still bounded: treat as "in the set"
+    extent = (re[0], re[-1], im[0], im[-1])
+    return extent, count
+
+
+def plot_still() -> None:
+    """A single high-detail Mandelbrot, coloured by escape time."""
+    extent, counts = mandelbrot(900, 700, centre=-0.6 + 0.0j, span=1.25, max_iter=200)
+    plt.figure("Mandelbrot set", figsize=(9, 7))
+    # log1p compresses the huge dynamic range near the boundary so the filaments show.
+    plt.imshow(
+        np.log1p(counts),
+        extent=extent,
+        origin="lower",
+        cmap="magma",
+        aspect="equal",
+    )
+    plt.title("Mandelbrot set — coloured by escape time")
+    plt.xlabel("Re(c)")
+    plt.ylabel("Im(c)")
+    plt.show()
+
+
+def animate_zoom() -> None:
+    """Zoom into a seahorse-valley point, one frame per escape grid.
+
+    Uses ``glplot.animation`` (the matplotlib-compatible surface): a ``FuncAnimation`` whose
+    update recomputes the grid at a smaller span each frame. Every frame is a fresh
+    escape-time computation — the discrete progression the animation model calls a
+    *step* rather than a blend, because there is no meaningful "half a Mandelbrot frame".
+    """
+    import glplot.animation as animation
+
+    target = -0.743643887037151 + 0.13182590420533j  # a classic seahorse spiral
+    fig = plt.figure("Mandelbrot zoom", figsize=(8, 8))
+    frames = 120
+
+    def update(frame: int):
+        span = 1.4 * (0.94**frame)  # geometric zoom: constant magnification per frame
+        max_iter = int(120 + frame * 6)  # deeper zoom needs more iterations to resolve
+        extent, counts = mandelbrot(500, 500, centre=target, span=span, max_iter=max_iter)
+        plt.cla()
+        plt.imshow(np.log1p(counts), extent=extent, origin="lower", cmap="turbo", aspect="equal")
+        plt.title(f"zoom {1.4 / span:,.0f}x   ({max_iter} iterations)")
+        return []
+
+    ani = animation.FuncAnimation(fig, update, frames=frames, interval=40)
+    # ani.save("mandelbrot_zoom.mp4", fps=25)   # needs imageio-ffmpeg or ffmpeg on PATH
+    plt.show()
+
+
+def show_gpu() -> None:
+    """The live, GPU-computed set. Scroll to zoom — it refines to the new scale in real time.
+
+    ``gplt.mandelbrot()`` adds a ``fractal`` layer; the escape loop runs in a fragment
+    shader, once per screen pixel, so there is no grid and no recompute to trigger. The
+    renderer raises the iteration budget as you zoom in, so the boundary keeps resolving.
+    """
+    plt.figure("Mandelbrot (live GPU)", figsize=(9, 7))
+    plt.mandelbrot(center=(-0.6, 0.0), span=1.3, cmap="magma", gain=1.2)
+    plt.title("Mandelbrot — live on the GPU (scroll to zoom)")
+    plt.xlabel("Re(c)")
+    plt.ylabel("Im(c)")
+    plt.show()
+
+
+if __name__ == "__main__":
+    if "--gpu" in sys.argv:
+        show_gpu()
+    elif "--zoom" in sys.argv:
+        animate_zoom()
+    else:
+        plot_still()

glplot-0.1.5/examples/free_energy_demo/compose.py

@@ -0,0 +1,101 @@
+"""Panel-grid compositing shared by mpl_version.py and glplot_version.py.
+
+Both scripts render each panel (and inset) as its own single-panel image and
+hand the file paths here -- using the exact same code to assemble the final
+grid and draw the title is what guarantees the two composites are laid out
+and captioned identically, rather than relying on two independent
+implementations to happen to agree.
+
+Why per-panel images at all, instead of one `plt.subplots(3, 2)` figure for
+mpl_version.py too: GLPlot's headless `savefig()` can only ever render one
+panel per figure (see glplot_version.py's module docstring), so matching
+mpl_version.py to that -- one figure per panel, composited afterward -- is
+what makes the two pipelines comparable at every stage, not just in the
+final pixels.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+#: Both scripts build every panel at this exact physical size and DPI. GLPlot's
+#: headless preview (glplot/utils/preview.py) hardcodes dpi=120 for the
+#: matplotlib figure it reconstructs -- not configurable from the calling
+#: script -- so mpl_version.py matches that number rather than the other way
+#: around. With the same figsize *and* the same DPI, a "9pt" font or a
+#: "1.5pt" line ends up the same pixel size in both outputs; matching only one
+#: of the two would still leave a scale mismatch.
+PANEL_FIGSIZE = (6.4, 5.6)
+PANEL_DPI = 120
+#: render_preview also floors the *inset* figure at 4.0x3.0in
+#: (``max(engine.width/100, 4.0)``, ``max(engine.height/100, 3.0)`` in
+#: glplot/utils/preview.py) regardless of the figsize passed to
+#: ``gplt.figure()`` -- requesting anything smaller (as this used to, at
+#: 2.6x2.3) silently got the floor size instead, so GLPlot's inset PNG came
+#: back at a different pixel size *and* a different aspect ratio (4:3 vs
+#: 2.6:2.3) than mpl_version.py's, which does honor a smaller figsize exactly.
+#: Matching that floor here, instead of fighting it, is what makes the two
+#: inset images the same shape before ``composite_inset`` resizes either of
+#: them into the parent panel's inset box.
+INSET_FIGSIZE = (4.0, 3.0)
+
+TITLE_FONT_PT = 15
+TITLE_BAR_PX = int(round(TITLE_FONT_PT * PANEL_DPI / 72.0 * 2.2))
+GAP_PX = 18
+
+
+def load_font(size_px):
+    for candidate in (
+        "/System/Library/Fonts/Supplemental/Arial.ttf",
+        "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+    ):
+        if Path(candidate).exists():
+            return ImageFont.truetype(candidate, size_px)
+    return ImageFont.load_default()
+
+
+def composite_inset(parent_path, inset_path, frac_box):
+    """Paste ``inset_path`` onto ``parent_path`` at a fraction-of-panel box, with a border."""
+    parent = Image.open(parent_path).convert("RGB")
+    inset = Image.open(inset_path).convert("RGB")
+    pw, ph = parent.size
+    x0, y0, w, h = frac_box
+    box_w, box_h = int(pw * w), int(ph * h)
+    inset = inset.resize((box_w - 6, box_h - 6))
+    bordered = Image.new("RGB", (box_w, box_h), "black")
+    bordered.paste(inset, (3, 3))
+    parent.paste(bordered, (int(pw * x0), int(ph * y0)))
+    parent.save(parent_path)
+
+
+def assemble_grid(paths_grid, out_path, title):
+    """Lay ``paths_grid`` (a list of rows of image paths) into one canvas with a centered title."""
+    images = [[Image.open(p).convert("RGB") for p in row] for row in paths_grid]
+    cell_w = max(im.width for row in images for im in row)
+    cell_h = max(im.height for row in images for im in row)
+    n_rows, n_cols = len(images), len(images[0])
+    canvas_w = n_cols * cell_w + (n_cols + 1) * GAP_PX
+    canvas_h = TITLE_BAR_PX + n_rows * cell_h + (n_rows + 1) * GAP_PX
+    canvas = Image.new("RGB", (canvas_w, canvas_h), "white")
+    draw = ImageDraw.Draw(canvas)
+
+    font = load_font(int(round(TITLE_FONT_PT * PANEL_DPI / 72.0)))
+    bbox = draw.textbbox((0, 0), title, font=font)
+    text_w = bbox[2] - bbox[0]
+    text_h = bbox[3] - bbox[1]
+    draw.text(
+        ((canvas_w - text_w) / 2, (TITLE_BAR_PX - text_h) / 2 - bbox[1]),
+        title,
+        fill="black",
+        font=font,
+    )
+
+    for r, row in enumerate(images):
+        for c, im in enumerate(row):
+            x = GAP_PX + c * (cell_w + GAP_PX)
+            y = TITLE_BAR_PX + GAP_PX + r * (cell_h + GAP_PX)
+            canvas.paste(im, (x, y))
+    canvas.save(out_path)
+    print(f"wrote {out_path}")