CLI reference

Installed as: quiltwright, core-only (numpy, pillow, click) -- no extra needed just to run --help. Source: src/quiltwright/cli/

Most commands operate on a quilt, which is where the backends have already met: a manifold swept out of PyVista and a molecular scene ray-traced from POV-Ray produce the same artifact, and cast / weave / wallpaper / dynamic treat them identically. Three commands are a whole pipeline rather than a step after one -- mesh, cartoon, probe -- and none of them is a generic renderer for the bundled scenes; those stay in scripts/, covered in shell.md.

This page is the flag-by-flag reference for every command. For the why behind each one, see shell.md.

quiltwright [OPTIONS] COMMAND [ARGS]...

Option	Effect
--version	Print the installed version and exit
--help	Show help and exit -- also works on any subcommand

Command	For
bridge	Inspect and restart Looking Glass Bridge
cartoon	Convert a structure into a POV-Ray cartoon include
cast	Show a saved quilt on the connected Looking Glass
dynamic	Pack stills into a macOS Dynamic Desktop HEIC
mesh	Auto-frame a mesh file and render it as a quilt
probe	Measure a scene's near and far depth by plane sweep
wallpaper	Set a woven frame as the desktop picture of its own panel
weave	Weave a quilt into a native pre-lensed frame for one panel

---

bridge

quiltwright bridge COMMAND [ARGS]...

Inspect and restart Looking Glass Bridge.

quiltwright bridge status    # is it actually able to draw?
quiltwright bridge reset     # kill and relaunch a wedged daemon

bridge status

quiltwright bridge status [OPTIONS]

Reports whether Bridge is running, responsive, and seeing a panel. Exits non-zero if Bridge is unusable, so this can gate a cast in a script. Bridge keeps its HTTP port open and keeps issuing session tokens after crashing internally, so a cast can report success at every step against a daemon that will never draw -- status checks the port, the session, the device list and whether any device is actually a Looking Glass, then gives a verdict.

Option	Default	Effect
--bridge-url TEXT	http://localhost:33334	Bridge HTTP API base URL
--timeout FLOAT	5.0	Per-request timeout. A wedged Bridge hangs rather than refusing, so this is what separates "slow" from "dead"

bridge reset

quiltwright bridge reset [OPTIONS]

Terminates Bridge and starts it again. Bridge's own menu restart spawns a replacement that inherits the wedge, which is why this kills the processes outright. Anything currently playing on the panel stops.

Option	Default	Effect
--no-relaunch	off	Terminate Bridge without starting it again
--wait FLOAT	20.0	Seconds to wait for the relaunched daemon to answer
--bridge-url TEXT	http://localhost:33334	Bridge HTTP API base URL

---

cartoon

quiltwright cartoon [OPTIONS] [SOURCE] [OUTPUT]

Converts a structure into a POV-Ray cartoon include, via headless PyMOL. SOURCE is anything PyMOL can load -- .pdb, .cif, .cif.gz. OUTPUT is the .inc to write. See pdb2pov.md for the object-only contract this writes to.

Option	Default	Effect
--rep TEXT	cartoon	Representation. cartoon and surface are what pdb2pov cannot draw; sticks and spheres duplicate its -b and -v
--color TEXT	spectrum	spectrum ramps rainbow along the chain; any PyMOL color name is flat; none keeps PyMOL's own coloring
--selection TEXT	polymer	PyMOL selection to show. The default drops waters and ligands
--assembly TEXT	1	Biological assembly. 1 is the biological unit -- ferritin arrives as a 24-mer rather than a 24th of itself. "" gives the asymmetric unit
--transparency FLOAT (0.0-1.0)	0.0	Exports as POV-Ray transmit, which is flat see-through rather than refractive
--surface-quality INTEGER	--	PyMOL surface_quality; lower is coarser. Worth setting negative for a large --rep surface, which otherwise runs to millions of triangles
--name TEXT	output stem	POV-Ray identifier to declare. Defaults to the output stem, made legal (a leading digit gains an underscore)
--raw	off	Skip coalescing and keep PyMOL's one mesh per triangle. For comparing against the raw export; several times larger
--check	off	Report how PyMOL can be reached and exit, converting nothing

quiltwright cartoon 2omf.cif.gz ompf_cartoon.inc   # a molecular ribbon, via PyMOL
quiltwright cartoon --check                         # is PyMOL reachable, and by which route?

---

cast

quiltwright cast [OPTIONS] [QUILT]

Shows a saved quilt on the connected Looking Glass. QUILT is a quilt PNG on this machine, normally one written by save_quilt() or make quilt-<name>, whose _qs<cols>x<rows>a<aspect> filename suffix supplies the tiling automatically.

Requires Looking Glass Bridge >= 2.2 running on the machine the panel is plugged into. Quit Looking Glass Studio first -- it holds the display exclusively, and Bridge will report success while the glass stays black.

Option	Default	Effect
--preset [16-landscape\|16-portrait\|27-landscape\|27-portrait\|32-landscape\|32-portrait\|65\|go\|portrait]	--	Quilt tiling grid and aspect, by device preset name
--grid COLSxROWS	from filename	Quilt tiling grid, explicit (e.g. 8x6); defaults to parsing the _qs<cols>x<rows>a<aspect> filename suffix
--aspect FLOAT	from filename	Tile aspect, overriding the filename's. Rarely needed -- a value disagreeing with the panel is letterboxed by it
--head INTEGER	-1	Bridge head index to play on. -1 lets Bridge choose, which is right until it picks an ordinary monitor; run --check for the list
--playlist TEXT	a fresh name per cast	Bridge playlist name. Leave it unset: a fresh name is what replaces the picture. Reusing a name Bridge already holds adds to that playlist, and the panel keeps showing the first quilt
--bridge-url TEXT	http://localhost:33334	Bridge HTTP API base URL
--check	off	List the output devices Bridge can see and exit without casting. The first thing to run when the glass stays black

# Cast a rendered quilt; tiling comes from the filename
quiltwright cast renders/quilts/bell-jar-holo_qs8x6a1.77778.png

# Which displays can Bridge see? Run this first when nothing appears
quiltwright cast --check

# Pin the panel when Bridge picks an ordinary monitor
quiltwright cast quilt.png --head 1

# A quilt whose filename carries no _qs suffix
quiltwright cast plain.png --grid 8x6 --aspect 1.77778
quiltwright cast plain.png --preset 16-landscape

---

mesh

quiltwright mesh [OPTIONS] SOURCE

Auto-frames the mesh file SOURCE and renders it as a quilt through Blender Cycles -- the only command here that needs no scene of ours at all. See mesh-import.md.

Option	Default	Effect
--device [16-landscape\|16-portrait\|27-landscape\|27-portrait\|32-landscape\|32-portrait\|65\|go\|portrait]	portrait	Target display, which sets the quilt grid, size and view cone
--view-cone FLOAT	device's, capped at 35	View cone in degrees. Defaults to the device's own, capped at 35 so a wide panel does not overrun the disparity budget: 16-landscape declares 50. An explicit value is used as given
--lighting TEXT	studio	Light rig for a mesh that carries none: one of soft, studio, sky, or a path to an .hdr/.exr environment map
--fov FLOAT	14.0	Vertical field of view in degrees. Object-centric, so narrow
--view-direction X Y Z	0.0 -1.0 0.0	Direction from the object's center to the eye (+z is up)
--margin FLOAT	1.2	Framing headroom beyond a tight fit; 1.0 is exactly tight
--samples INTEGER	128	Cycles samples per pixel
--view-transform TEXT	Standard	OCIO view transform (Standard, AgX, Filmic, ...); see cycles.md
--compute [auto\|gpu\|cpu]	auto	Cycles compute device. auto prefers a GPU, Metal first
--preview	off	Quarter-size quilt, for iterating on framing
--still	off	One center view as a flat image, at the device's aspect, instead of a quilt
--out TEXT	source name	Output stem; defaults to the source name under renders/quilts/ (or gallery/ with --still)
--cast	off	Send the result to Looking Glass Bridge

quiltwright mesh model.glb
quiltwright mesh scan.fbx --lighting sky --still
quiltwright mesh asset.obj --device 27-portrait --samples 256 --cast
quiltwright mesh statue.ply --view-direction 0.5 -1 0.3 --fov 20

---

paraview

quiltwright paraview [OPTIONS] [STATE]

Renders the ParaView state file STATE (a .pvsm) as a quilt, by sweeping the render view's camera inside ParaView's own pvpython. The session's pipeline, color maps and camera all come with it. The depth budget is printed before the sweep starts. See paraview.md.

Option	Default	Effect
--device [16-landscape\|16-portrait\|27-landscape\|27-portrait\|32-landscape\|32-portrait\|65\|go\|portrait]	16-landscape	Target display, which sets the quilt grid, size and view cone
--fov FLOAT	14.0	Vertical field of view in degrees; the camera is dollied back to keep the state's framing. 0 keeps the state's own FOV
--zoom FLOAT	--	Dolly factor after framing; above 1 fills more of each tile, which is what drives perceived depth
--view-cone FLOAT	device's, capped at 35	View cone in degrees. Defaults to the device's own, capped at 35 so a wide panel does not overrun the disparity budget: 16-landscape declares 50. An explicit value is used as given
--orientation-axes	off	Keep ParaView's corner axes widget. Hidden by default: it is pinned to the screen, so it would sit on the glass in every view
--preview	off	Quarter-size quilt, for iterating on framing
--still	off	One center view as a flat image, at the device's aspect, instead of a quilt
--keep-views DIR	--	Directory to keep the per-view PNGs and camera.json probe in
--out TEXT	state name	Output stem; defaults to the state name under renders/quilts/ (or gallery/ with --still)
--cast	off	Send the result to Looking Glass Bridge
--check	off	Report where pvpython was found and exit, rendering nothing

quiltwright paraview session.pvsm
quiltwright paraview session.pvsm --still
quiltwright paraview session.pvsm --device 27-portrait --zoom 1.4 --cast
quiltwright paraview --check

---

playlist

quiltwright playlist [OPTIONS] SOURCES...

Plays several quilts on the connected Looking Glass as one playlist that advances on a timer and loops. SOURCES are quilt files, played in the order given, or folders. A folder holding a playlist.json is read the way Looking Glass Studio 1.x keeps a playlist -- a folder of media and a list of {"filename": ...} entries -- and plays in that order, so a Studio playlist folder plays unchanged. Any other folder plays its quilt files by name.

Each quilt's tiling comes from its own _qs<cols>x<rows>a<aspect> filename suffix, so one playlist can mix grids. A file without the suffix is refused by name rather than guessed at.

The whole playlist is built before it starts playing, which is what makes it advance: quilts inserted into a playlist that is already playing never show. Each run plays a fresh playlist, so it replaces whatever is on the panel.

Option	Default	Effect
--duration FLOAT	20.0	Seconds each quilt shows before the next
--head INTEGER	-1	Bridge head index to play on. -1 lets Bridge choose; quiltwright cast --check lists them
--once	off	Play through once instead of looping
--playlist TEXT	a fresh name	Bridge playlist name. Leave it unset: a fresh name is what replaces the picture
--bridge-url TEXT	http://localhost:33334	Bridge HTTP API base URL

# Two quilts, 10 seconds each, on the panel at head 1
quiltwright playlist bdna-go_qs11x6a0.5625.png bell-jar-portrait_qs11x6a0.5625.png --duration 10 --head 1

# A Looking Glass Studio playlist folder, in its own order
quiltwright playlist ~/Documents/HoloPlayStudio/"EGS Science Go"

# Every quilt in a folder, by name, once through
quiltwright playlist renders/quilts/go --once

# The Looking Glass Go set, from the Makefile
make playlist-go PANEL_HEAD=1

---

probe

quiltwright probe [OPTIONS] SCENE

Measures SCENE's near and far depth by plane sweep -- the measurement every POV-Ray depth budget starts from: it slides an opaque plane along the view axis and reports where content actually begins and ends, which is what focal_distance_for_range() wants. Probe through the camera you will render with, and at +Q8 or above -- below that POV-Ray disables transparency and a room reports no windows at all. On a scene whose backdrop runs to the horizon the sweep never closes and the printed far is the end of it; the command says so, and --rows prints the curve to fit the knee from.

Option	Default	Effect
--eye X Y Z	required	Camera position to probe through, in scene units
--aim X Y Z	required	Camera look-at point
--fov FLOAT	53.13	Vertical field of view in degrees. The default is POV-Ray's own unit direction/up lens, 2*atan(0.5)
--min-distance FLOAT	1% of --max-distance	Near end of the sweep. A scene composed far from its eye -- porin sits 1100 units out -- wants its probes where its content is, not 200 of them in front of it
--max-distance FLOAT	400.0	Far end of the sweep, before the one at infinity
--probes INTEGER	200	Number of planes between the two distances
--include-path DIR	--	Extra #include directory; repeatable. The scene's own is automatic
--width INTEGER	320	Probe frame width
--height INTEGER	180	Probe frame height
--quality INTEGER	11	POV-Ray +Q. Below 8 it disables transparency and glass reads solid
--pov-arg ARG	--	Extra POV-Ray argument, e.g. +MV3.1 for a scene with no #version pragma of its own; repeatable
--rows	off	Print the whole curve, one distance per line

quiltwright probe pov-scenes/bell_jar/bj.pov --eye 0 35 -95 --aim 0 18 0
quiltwright probe pov-scenes/porin/3porin.pov --eye 0 0 -1100 --aim 0 0 0 \
    --include-path pov-scenes/myinclude --min-distance 700 \
    --max-distance 1600 --pov-arg +MV3.1

---

dynamic

quiltwright dynamic [OPTIONS]

Packs finished stills into a macOS Dynamic Desktop .heic. macOS picks the frame from sun position, wall-clock time, or Light/Dark appearance -- with no agent of ours running. Install the file with wallpaper.

This is not POV-Ray's clock. That identifier is POV-Ray's animation parameter (+K). Real time of day lives in the HEIC metadata, which macOS reads. POV-Ray's contribution is render_pov_quilt(..., lighting="light") or sun=(altitude, azimuth) to produce the stills.

Woven _native_ frames always encode lossless 4:4:4. Lossy HEVC 4:2:0 would mix the per-channel views and destroy the hologram. Encoding needs the heic extra (pip install 'quiltwright[heic]').

Option	Default	Effect
--appearance LIGHT DARK	--	Two stills: light appearance, then dark
--solar FILE.json	--	JSON array with altitude / azimuth per still (wallpapper shape)
--time FILE.json	--	JSON array with time (HH:MM or HH:MM:SS) per still
-o, --output PATH	--	Output .heic. Required unless --dump
--lossless	off (on for _native_)	Force lossless 4:4:4
--lossy	off	Force lossy HEVC. Refused for woven frames
--dump PATH	--	Print apple_desktop metadata from an existing HEIC

quiltwright dynamic --appearance day_native_LKG-J00332.png night_native_LKG-J00332.png \
    -o scene.heic
quiltwright dynamic --solar solar.json -o scene.heic
quiltwright wallpaper scene.heic

Give exactly one of --appearance, --solar, or --time.

---

wallpaper

quiltwright wallpaper [OPTIONS] [WOVEN]

Sets a woven frame as the desktop picture of its own panel. WOVEN is a native-resolution frame from quiltwright weave -- already interleaved for one panel, so displayed 1:1 it fuses into a hologram with no Looking Glass software running at all. The panel is identified from the _native_<serial> filename and matched against each desktop's display name.

The frame is copied into a stable pictures folder first, because macOS stores wallpaper as a path: pointing the desktop into renders/ means the panel goes blank the next time that directory is cleaned.

Option	Default	Effect
--display TEXT	serial in filename	Panel serial to target (e.g. LKG-J00332)
--desktop INTEGER	--	Target desktop by 1-based index instead of by serial. Use --list to see them
--dir DIRECTORY	~/Pictures/LKG-wallpapers	Where to install the frame
--no-install	off	Set the file where it lies instead of copying it. Convenient, but the desktop breaks if that path is later cleaned
--list	off	List the desktops and their current pictures, then exit

# Weave, then hang it on the panel it was woven for
quiltwright weave renders/quilts/bell-jar-holo_qs8x6a1.77778.png \
    --cal ~/Pictures/LKG-wallpapers/visual.json
quiltwright wallpaper bell-jar-holo_native_LKG-J00332.png

# What is on each desktop right now?
quiltwright wallpaper --list

# Target explicitly, when the filename carries no serial
quiltwright wallpaper frame.png --display LKG-J00332
quiltwright wallpaper frame.png --desktop 2

# Leave it where it is (it will break if renders/ is cleaned)
quiltwright wallpaper renders/quilts/x_native_LKG-J00332.png --no-install

---

weave

quiltwright weave [OPTIONS] QUILT

Weaves QUILT into a native pre-lensed frame for one panel -- interleaved for display 1:1, most usefully as its desktop wallpaper, with no Bridge process required. See docs/lfd.md and quiltwright.weave for the math.

Option	Default	Effect
--cal FILE	required	Path to the panel's visual.json calibration file
--preset [16-landscape\|16-portrait\|27-landscape\|27-portrait\|32-landscape\|32-portrait\|65\|go\|portrait]	--	Quilt tiling grid, by device preset name
--grid COLSxROWS	from filename	Quilt tiling grid, explicit (e.g. 8x6); defaults to parsing the _qs<cols>x<rows> filename suffix
-o, --output FILE	<quilt stem>_native_<serial>.png	Output path
--invert	off	Reverse the view order if the fused result reads inside-out

quiltwright weave renders/quilts/bell-jar-holo_qs8x6a1.77778.png --cal visual.json