Declarative raytracing in Typst

A Typst plugin that embeds the POV-Ray 3.8 ray-tracer, compiled to WebAssembly via Emscripten. Write a POV-Ray scene in your .typ document and get a rendered PNG.

Feel free to read the documentation to see more examples and options.

#import "@preview/povrayst:0.1.0": pov, render
#show raw.where(lang: "povray"): pov

```povray
camera { location <0, 2, -5> look_at 0 }
light_source { <4, 6, -4> rgb 1.2 }
sphere { 0, 1 pigment { rgb <1, 0.4, 0.15> } }
```

// Or load from a file:
#render(read("scene.pov"))

pov(code, ..kwargs) accepts the scene as a raw block or a string; render(scene, ..kwargs) accepts a string only (use it with read()). Both take the same ~25 keyword arguments (width, height, quality, antialiasing, gamma, tracing depth, partial-render section, includes, ...).

The package ships povray.sublime-syntax covering the full POV-Ray SDL, exposed through the highlight show rule. Apply it once at the top of your document:

#import "@preview/povrayst:0.1.0": pov, render, highlight
#show: highlight
#show raw.where(lang: "povray"): pov

After this, every fenced ```povray ``` block in the document (including the ones rendered via the pov show rule above) is highlighted by Typst's syntect integration — no extra file to copy.

Every keyword argument to render() / pov(), its default, and the POV-Ray option it maps to (verbatim from POV-Ray's .ini / command-line reference). Passing none suppresses the flag so POV-Ray's own default stays in force. The plugin always sets +FN (PNG), -D (no display), and Work_Threads=1.

Gallery render times under native typst compile on an AMD Ryzen 9 9950X (Zen 5, 5.7 GHz), median of 3 samples:

• No filesystem: #include, image_map, height_field, bump_map of external files won't work—the VFS returns null on all reads. #include is handled by Typst-side text expansion (see expand-includes in pkg/povray.typ), but image maps have no workaround yet.
• Single-threaded: Work_Threads=1 always. Multi-core parallelism isn't possible under wasmi.
• One output frame: animation options are forwarded but only the last PNG is captured.
• Missing include hangs: if a scene references an #include name not in the includes dict, POV-Ray's Error() function is a no-op (throw-stripped) so the parser loops forever instead of exiting cleanly.

Pre-built pkg/povray.wasm is shipped with the package, so end users don't need to build anything. For build instructions, the patch tour, and the POV-Ray version details, see NOTES.md.

AGPL-3.0-or-later (same as POV-Ray 3.8).