quiltwright 0.10.1

Quiltwright -- holographic output for scientific visualization.

Eric G. Suchanek, PhD -- Flux-Frontiers

Quiltwright is the last stage of a scientific rendering pipeline -- any pipeline that ends in a scene. It takes what you already have -- a PyVista or VTK scene built in memory, a Blender file or an exported mesh, or a .pov file written thirty years ago by someone who is no longer around to explain it -- and puts it on holographic hardware in glasses-free depth. Nothing is rewritten to get there: your scene file is never modified, the off-axis camera is supplied per view, and each scene is rendered by the renderer it already belongs to. Where that renderer is Blender's Cycles, the views are path-traced on the GPU's ray-tracing cores if the hardware has them.

It is used that way by WaveRider for geometric ML manifolds and by pypdb2pov for molecular structures, but neither is a prerequisite. If you can render it, you can hang it in the air.

A career in structural biophysics, arranged as exhibits: B-DNA and Z-DNA under bell jars, Ras and my original DNA Under Glass on the walls. The molecular models were generated by pdb2pov in 1997; the room dates to 1995. Quiltwright ray-traces it into a 48-view light-field quilt for Looking Glass light-field panels, or into 2-D video for Hololuminescent displays. A third output -- a 23-view sweep for LitiHolo's desktop hologram printer -- is in development. About the image

Latest news

v0.10.1 (2026-08-31). Documentation gets a real home: the docs/*.md guides now build into a GitHub Pages site at flux-frontiers.github.io/quiltwright, with an mkdocstrings API reference generated straight from the package's own docstrings, so it can't drift from the code. docs/architecture.md replaces the module-split proposal it outgrew -- the split it planned had already landed -- and docs/cli.md is a full flag reference for every command. The repository itself moved under the Flux-Frontiers org, matching the rest of the fleet.

This cut also carries bj_holo_2026.pov -- "DNA Under Glass" with a bell jar that finally refracts rather than just tinting, via a Fresnel reflection and a real wall thickness -- and a fix for the vitrine exhibits, which had been rendering at a 71.4-degree lens instead of the 44 degrees they are composed at.

Full history: CHANGELOG.md and releases.

What it's for

     scene sources                  quiltwright                  outputs

  PyVista / VTK  -----+        +------------------+        +-->  LFD  light-field panels
   (WaveRider, TVB)   |        |  off-axis views  |        |          multi-view quilts
                      +------->|  depth budget    |------->+-->  HLD  hololuminescent
  POV-Ray  -----------+        |  quilt assembly  |        |          2-D video
   (pypdb2pov, PyMOL) |        |  view sweeps     |        +-->  LitiHolo  hogel sweeps
                      |        +------------------+                       (in development)
  Blender / meshes ---+
   (.blend, glTF, USD, OBJ)

Three backends share one assembler:

render_cycles_quilt_from_plotter() takes the same PyVista plotter render_quilt() does and path-traces it instead. WaveRider, The Virtual Brain, PyVista example datasets, quiltwright.povgen, and a plain .pov file on disk all feed the same path.

Two display technologies. Light-field displays (LFD -- Portrait, Go, 16"/27"/32"/65") consume quilts: N views tiled into one image. quiltwright.lfd targets those. Hololuminescent displays (HLD -- 16"/27"/86") play ordinary 2-D video behind a fixed holographic optic and need dark-field styling rather than parallax; that is quiltwright.hld.

A third output is in development: render_pov_views() plus LITIHOLO_SWEEP write a 23-view single-row sweep for LitiHolo's desktop hologram printer. Nothing has yet passed through a printer's software; docs/lfd.md records what remains open.

Off-axis, not toe-in

Each view must use an off-axis (asymmetric-frustum) projection: the camera slides sideways while continuing to face the same direction, with the image plane sheared back onto the original view axis.

The intuitive alternative is to swivel each camera to keep the subject centered. This "toe-in" approach introduces vertical parallax and keystone distortion, so the display cannot fuse the views: you get ghosting instead of depth. It is the single most common way light-field renders go wrong, and it produces output that looks perfectly plausible in any individual frame.

Install

pip install quiltwright                 # core: quilt geometry + Bridge control
pip install "quiltwright[viz]"          # + PyVista/VTK rendering backend
pip install "quiltwright[video]"        # + a bundled ffmpeg for video encoding
pip install "quiltwright[molecules]"    # + PDB and mmCIF, via pypdb2pov

Requires Python 3.12 or 3.13. Core depends only on numpy, pillow, and click.

POV-Ray, Blender, PyMOL, ffmpeg, and Looking Glass Bridge are external binaries, not pip dependencies. Poetry groups, from-source install, and the rest of the stack are in the installation guide.

Quick start

import pyvista as pv
from quiltwright import QUILT_PRESETS, render_quilt, save_quilt

p = pv.Plotter(off_screen=True)
p.add_mesh(pv.ParametricTorus())
spec = QUILT_PRESETS["portrait"]
save_quilt(render_quilt(p, spec), "torus", spec)   # -> torus_qs8x6a0.75.png

POV-Ray, Cycles, casting to Bridge, and hologram-printer sweeps: docs/usage.md. Shell targets and the CLI: docs/shell.md.

Driving it from the shell

The Makefile covers the bundled 1993-99 scenes. The quiltwright CLI covers hardware (cast, weave, wallpaper, bridge) and arbitrary input (mesh, cartoon, probe). Worked exhibits stay in scripts/. Full tour: docs/shell.md.

make gallery                    # every reference still -> gallery/
make quilts                     # every bundled quilt, measured budgets dialled in
make preview-museum             # quarter-size, for iterating on composition

quiltwright cast renders/quilts/bell-jar-holo_qs8x6a1.77778.png
quiltwright bridge status       # is Bridge actually able to draw?
quiltwright weave ... && quiltwright wallpaper ...   # the no-Bridge path
quiltwright cartoon 2omf.cif.gz ompf_cartoon.inc     # molecular ribbon, via PyMOL
quiltwright mesh model.glb                           # any mesh file, camera auto-framed
quiltwright probe scene.pov --eye 0 35 -95 --aim 0 18 0   # measure its depth range

python scripts/make_exhibit.py 7AHL --quilt          # fetch -> convert -> render

RENDER_THREADS defaults to ncpu - 2. When the glass stays black, run quiltwright bridge status first -- Bridge keeps answering HTTP after crashing internally.

The depth budget

Whether a hologram fuses comes down to adjacent-view disparity: how far a feature moves between neighboring views. Roughly 4-5 px is the practical ceiling; past ~8 px, hard edges ghost. The arithmetic API is in docs/usage.md; the results worth knowing before you frame a shot -- each derived in docs/povray.md:

• Content at the focal plane has zero disparity -- it is welded to the glass.
• The focal plane belongs at the harmonic mean of the measured depth range, not the midpoint; near content is the expensive side.
• A narrower field of view increases disparity. The widely repeated "~14 degree FOV" advice is specific to object-centric scenes; applied to an interior it makes ghosting worse.
• Interiors have a fourth trap no arithmetic warns about: the camera sweep can run through a wall. Measure sweep clearance.
• The depths themselves are measured, not guessed -- quiltwright probe sweeps an opaque plane along the view axis and reports where content actually begins and ends.

Supported devices

QUILT_PRESETS carries the official quilt settings for Portrait, Go, and the 16"/27"/32"/65" panels in both orientations. The 16" Gen3 Landscape entry is verified against what Bridge reports for real hardware -- see docs/usage.md.

Documentation

Testing

poetry install --with viz,dev    # or: pip install -e ".[viz]" && pip install pytest
pytest

Tests skip when their backend is absent. Headless CI: xvfb-run -a pytest. Layered install and skip conditions are in the installation guide.

The pipelines this serves

• WaveRider -- manifold-aware geometric ML. Its voxel and manifold visualizer builds the PyVista scenes that render_quilt() sweeps.
• pypdb2pov -- PDB and mmCIF to POV-Ray. Reads mmCIF and compressed input, ships the atom textures inside the package, and imports, so a conversion and a quilt render fit in one script. Scenes are byte-identical to pdb2pov, the 1993 C original.
• proteusPy -- protein disulfide bond analysis and rendering.

Citation

If you use Quiltwright in your work, please cite it. Citation metadata is in CITATION.cff; GitHub's "Cite this repository" button generates BibTeX/APA from it, and the DOI badge above resolves to the archived release on Zenodo.

@software{suchanek_quiltwright,
  author  = {Suchanek, Eric G.},
  title   = {Quiltwright: Holographic Output for Looking Glass Displays},
  url     = {https://github.com/Flux-Frontiers/quiltwright},
  doi     = {10.5281/zenodo.22180300},
  version = {0.10.1},
  year    = {2026}
}

License

BSD 3-Clause. See LICENSE.