Maquette is a Typst plugin that renders 3D models directly inside your documents — no screenshots, no external tools, no manual re-exports when you tweak the camera angle.

Maquette takes STL, OBJ, and PLY files and turns them into SVG or PNG images at compile time, right inside the Typst pipeline. Point a camera, set up lighting, pick a shading model, and the result lands in your PDF. Change a parameter, recompile, done. This makes it practical to embed technical 3D illustrations in engineering reports, research papers, and documentation without maintaining a separate asset pipeline.

Everything runs as a single WASM plugin (~460 KB), with focus on speed.

Check the documentation to see examples of all the features.

#import "@preview/maquette:0.1.0": render-obj
#let cube = read("examples/data/bunny.obj")
#render-obj(cube)

Rendering Techniques

Documentation

See examples/documentation.pdf for a full walkthrough with examples, or compile it:

make demo

Functions

render-stl / render-obj / render-ply

#render-stl(stl-data, config, width: auto, height: auto, format: "png")
#render-obj(obj-data, config, width: auto, height: auto, format: "png")
#render-ply(ply-data, config, width: auto, height: auto, format: "png")

Renders a 3D model. Data must be read with encoding: none (required for binary STL/PLY, optional for OBJ). Config is a JSON string via json.encode((...)). Set format: "svg" for vector output.

get-stl-info / get-obj-info / get-ply-info

#let info = get-stl-info(stl-data, json.encode(()))
#let info = get-obj-info(obj-data, json.encode(()))
#let info = get-ply-info(ply-data, json.encode(()))

Returns JSON with model metadata (triangle count, vertex count, bounding box, groups).

Output Formats

• PNG (default): Z-buffer rasterized. Best for high-poly models and smooth shading. Set width/height for resolution and antialias for supersampling.
• SVG (format: "svg"): Vector output via painter’s algorithm. Best for low-to-medium poly models. Supports debug overlays and silhouette outlines.

Config Reference

Camera & Viewport

Appearance

Shading & Lighting

Color Mapping

Outlines

Effects

Annotations

Multi-View

Diagnostics

Full Config

{ // ── Camera & Viewport ─────────────────────────────────────────────
"camera": [3, 3, 3],
// Camera position in world space (Cartesian)
"azimuth": null,
// Spherical camera: horizontal angle in degrees
"elevation": null,
// Spherical camera: vertical angle in degrees
"distance": null,
// Spherical camera: distance from center (auto)
"center": [0, 0, 0],
// Look-at target (overridden by auto_center)
"up": [0, 0, 1],
// Up direction vector
"fov": 45,
// Vertical FOV in degrees (perspective only)
"projection": "perspective",
// "perspective", "orthographic", "isometric", "cabinet", "cavalier",
// "fisheye", "stereographic", "curvilinear", "cylindrical", "pannini",
// "tiny-planet"
"auto_center": true,
// Auto-center on model bounding box
"auto_fit": true,
// Scale model to fill viewport
"width": 500,
// Output width in pixels
"height": 500,
// Output height in pixels
"background": "#f0f0f0",
// Background color (hex), "" = transparent
// ── Appearance ────────────────────────────────────────────────────
"color": "#4488cc",
// Model fill color (hex)
"stroke": "none",
// Triangle edge stroke: color string or { color, width }
"light_dir": [1, 2, 3],
// Directional light vector
"ambient": 0.15,
// Ambient light intensity (0-1), or { intensity, sky, ground }
"mode": "solid",
// "solid", "wireframe", "solid+wireframe", "x-ray"
"opacity": 1.0,
// Global model opacity (0-1)
"xray_opacity": 0.1,
// Front-face opacity for x-ray mode (0-1)
"cull_backface": true,
// Back-face culling (auto-disabled for x-ray)
"wireframe": "",
// Wireframe overlay: color string or { color, width }
"smooth": true,
// Gouraud smooth shading (best with PNG)
"specular": 0.2,
// Specular highlight intensity (0-1)
"shininess": 32,
// Specular exponent (higher = tighter)
"gamma_correction": true,
// Compute lighting in linear sRGB space
"fresnel": 0.3,
// Fresnel rim lighting: intensity (0-1), or { intensity, power }
"lights": [],
// Array of light definitions (see Multi-Light)
"tone_mapping": "",
// "reinhard", "aces", or { method, exposure }
"shading": "",
// "blinn-phong" (default), "gooch", "cel", "flat", or "normal"
"gooch_warm": "#ffcc44",
// Gooch warm tone color
"gooch_cool": "#4466cc",
// Gooch cool tone color
"cel_bands": 4,
// Number of cel-shading bands
"sss": false,
// Subsurface scattering: true or { intensity, power, distortion }
"materials": {},
// OBJ material map: { "name": "#hex" }
"highlight": {},
// OBJ group highlight: "#hex" or { color, specular, ... }
// ── Color Mapping ─────────────────────────────────────────────────
"color_map": "",
// "height", "overhang", "curvature", "scalar", or "" (off)
"color_map_palette": [],
// Custom hex color gradient
"scalar_function": "",
// Math expression for scalar mode: "sqrt(x*x+y*y+z*z)"
"vertex_smoothing": 4,
// Smooth color values across vertices (0-4)
"overhang_angle": 45,
// Overhang threshold in degrees
// ── Outlines ──────────────────────────────────────────────────────
"outline": false,
// Silhouette edge outlines: true or { color, width }
// ── Effects ───────────────────────────────────────────────────────
"ground_shadow": false,
// Ground shadow: true or { opacity, color }
"clip_plane": null,
// Clipping plane (a, b, c, d)
"explode": 0,
// Exploded view factor
"point_size": 0,
// Point cloud splat radius (0 = auto)
"antialias": 1,
// Supersampling for PNG (2 = 2x2 SSAA, 4 = 4x4)
"fxaa": true,
// Fast approximate anti-aliasing (PNG only)
"ssao": false,
// Screen-space AO: true or { samples, radius, bias, strength }
"bloom": false,
// Bloom: true or { threshold, intensity, radius }
"glow": false,
// Glow: true or { color, intensity, radius }
"sharpen": false,
// Sharpen: true or { strength }
// ── Annotations ─────────────────────────────────────────────────
"annotations": false,
// Annotate OBJ groups: true or { groups, color, font_size, offset }
// ── Multi-View ────────────────────────────────────────────────────
"views": null,
// Named views: ["front", "right", "top", ...]
"turntable": 0,
// Turntable views: count, or { iterations, elevation }
"grid_labels": true,
// Show labels on multi-view grids
// ── Diagnostics ───────────────────────────────────────────────────
"debug": false,
// Overlay model metadata
"debug_color": "#cc2222"
// Debug text color
}

Building

make build    # cargo build → wasm-opt -O3 → deploy
make doc      # build + compile examples/documentation.pdf

Requires cargo, wasm32-unknown-unknown target, and wasm-opt (from binaryen).