Quiltwright

Holographic output for scientific visualisation.

Eric G. Suchanek, PhD — Flux-Frontiers

Quiltwright is the last stage of two scientific rendering pipelines. It takes scenes that already exist — geometric ML manifolds from WaveRider, molecular structures from pdb2pov — and puts them on holographic hardware, in glasses-free depth.

A career in structural biophysics, arranged as exhibits: B-DNA and Z-DNA under bell jars, Ras and a drug-discovery pipeline 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 display on Looking Glass Light Field or Hololuminescent displays and Litiholo holographic printers (in development). About the image →

What it's for

     scene sources                  quiltwright                 displays

  PyVista / VTK  ─────┐        ┌──────────────────┐        ┌──→  LFD  light-field panels
   (WaveRider)        ├───────→│  off-axis views  │───────→┤          multi-view quilts
                      │        │  depth budget    │        │
  POV-Ray  ───────────┘        │  quilt assembly  │        └──→  HLD  hololuminescent
   (pdb2pov)                   └──────────────────┘                   2-D video

Two scene sources. WaveRider's voxel and manifold visualiser builds PyVista/VTK scenes in memory; render_quilt() sweeps them. pdb2pov turns PDB files into POV-Ray molecular scenes on disk, some of them decades old; render_pov_quilt() ray-traces them, appending a camera per view and modifying nothing. The two backends meet at a shared, renderer-agnostic assembler.

Two display technologies, which are easy to confuse because one company sells both. Light-field displays (LFD — Portrait, Go, 16″/27″/32″/65″) are lenticular panels that consume quilts: N views of the same scene tiled into one image, fused optically into real depth. Hololuminescent displays (HLD — 16″/27″/86″) play ordinary 2-D video behind a fixed holographic optic, and need styling rather than parallax — dark field, high contrast, generous safe margins. quiltwright.lfd targets the first; quiltwright.hld the second.

The shared middle is what makes this a package rather than two scripts: quilt geometry and device presets, the depth-budget arithmetic that decides whether a scene will fuse before you spend an hour rendering it, filename conventions Looking Glass software parses, video encoding, and direct Bridge control.

That middle also serves consumers that are not panels at all: render_pov_views() writes the sweep as separate frames, and sweep_spec() / LITIHOLO_SWEEP give the single-row layout a hologram printer's prime view count needs and a quilt grid cannot express — so one scene feeds a light-field panel and a hologram printer without being rebuilt. Nothing has been through a printer's software yet, so the claim is a sweep matching the published specification rather than verified compatibility; docs/lfd.md records what is still open.

The part that is easy to get wrong

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 centred. That is "toe-in", and it 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. Quiltwright does the off-axis projection correctly in both backends, and gives you the arithmetic to know in advance whether a scene will fuse.

Install

pip install quiltwright              # core: quilt geometry + Bridge control
pip install "quiltwright[viz]"       # + PyVista/VTK rendering backend

The POV-Ray backend needs a povray binary on PATH rather than a Python package:

brew install povray                  # macOS

For the complete stack — renderers, ffmpeg, Looking Glass Bridge, pdb2pov — see the installation guide.

Quick start

From a PyVista scene

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

From a POV-Ray scene

The scene file is never modified — each view wraps it with #include and appends one camera.

from quiltwright import QUILT_PRESETS, PovCamera, render_pov_quilt, save_quilt

camera = PovCamera(location=(15, 20, 6), look_at=(44, 19.2, 45.1), fov=53.13)
spec = QUILT_PRESETS["16-landscape"]
quilt = render_pov_quilt("pov-scenes/museum/museum.pov", spec, camera,
                         include_paths=["pov-scenes/myinclude", "pov-scenes"])
save_quilt(quilt, "museum", spec)

The museum scene above ships in pov-scenes/, and scripts/render_museum_hologram.py renders it end-to-end with a measured depth budget — the worked case study in docs/povray.md, and the scene itself in docs/about-the-image.md.

Two more scene trees ship alongside it — the bell-jar DNA still lifes the museum's pedestals were built from, and porin's β-barrel over water. What is in each, and how to render them directly, is in pov-scenes/README.md.

Send it to the display

from quiltwright import cast_quilt, pause_quilt, resume_quilt, stop_quilt

cast_quilt("museum_qs8x6a1.77778.png", spec)   # needs Looking Glass Bridge >= 2.2

Saved filenames carry the _qs<cols>x<rows>a<aspect> suffix that Looking Glass Studio and Bridge parse, so playback settings are detected automatically.

The depth budget

Whether a hologram fuses comes down to adjacent-view disparity: how far a feature moves between neighbouring views. Roughly 4–5 px is the practical ceiling; past ~8 px, hard edges ghost.

from quiltwright import QUILT_PRESETS, focal_distance_for_range, view_disparity

# Put the focal plane where near and far content are equally penalised.
focal = focal_distance_for_range(near=31, far=96)       # harmonic mean, not midpoint
view_disparity(QUILT_PRESETS["16-landscape"], fov=53.13,
               focal_distance=focal, depth=31)          # -> px between adjacent views

Those two depths are measured, not guessed — scripts/measure_depth_range.py sweeps an opaque plane along the view axis and reports where a scene's content actually begins and ends.

Three results worth knowing before you frame a shot:

• Content at the focal plane has zero disparity — it is welded to the glass.
• The focal plane belongs at the harmonic mean of the depth range, not the midpoint. Disparity is asymmetric in depth, and near content is the expensive side.
• A narrower field of view increases disparity. Zooming in magnifies the scene and the parallax with it. The widely repeated "use ~14° FOV" advice is specific to object-centric scenes; applied to an interior it makes ghosting worse.

For interiors there is a fourth trap that no arithmetic will warn you about: the camera sweep physically travels focal_distance × tan(cone/2) sideways, and in a room that path can run through a wall. See docs/povray.md.

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.

from quiltwright import QUILT_PRESETS
QUILT_PRESETS["16-landscape"]      # 8x6 views, 7680x4320, aspect 1.7778

Documentation

Testing

pip install -e ".[viz]" && pip install pytest
pytest

Rendering tests skip cleanly on machines with no OpenGL stack, and the POV-Ray tests skip when no povray binary is present. Under a headless CI runner, use xvfb-run -a pytest to exercise them.

The pipelines this serves

• WaveRider — manifold-aware geometric ML. Its voxel and manifold visualiser builds the PyVista scenes that render_quilt() sweeps.
• pdb2pov — PDB to POV-Ray converter, written in C in 1993 and still building from a fresh clone. It produced the molecular models in the image above, and still feeds the POV-Ray backend.
• 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/suchanek/quiltwright},
  doi     = {10.5281/zenodo.21798503},
  version = {0.3.0},
  year    = {2026}
}

License

BSD 3-Clause. See LICENSE.