Render commands

Renders need a browser; films also need the local renderer. Read Rendering for the three tiers.

With no browser installed, a render in a terminal offers once to download Chromium into Puni's own cache (PUNI_BROWSERS_PATH, else $XDG_CACHE_HOME/puni/browsers, else ~/.cache/puni/browsers), naming what it costs on disk. --yes accepts without asking. A run that is not interactive, or has CI set, or asked for --json, is never asked and fails exactly as it did before, unless --yes is given, which downloads without asking in any of these cases. A refusal is remembered only for that run. A browser you name yourself, with --browser or the host's own variable, is an instruction: if that path is empty the render says so rather than fetching something else.

#render png

A still. Samples 0 is the studio raster; 1 to 1024 is the path tracer.

#Run render png

puni render png --file scene.json --output still.png --time 1 --width 1200 --height 1200 --json

A scene holding a stylised surface (the flat and toon skins, ink outlines, tone mapping off, flat shading) draws in PNG and film only: --samples above 0 (the path tracer) is refused with STYLISED_SKIN_PATH_TRACE.

#render glb

The sampled scene as glTF with materials, part IDs and interface textures, in metres. A scene holding a stylised surface (the flat and toon skins, ink outlines, tone mapping off, flat shading) is refused with STYLISED_SKIN_GLB; facets on a round form are geometry and export.

#Run render glb

puni render glb --file scene.json --output scene.glb --time 1 --json

#render usdz

The sampled scene for RealityKit. A scene holding a stylised surface is refused with STYLISED_SKIN_USDZ.

#Run render usdz

puni render usdz --file scene.json --output scene.usdz --json

#render view

The still render png draws, made by a render worker instead of this machine. For a machine with no GPU, or none the caller may use.

#Run render view

puni render view --file scene.json --output view.png --remote --width 640 --json

A hosted saved project uses puni render view --id PROJECT --output view.png --remote. Every attempt receives an ID. If delivery or the local write fails, follow the printed --recover ID instruction; recovery returns the original retained bytes even after the project changes, or refuses without another render or debit. An identical command without --request-id reuses a still-valid receipt for free and binds its new recovery ID to those bytes. Changed inputs or expired bytes start a fresh attempt. Terminal rows last 365 days; retained billing debits prevent paid IDs from ever being charged again.

#render compare

How close the scene stands to a picture you supply (silhouette overlap, structure inside that outline, proportion and colour), against a floor. It renders a measurement-only transparent environment (no floor or its shadow), takes the subject mask from alpha rather than colour, then scores the pair with the same card the hosted puni_compare_reference tool reports, so one pair reads the same through both doors. The saved environment is unchanged. The result names this cutout in measurement. --reference reads a local image file; hosted MCP also accepts owner-scoped asset URIs and guarded public HTTPS image URLs.

It is a read. Nothing is saved, and the reference is never an instruction: it is measured, not followed. A transparent reference is measured over white, so a sticker with no background scores the same here as through the hosted tool.

The numbers are a gate, not a verdict. Above the floor the eyes rule; below it the work is a mechanics milestone, not a proof. silhouette is the score the floor tests, and the floor is 0.85. structure sits beside it because an outline can be right while the insides are wrong (an aliased texture, a lost band), and silhouette overlap alone cannot see that. Structure is read only where either object has ink. A pass also needs the colour to be right. Colour fails when both of its terms are wrong at once, over the whole object (colour) or region by region (placement). A right outline with the right colours in the wrong places still fails.

A render or reference with no subject in it is refused with LIKENESS_RENDER_EMPTY or LIKENESS_REFERENCE_EMPTY and exit 2, before any score is printed. A subject is ink that holds together. Most of the ink the card would measure has to stand in connected pieces at least 2.5% of the picture's longer side: 16 pixels at the 640 measure, never fewer than 8. Specks are refused however widely they spread; a thin wire or ring is kept. A scene with nothing visible to draw is refused as RENDER_SCENE_EMPTY before anything is rendered.

#Run render compare

puni render compare --file scene.json --reference picture.png --json

Exit is zero above the floor and non-zero below it, so the command can gate a script without parsing its output. The whole comparison stops at --timeout, 120 seconds by default, with PUNI_TIMEOUT. The deadline starts before the first file is read, so a stalled reference, scene or runtime read is held to it too. An interrupt stops it with PUNI_CANCELLED. Either way the browser it started is closed, and a browser that has not closed five seconds later is killed.

#render film

Every frame from zero, with the scene's sound, encoded by the local renderer.

#Run render film

puni render film --file scene.puni.json --output scene.mp4 --width 640 --height 640 --json

Back to the command line index for every group.