threers
A drop-in three.js replacement for Rust and the browser, backed by wgpu. The same Rust core runs natively (winit) and as WebAssembly, with a JavaScript shim that exposes the familiar THREE.* API so existing three.js code can run with minimal changes.
Current version: 0.0.4 · Changelog
Table of contents
- Features
- Prelude
- Quick start
- Native (desktop)
- Optional: mesh-bvh / CSG
- OpenSCAD solid modeling
- Lattice infill
- Kirigami corrugations
- Materials: metals, glass, anisotropy, thin film
- Headless render & video export
- Path tracing (
raytrace) - Metal backend (Apple)
- visionOS
- Native codecs (GIF, APNG, VP9, H.264, HEVC)
- Subtitles and captions
- Animating OpenSCAD models
- Web (browser)
- Earth, sun and lens flare
- RLX bridge
- Physics
- Parity compare UI
- Project layout
- Architecture
- Development
- Status
- License
Features
- Scene graph (
Object3D,Scene, transforms, layers) - Buffer geometries, PBR materials, lights, shadows, fog
- Extended PBR — clearcoat (direct + IBL), transmission/IOR/dispersion, anisotropy (+rotation), sheen (direct + IBL), thin-film iridescence (+thickness map), volume absorption, normal mapping with vertex tangents, geometric specular AA, and measured-reflectance
materials::presets - HDR pipeline —
Rgba16Floattextures, float.hdrdecoding, HDR environment prefiltering, and ACES tone mapping onRenderer - Area lights —
RectAreaLightshading (analytic diffuse form factor + representative-point specular) - Custom WGSL materials via
ShaderMaterial - wgpu renderer with post-processing (FXAA, bloom, SSAO, glitch, halftone, …)
- Loaders (glTF, OBJ, STL, HDR, …), animation, controls, helpers
- Headless offscreen render → tightly packed RGBA (
HeadlessRenderer, native) - Opt-in Metal backend (
metal, macOS/iOS) — a second renderer that talks to Metal directly through the Objective-C runtime: nometal-rs, noobjccrate, no build script, no new dependency of any kind. Draws the sameSceneto an offscreen target or aCAMetalLayer, andPassAttachments::from_rawwill draw it into textures your app already owns. wgpu'sRendererstays the default and the complete one — see Metal backend (Apple) for what this covers and what it does not. - Opt-in visionOS (
visionos) — the CompositorServices frame loop and ARKit world tracking, again as plainextern "C"against the visionOS SDK. Both eyes are drawn in one pass into a texture array, depth runs reverse-Z (the only convention the compositor accepts), per-eye projections come fromcp_drawable_compute_projection, and the device anchor keeps content still in the room instead of riding on the viewer's head. See visionOS. - Video export (
video) — frame sequence → ffmpeg; native GIF/APNG/H.264/VP9 whennative-codecis on - Native codecs (
native-codec) — pure-Rust GIF (encode/decode), APNG, VP9/WebM, H.264/MP4, HEVC/MP4; wasm-safe browser download - Subtitles & captions — SubRip / WebVTT parse + write, text rasterized on-screen over the 3D frame or burned into exported video, plus sidecar files and soft-subtitle tracks (MP4
tx3g, WebM WebVTT). Pure Rust, no font assets required, wasm-safe. - Height maps —
displacementMap/displacementScale/displacementBiason Standard and Physical materials, sampled in the vertex stage (plain, skinned, instanced and shadow paths) - Kirigami plate lattices — Kirigami Expanded Miura corrugations (Parra Rubio et al., ASME 2023): planar and curved sandwich cores as plates with crease topology, developed SVG nets, and discrete origami cells.
cargo run --release --example kirigami - Lattice generators — 29 periodic infills as
BufferGeometry, in one API: 8 triply periodic minimal surfaces (gyroid, Schwarz P and D, Neovius, I-WP, Fischer–Koch S, Lidinoid, split P), 7 beam cells (simple cubic, BCC, BCC-Z, FCC, octet truss, diamond, Kelvin), the 9 patterns a slicer draws (rectilinear turning and aligned, grid, triangles, tri-hexagon, honeycomb, cubic, quarter cubic, concentric), and 5 face-connected cuboctahedra voxels (rigid, compliant, auxetic, chiral CW/CCW — Jenett et al., Sci. Adv. 2020). Sized the way a slicer sizes them — ask for 25 % density and the wall thickness is solved for you — and meshed by a marching cubes that derives its own case table, so ambiguous cells cannot crack and the output is indexed, welded and watertight.gradevaries thickness across the part,trimpours the lattice into any shape you can write as a field, and both keep the mesh closed.wall_samplescatches the failure mode that would otherwise be silent — a wall thinner than the sample step comes out as gravel, not as a wall — andresolve_wallsfixes it per generator rather than paying the worst case on all of them. No feature flag, no dependencies. - Opt-in planets (
planet) —Planet/Starfieldbuilders that stack a textured body, a cloud shell and an analytically shaded atmosphere; procedural equirectangular map generation; elevation → normal + roughness derivation; and a loader for NASA's public-domain Blue Marble, Black Marble, MODIS, GEBCO, CGI Moon Kit and Deep Star Maps imagery - Opt-in path tracer (
raytrace) — a physically-based renderer beside the rasteriser, not inside it. Rays leave the camera, scatter off surfaces by their BSDF, and either find a light or die trying; the image is the average of millions of such paths, so global illumination, colour bleeding, soft shadows, glossy interreflection and refraction fall out of the integral rather than being features bolted on. A principled BSDF (Lambert + anisotropic GGX + rough dielectric transmission + clearcoat, with Kulla–Conty energy compensation, so rough gold does not render grey), emissive geometry sampled as area lights, next-event estimation with the power heuristic, Owen-scrambled Sobol sampling (every 2D decision a path makes comes from a stratified low-discrepancy pair — 1.5–3× lower RMS error at the same sample count, which is 2–9× the effective samples), importance-sampled environments (an HDRI's sun is 6·10⁻⁵ of the sphere — cosine-weighted sampling finds it once in twenty thousand tries and returns speckle), adaptive sampling that stops each pixel when its own standard error settles, Russian roulette, Beer–Lambert absorption inside solids, a thin-lens camera with autofocus, and an AOV-guided À-Trous denoiser thresholded on each pixel's measured variance, with albedo and normal guides that follow the path through mirrors and glass the way Cycles' do. Two backends over one scene form: a portable CPU reference (wasm32 included, rayon-parallel withparallel) and a wgpu compute kernel — no new dependency, it reuses the renderer's own wgpu — that runs the same estimator and agrees with the CPU to within Monte-Carlo noise. Takes an ordinaryScenewith ordinaryMaterials andLights; nothing is authored twice. See Path tracing. - Opt-in mesh BVH (
mesh-bvh) — accelerated raycast / shapecast (three-mesh-bvh–compatible) - Opt-in CSG (
bvh-csg) — boolean ops onBufferGeometry(three-bvh-csg–compatible); Rust native + JS addon - Opt-in OpenSCAD (
openscad) — a.scadinterpreter and aSolid/scad!Rust DSL, evaluated by a pure-Rust watertight exact-CSG kernel (resolves curved∧curved booleans, float fallback where unverifiable). Mesh import/export (STL/OBJ/OFF/3MF/AMF/glTF-GLB, DXF/SVG,.dat/.pngheightmaps) and a live browser playground. - Opt-in NURBS (
nurbs) — f64 rational curves and surfaces with analytic derivatives, Boehm knot insertion / refinement / Bézier extraction / degree elevation, and exact conic and quadric constructors (a circle is a rational quadratic, so a sampled sphere holds its radius to ~1e-15 at any parameter — not to whatever segment count you picked). Curvature-adaptive tessellation toBufferGeometrywith analytic normals viaNurbsGeometry, plus JS bindings (NURBS=1 web/build.sh). Stage 0 of the B-rep roadmap in docs/brep-nurbs-plan.md. - Opt-in surface provenance (
brep) — every triangle of a built-in primitive knows the analyticSurfaceit was sampled from, so normals come fromSᵤ × Sᵥinstead of averaged face normals, UVs come from the surface's own parameterization, and a mesh can be re-tessellated at any tolerance after the fact rather than being frozen at whatever$fnwas chosen. Recovers what triangles cannot hold — a truncated cone's apex is not a vertex, not on any face, and not inside the bounding box. Provenance is a sidecar: it never alters a mesh, and dropping it leaves every consumer behaving as before. Stage 1 of docs/brep-nurbs-plan.md. - Opt-in analytic CSG acceleration (
brep-csg) — when both boolean operands carry provenance, a triangle pair is resolved by asking what its surfaces do rather than intersecting the triangles. Fixes the exact-CSG kernel's longest-standing degeneracy: two identical primitives translated along a shared axis, which used to fall back to the float kernel and now returns an exact watertight result. The classifier's exact-arithmetic coplanarity test cannot be passed by re-triangulated vertices; surface identity can. Strictly an accelerator — anything without a closed form falls through to the existing path, and a tagged boolean is asserted never to be worse than an untagged one. See docs/brep-nurbs-plan.md § Stage 2. - Opt-in B-rep boolean (
brep-kernel) —Body::booleanfor union / difference / intersection on the B-rep itself, not on triangles. Surfaces are intersected in closed form, each face is trimmed by the resulting curves, and the seams become shared edges: both sides index the same vertices, so a result is watertight at any tolerance rather than merely coincident — and stays analytic, so a bore comes back as aCylinderyou can re-tessellate, not a band of triangles. Coaxial surfaces of revolution are exact, which covers a torus against a cylinder, sphere, cone or another torus — cases with no closed form in general position. A pair with no closed form is traced numerically rather than refused, so a cross-drilled hole resolves too. It declines rather than approximates:TangentialContactwhere two surfaces touch instead of crossing,NeedsArrangementwhen a face's subdivision does not come apart,CoincidentFaceswhere the two share a surface, andNotWatertightif the pieces do not assemble — the layer verifies its own result before returning it, so what you get back is closed or you get nothing. A result is also a solid: one closed shell with every edge on exactly two faces, which is what lets it be the input to the next boolean. Stage 4 of docs/brep-nurbs-plan.md. - Opt-in STEP (
step) — ISO 10303-21 read and write, and the AP203/AP214 advanced-B-rep mapping to and fromBody. Planes, cylinders, spheres, cones and tori map to their own entities, and so do the circles and lines bounding them: a drilled plate arrives in a CAD system as three cylinders it can re-dimension, not as facets it cannot. Import returns a solid, so a file you read can be cut again. Export is deterministic — no clock, no hash order — so the same model always produces the same bytes, and anything unmappable is reported rather than silently approximated. The promise is checked, not asserted: a corpus of booleans is written, read back and re-measured, and each must either come back the size it left or have the export name what it could not carry — a face whose edges bound two regions and do not say which (AmbiguousRegion), or one bounded partly by its own seam (SeamBoundary). Silence and a wrong answer is the one outcome ruled out, which is what a format whose point is that the model survives has to guarantee.cargo run --example brep_part --features step. Stage 5 of docs/brep-nurbs-plan.md. - OpenSCAD animation — the
$tloop rendered headlessly: colored parts fromcolor(), pickable palettes, a camera-relative studio light rig with shadows, a camera that fits or orbits the model (or obeys its$vpr/$vpt/$vpd), static-model caching, concurrent frame evaluation, and one-call PNG / PNG-sequence / video output. - Companion crate
threers-physics— rigid-body physics: gravity, collisions, joints, scene queries (raycast / shapecast), inverse kinematics, continuous collision detection and zero-gravity/orbital models. Pure Rust, wasm-ready, with optional rayon and wgpu-compute acceleration. Seecrates/threers-physics. - Companion crate
threers-animation— easing, tweens, springs, timelines, cinematic camera animation (fly/orbit/paths/shake/shots), and blending an animated pose into a simulated one (ragdolls). Seecrates/threers-animation,docs/animation.md, anddocs/camera-animation.md. - Published JS package
threers— npm / Deno / Node ESM fromcrates/threers-js. Defaultthreers/mini(small wasm);threers/fullfor CAD/codecs/path tracer. Arch-independent wasm. - Published native Node package
threers-node— napi-rs addon fromcrates/threers-nodewith per-arch binaries (@threers/node-darwin-arm64, …). Not Neon; Deno stays on the wasm package. Seedocs/bindings.md. - Published Python package
threers— PyPI wheels fromcrates/threers-py(maturin / PyO3; arm64 + x86_64 matrices). - Companion crate
threers-robot-arm— a four-axis pick-and-place cell run two ways (kinematic and servo-driven), sized from its own inverse dynamics, with a scrubbable browser player. Seecrates/threers-robot-arm. - Companion crate
threers-probe— screen-space neural global illumination from a G-buffer and a set of lighting probes: trained in RLX, run anywhere RLX runs. Seecrates/threers-probe. - Companion crate
threers-continuum— tendon-driven continuum robots: a flexible rod as a chain of elastic hinges, cable routing, Clark coordinates and task-space tip control. Seecrates/threers-continuum. - Opt-in RLX bridge (
rlx) — RLX, an ML compiler + runtime, as a neighbour of the renderer rather than a layer under it. Vertex attributes and pixels convert torlxtensors of a declared shape and back (NHWC/NCHW, sRGB↔linear,Rgba16Floatincluded), andGraphRunnercompiles a graph once so a per-frame filter does not pay the compiler sixty times a second. On top of that:ConvFilter(blur/sharpen/Sobel/emboss as depthwise conv2d),Diffusion(iteratedh ← h + κ∇²hfor terrain),mesh::taubin_smooth(smoothing as a graph over[n, 3]positions),ColorGrade(a colour transform fitted to a reference by autodiff — not applied, learned), andPalette(k-means with the assignment step on the device). Built with rlx'scpu,tensorandgpubackends, native and wasm32. - Opt-in exact Delaunay / Voronoi (
rlx-geo) —rlx-geo's integer predicates, so scattered samples triangulate to the Delaunay mesh rather than one a floating-point predicate rounded into a near-miss (a flipped triangle in a height field is a visible spike).heightfield_geometryreturnsBufferGeometrywith normals and UVs;refine_heightfieldsamples adaptively, reaching ~9× lower error than a uniform grid of the same vertex count; Voronoi labels, site-distance, wall-distance and edge maps drive cell textures (cracked mud, stained glass) vianormal_map_from_height. - Parallel CPU work (
parallel) — rayon-backed BVH/CSG evaluation; native only, and order-preserving so results are unchanged - Web:
web/threejs-shim.js+ wasm — drop-inTHREE.*replacement targeting three.js r165 - Native: winit examples for desktop development and debugging
Prelude
use threers::prelude::*; brings in the scene graph, the common geometries and
materials, lights, cameras, textures, the renderers, the vector maths, and the
Camera trait — which has to be in scope for camera.view_matrix() to resolve,
and is the sort of thing a prelude is for.
use *;
let mut scene = new;
scene.add;
scene.add_light;
let mut camera = new;
camera.position = new;
camera.look_at;
It is a curated subset, not everything the crate exports: a glob import claims
every name in it, so the maths shapes (Plane, Sphere, Triangle, Ray,
Box3, …), the curve and path types (Path, Shape, …), and the subsystems you
reach for deliberately are left out of the root. Nested modules keep those
reachable without polluting the glob:
use *;
use *;
use *;
All of them also remain at the crate root — threers::Path,
threers::loaders::GltfLoader — one use away. Feature-gated nested modules
(prelude::csg, prelude::openscad, prelude::nurbs, prelude::raytrace,
prelude::captions) appear when the matching Cargo feature is on. With the
metal feature on, the Metal renderers join the root prelude, because they are
renderers like the others.
Meta feature bundles (cad, media, gi, apple, full) turn on related leaf
flags in one go — see the feature table in the crate docs.
Quick start
Native (desktop)
Requires Rust 1.87+ (wgpu 30's minimum), a working wgpu backend (Metal/Vulkan/DX12), and dev dependencies from Cargo.toml.
ocean_water is a GPU FFT ocean: a JONSWAP spectrum on a full lattice,
inverse-transformed each frame into three tiling cascades (swell / waves /
ripples) by a butterfly compute pass. Everything reads the cascades through one
shared sampler — a compute pass displaces a camera-anchored disc from them, the
ShaderMaterial fragment samples them per pixel for normals and breaking-wave
foam, a second compute pass accumulates persistent foam and wake, and the CPU
answers buoyancy from the dominant modes with no readback. The mesh is uploaded
once and written in place on the GPU, so per-frame CPU cost is flat in vertex
count (~0.3 ms at every quality level). Eight sea-state presets, five mesh
densities:
cargo run --release --example ocean_water -- storm --quality ultra,
-- tropical --png ocean.png, -- --bench, or -- --list.
Waves shoal over the analytic sea bed — slowing, shortening, growing by Green's law and breaking past 0.78 of their own depth, which is what draws the surf zone. It also does screen-space reflection and refraction, caustics on a shader-lit sea floor, persistent foam and wake, spray/rain/underwater-mote particles, an underwater view with Snell's window, water masking, sparkle and multi-point buoyancy.
The FFT's butterfly table is validated on the CPU against both a naive DFT and
rlx's own FFT before it ever reaches the GPU (--features rlx), because a
butterfly index off by one produces plausible noise rather than an error. rlx is
not in the per-frame path: measured, its CPU backend is ~6.6 ms a frame for three
cascades, and its GPU backend builds its own device rather than borrowing this
one, so results would cross host memory either way. (It used to be a different
major of wgpu as well; since the wgpu 30 upgrade both are the same major, which
is what made rlx's GPU backend usable on wasm32 at all.)
Four small opt-in APIs carry that, all reusable outside the example:
BufferGeometry::gpu_writableaddsSTORAGEusage to a mesh's vertex buffer, andRenderer::vertex_bufferhands it back — so a compute shader can write positions and normals directly, vertex animation with no CPU round trip.ShaderMaterial::texturesbinds up to four of your own texture views asu_tex0..3, for sampling something a compute pass wrote this frame.ShaderMaterial::screen_spacedraws the material in the refraction pass, where the captured opaque colour and depth are available — the prerequisite for any custom SSR or refraction.ShaderMaterial::sideis now honoured (it was previously ignored and always culled back faces, which silently hid anything meant to be seen from inside).
Optional: mesh-bvh / CSG
# BVH picking demo
# Hierarchy CSG (exact TriKey parity with JS three-bvh-csg@0.0.16)
// Cargo.toml: threers = { version = "0.0.4", features = ["bvh-csg"] }
use ;
let mut ev = new;
let mut a = new;
let mut b = new;
let _geom = ev.evaluate;
OpenSCAD solid modeling
The openscad feature adds two front ends onto one Solid CSG tree — an OpenSCAD
.scad interpreter and a Rust DSL — evaluated by a pure-Rust watertight
exact-CSG kernel (to_geometry_exact), with mesh import/export.
# convert a .scad to any mesh format (format = output extension):
// Cargo.toml: threers = { version = "0.0.4", features = ["openscad"] }
use ;
// (a) Rust DSL — fluent builder + the `scad!` macro:
let part = scad! ;
let _stl = part.to_stl; // also .to_obj/.to_off/.to_3mf/.to_glb
// (b) or parse an OpenSCAD program:
let solid = parse_scad.unwrap;
let _glb = solid.to_glb;
let _ = ; // primitives are also free functions
Curved∧curved booleans (e.g. sphere ∪ sphere, cylinder ∩ cylinder) resolve to
watertight meshes; the kernel falls back to the float evaluator only where its
manifold gate can't verify a result, so it is never wrong — only sometimes
deferential. Try it live in the browser: web/openscad-playground.html.
Kirigami corrugations
Kirigami Expanded Miura plate lattices — pads, inclined walls, custom curvature, discrete origami cells, tiled assemblies, TPMS/strut lattice cores, and a joined crease net.
use ;
let geom = new
.cell
.height
.thickness
.build;
let saddle = Saddle.evaluate_default;
let hybrid = saddle.to_geometry_with_core;
let tiled = tile
.evaluate;
write.unwrap;
Browser: web/examples/kirigami.html (needs a wasm build with web/build.sh).
Lattice infill
29 periodic lattices, all unconditional — no feature flag and no extra dependencies.
use ;
// A 20 mm cube of gyroid, 5 mm cells, 0.8 mm walls.
let gyroid = new
.size
.cell_size
.thickness
.build;
// Or say what a slicer would say — 25 % infill — and let it solve the
// strut diameter that gets there.
let octet = new
.size
.cells
.fit_relative_density;
let diameter = octet.current_thickness;
let mesh = octet.build;
// Face-connected cuboct voxel: the same assembly, four metamaterial
// behaviours. `shape` is amplitude / reentrant indent / chiral radius
// as a fraction of cell pitch.
let auxetic = new
.size
.cells
.shape
.fit_relative_density
.build;
// Discrete assembly: six face parts per voxel, exploded so the joints show.
let exploded = new
.pitch
.cells
.explode
.build;
// Denser on the right than the left, and poured into a sphere.
let graded = new
.size
.cells
.thickness
.grade
.trim
.build;
| Family | Generators |
|---|---|
Tpms |
Gyroid, SchwarzP, Diamond, Neovius, IWP, FischerKochS, Lidinoid, SplitP |
Strut |
Cubic, Bcc, BccZ, Fcc, Octet, Diamond, Kelvin |
Cuboct |
Rigid, Compliant, Auxetic, ChiralCw, ChiralCcw |
Infill |
Rectilinear, AlignedRectilinear, Grid, Triangles, TriHexagon, Honeycomb, Cubic, QuarterCubic, Concentric |
LatticeKind::from_name takes any of those names, so a --lattice gyroid flag
needs no table of its own.
Sheet or solid
A minimal surface bounds two interlocking labyrinths, and there are two ways
to make a solid out of that. LatticeStyle picks which (beam and infill
lattices are always the solid around their beams or walls):
Sheet (default) |
a wall of thickness centred on the surface, with open void either side. Two independent channel networks, no closed cells, the most surface area per gram — infill, heat exchangers, scaffolds. |
Solid |
one labyrinth filled, the other left as void. Stiffer than a sheet of the same mass, and it leaves a single connected void. |
For Solid, thickness is an offset from the minimal surface rather than a
wall width — 0.0 is the bare surface, so about half the volume, and negative
values thin it below that. Two consequences worth knowing: wall_samples
reports infinity, because there is no wall to resolve; and grade scales that
offset, so grading a solid lattice sitting at offset 0.0 does nothing at all
(zero times anything is zero). Give it a non-zero offset to scale, or grade a
sheet, which runs from nothing to solid.
let solid = new
.size
.cells
.style
.fit_relative_density // solves the offset, here about −1.25 mm
.build;
Filling shapes, not just boxes
A lattice fills a box unless told otherwise. fill takes a Region — a signed
field plus the bounds it occupies — and the region's own bounds size the sample
grid, so there is nothing else to say. The mesh closes over the cut, so the
result is still one watertight shell.
use ;
// Primitives, swept curves, and constructive combinations of them.
let curve = new;
let shape = sphere
.union
.difference;
// …any closed triangle mesh (`mesh-bvh`)…
let shape = mesh.unwrap;
// …or an OpenSCAD model, through the exact-CSG kernel (`openscad`).
let shape = scad.unwrap;
let part = new
.fill
.cell_size
.fit_relative_density // 25 % of the *part*, not of its bounding box
.skin // perimeters and infill, in one mesh
.build;
| Constructor | |
|---|---|
sphere, cuboid, rounded_cuboid, capsule, cylinder, cone, torus, half_space |
exact signed distances |
tube(curve, radius, segments) |
a swept Curve3 — Catmull-Rom, Bézier, NURBS, … |
mesh(&BufferGeometry), from_bvh |
any closed triangle mesh (mesh-bvh) |
solid(Solid), scad(&str) |
an OpenSCAD model, through the exact-CSG kernel (openscad) |
new(bounds, field) |
your own field |
union, intersection, difference, smooth_union, offset, shell, invert |
combinators |
translate, rotate, scale, transform |
placement |
skin(t) adds a solid wall on the fill's surface and unions it with the
lattice, so the two bond and the part is a printed part rather than a lattice
in a bag. clip(region) cuts the finished part — skin included — for
sectioning it to look inside, and unlike fill the skin stops dead at the cut
face.
Density is measured against the part, not its bounding box. It has to be: a tube swept along a curve might occupy a fifth of its own box, so 25 % of the box would be unreachable however thick the walls were made.
Each is a scalar field, contoured by a marching cubes that builds its own case
table by chaining face contours into loops. That buys the two properties a
slicer or a boolean kernel actually needs: an ambiguous cell is resolved from
its corner signs alone, so the two cells sharing that face always agree and the
mesh cannot crack; and the loops come out oriented, so no triangle needs a
normal test to face the right way. Output is indexed, welded, and closed —
every edge shared by exactly two triangles, including where trim cuts the
lattice off.
Thickness is a length, not a level-set constant: the TPMS fields are divided by their own gradient, so a 0.8 mm wall is 0.8 mm everywhere rather than varying two-to-one between the channels and the necks. The gradients are closed-form rather than differenced, which is one field evaluation a sample instead of seven.
Resolution, and the one way this fails quietly
A wall thinner than the sample step is missed between samples, and the mesh comes out as disconnected specks. Nothing errors, because a field never sampled inside a wall looks exactly like one with no wall there. It is easy to hit by accident: at 25 % density Lidinoid needs walls a third as thick as a gyroid, so the settings that render one cleanly shatter the other.
let lattice = new
.size
.cells
.fit_relative_density // density first — it sets the thickness
.max_samples
.resolve_walls; // …which sets how fine the sampling has to be
assert!;
Sampling parallelises with the crate's parallel feature — the gallery example
builds 1.6× faster with it on (2.0 s → 1.3 s for all 25 tiles, 10 cores).
Results are byte-identical either way: every sample has a fixed address in the
grid, so a build flag cannot change the geometry.
Materials: metals, glass, anisotropy, thin film
PhysicalMaterial (three.js MeshPhysicalMaterial) carries the full extended
PBR stack — clearcoat, transmission + IOR + dispersion, anisotropy with an
in-plane rotation, sheen, iridescence, and Beer-Lambert volume absorption — all
honored by the renderer, plus normal / roughness / metalness / AO / emissive maps.
In the browser, web/examples/materials.html renders all of them live via
wasm/wgpu (also procedural — no HDRI or texture downloads). The JS shim accepts
three.js's own option names, so this is portable three.js code:
;
// …or start from a preset and tweak:
THREE.;
Measured-reflectance presets live in materials::presets (gold and silver MLI
foil, aluminium, brushed aluminium, titanium, heat-tinted titanium, solar cell,
thermal paint, black kapton, optical glass):
use presets;
let mut foil = gold_foil; // F0 (1.000, 0.766, 0.336), metalness 1
foil.normal_map = Some; // the crinkle is what makes it read as foil
let panel = solar_cell; // dark cells + cover-glass clearcoat
let bell = anodized_titanium; // thin-film hue by thickness (nm)
HDR environments and tone mapping
An 8-bit environment cannot hold a sun: capped at 1.0, a solar disc can only be made to read bright by making it physically huge, and PMREM then smears it across tens of degrees so every metal reflects the same grey wash. Load a real one instead:
use ;
let = parse_f32?; // linear f32, unclipped
let cube = from_equirect_f32;
scene.environment = Some;
// Without this, anything above 1.0 hard-clips to white and loses its hue.
renderer.set_tone_mapping;
Tone mapping is off by default so existing scenes render unchanged.
Two things worth knowing before you reach for metals:
- Metals need
scene.environment. Atmetalness = 1.0the BRDF has no diffuse term, so with no environment a gold sphere renders near-black no matter how many lights you add. Prefilter one withPmremGenerator::generate_pmrem; that mip chain is also what makesroughnessmean anything for reflections. - Pick a non-sRGB offscreen format. The mesh shader does its own
linear→sRGB encode, so a
HeadlessRendererleft on the defaultRgba8UnormSrgbtarget encodes twice and washes the image out (mid-greys land ~2.5× too bright). Use.color_format(wgpu::TextureFormat::Rgba8Unorm), as the examples above do.
For a brushed look, anisotropy_rotation aims the streak in UV tangent space;
the tangent frame is derived from UV screen-space derivatives, so it needs a mesh
with UVs (without them the frame falls back to a view-dependent one and the
rotation is arbitrary).
Headless render & video export
Native-only. HeadlessRenderer owns the wgpu device and an offscreen target; export_video pipes RGBA frames to ffmpeg (or in-process GIF/APNG when native-codec is enabled).
Per-format examples (optional --out PATH):
| Example | Features | Output |
|---|---|---|
export_h264 |
video |
.mp4 (native H.264 with native-codec; else ffmpeg libx264) |
export_hevc |
video |
.mp4 (libx265) |
export_hevc_vt |
video |
.mp4 (hevc_videotoolbox) |
export_vp9 |
video |
.webm opaque |
export_vp9_alpha |
video |
.webm + alpha |
export_gif |
video,native-codec |
.gif (no ffmpeg) |
export_apng |
video,native-codec |
animated PNG |
export_webm_native |
native-codec |
.webm pure-Rust VP9 |
// Cargo.toml: threers = { version = "0.0.4", features = ["video"] }
use ;
let mut hr = builder.size.build.unwrap;
let opts = new.fps.codec;
// export_video(w, h, frame_count, &opts, |i| { /* advance scene */; hr.render_to_rgba(...) })
GIF / APNG without spawning ffmpeg:
// features = ["video", "native-codec"]
let opts = new
.fps
.codec
.transparent
.gif_colors;
Browser-friendly bytes API (also used from wasm):
// features = ["native-codec"]
use ;
let bytes = encode_animation_rgba.unwrap;
Path tracing (raytrace)
Renderer draws a scene the way a GPU pipeline does: project the triangles,
shade each fragment from a fixed set of lights, approximate everything else.
Those approximations are what make it run at 60 fps and what make it wrong in
familiar ways — light does not bounce, a mirror cannot show what is behind the
camera, and a glass ball does not bend the room.
RaytraceRenderer answers the same question by simulating light transport. It
takes the same Scene — same materials, same lights, nothing authored twice.
use ;
let mut renderer = new;
renderer.set_settings;
let rgba = renderer.render_to_rgba; // same layout as HeadlessRenderer
write?;
Progressive, so a preview refines instead of appearing all at once — the scene is flattened and its BVH built once, then samples are added to the same film:
renderer.prepare;
for _ in 0..20
Backends. CpuBackend is the reference — portable, wasm32 included, and the
definition of correct for the module. gpu::GpuBackend runs the same integrator
as a wgpu compute kernel over the same scene, and is selected by swapping one
argument:
use GpuBackend;
let backend = headless?; // or ::with_device(device, queue)
let mut renderer = with_backend;
The kernel is packed for throughput rather than convenience: the whole scene goes into four storage buffers plus one texture atlas (WebGPU's baseline guarantees only four storage buffers per stage, and bindless is a native-only wgpu feature this kernel does not assume), so there is one bind group for any scene; samples are traced in batches per dispatch, because a single dispatch that runs for seconds trips the GPU watchdog on every platform; the film accumulates on the device and is read back once, not once per batch; and one invocation owns one pixel, so there are no atomics anywhere.
On an Apple M-series integrated GPU the path_trace_gpu example runs about
7× faster than the rayon-parallel CPU backend at identical settings, and the
two frames agree to four decimal places — which is what the CPU↔GPU test in the
suite checks, along with a white-furnace test on each.
Image-based lighting. The usual way to light a realistic render is one
HDRI and no lights at all — hdri_lighting does exactly that: no
DirectionalLight, no AmbientLight, every shadow and highlight and bit of
fill coming out of scene.environment. Point it at a real .hdr with
HDRI=studio.hdr, or let it synthesise a sky with a sun four orders of
magnitude brighter than the blue around it.
let = parse_f32?;
scene.environment = Some;
settings.background = Environment; // lit by it *and* seen behind
That needs three things to be right, and an HDRI is unforgiving about all
three: the full dynamic range has to reach the integrator (the 8-bit copy
CubeTexture keeps for display is Reinhard-compressed, and integrating it caps
the sky at about 1.0), the sun has to be importance-sampled, and the cube faces
have to be read in the orientation they were written in.
Sampling. Three strategies, all combined by the power heuristic so none is trusted where it is poor: the BSDF's own lobes; the lights, including emissive geometry by an area×luminance distribution; and the environment, by a 256×128 density built over its own brightness.
Underneath all of them, the numbers are stratified rather than independent. Nearly every decision a path makes is two-dimensional — a point on a light, a direction off a BSDF, a point on the lens — and each one draws a pair from an Owen-scrambled Sobol (0,2)-sequence, so sixteen samples of a pixel cover the unit square evenly instead of clumping the way sixteen independent draws do. Dimensions are allocated in a fixed block per bounce so that the same decision draws the same dimension on every sample, which is what makes the stratification worth anything. Measured against a converged reference: 1.5× lower RMS on a plain area-light scene, 3× on one with an environment, a sun and an emitter — the latter being roughly nine times the effective samples. That last one is not a refinement — an HDRI puts most of its energy into a sun about 6·10⁻⁵ of the sphere across, which a cosine-weighted direction finds roughly once in twenty thousand samples, so without it an HDRI-lit render is white speckle that does not resolve at any sample count you would wait for.
Denoising. Cycles uses OpenImageDenoise — a pretrained U-Net — which is not something this crate can ship. What it can take from Cycles is the part that makes any guided denoiser work, and that is how the guide passes are built: the albedo and normal are not "whatever the first hit was". A mirror's own colour and normal describe the mirror, not the image in it, and a glass ball's describe neither the glass nor the room behind it. So the guides follow the path through specular and transmissive surfaces, carrying their tint, until they reach something rough enough to describe — Cycles' scheme, thresholds included.
The reconstruction filter is edge-avoiding À-Trous, but the colour threshold is the pixel's own accumulated variance rather than a constant: two estimates of the same value differ by about their combined standard deviation, so dividing by it asks "is this difference more than noise?" instead of comparing against a number that is wrong at every sample count but one. Where a pixel has already converged the filter stands down entirely — there is nothing left to remove and a smooth gradient is all it could damage.
And the filter's parameters are fitted, not guessed. denoise_fit renders
a handful of scenes twice — 32 samples and 8192 — and searches the four widths
against that ground truth, judged on a held-out interior:
Which was worth doing. The hand-picked values it replaced were worse on every
scene tried, and on a smooth area-lit one they were worse than not denoising at
all. Relative error on the held-out scene went 0.096 → 0.084, and on glass
beside rough metal 0.182 → 0.157. DenoiseParams::fit is public, so the same
can be done against your own content.
A trained denoiser (--features learned-denoise) sits beside the fitted
À-Trous filter. It is a U-Net over the same guides — colour, albedo, normal —
trained on pairs this renderer generates itself, so no corpus is collected and
no licence attaches to the result.
Measured against the OpenImageDenoise library inside Blender.app, driven at
the settings Cycles sets in intern/cycles/integrator/denoiser_oidn_base.cpp
(filter RT, hdr on, srgb off, quality HIGH) — so the comparison is with what
Blender actually ships, not an approximation of it:
| scored on | ours | Blender's OIDN | |
|---|---|---|---|
| renders of this repo's NEMA 17 and printer | 0.03545 (5.51×) | 0.03720 (5.25×) | 4.7% ahead |
| the furnace test | 0.0125 | 0.0132 | 5.2% ahead |
| Cornell box | 0.0558 | 0.0492 | 13.3% behind |
| Veach MIS | 0.1016 | 0.0919 | 10.6% behind |
Both directions are worth stating. On real machined geometry it is ahead of what Cycles ships. On the classic demonstration scenes it is behind, and the per-scene split says why: the training corpus had no tight saturated box and no frame holding a pinpoint light beside a broad one. Those regimes are in the generator now.
The furnace test is the row to keep. A grey sphere in a uniform emissive environment must converge to exactly the environment's radiance — the multiple-scattering series sums to one — so the correct answer is known in closed form and any structure a denoiser draws there is provably invented. Being ahead on that one says the filter hallucinates less, which is the property a renderer actually wants and which none of the other numbers measure.
The forward pass is raytrace::denoise_net: plain Rust, no dependencies,
wasm32 included. It is checked against the implementation that trained it
rather than by eye — worst per-pixel disagreement 0.000000
(examples/denoise_parity.rs). Training lives in rlx-denoise, which is
GPL-3.0-only and is not linked by this crate.
In a browser. wasm_denoise splits the work into plan / extract /
run / merge, where only run is expensive and belongs on a worker; tiles
share no state, so N workers produce the same frame as one
(tiling_a_frame_matches_denoising_it_whole asserts exactly that). The module
docs carry the worker wiring.
Measured: ~0.7 s a 128×128 tile at the default widths on one core, ~1.1 s at
wide. Four times the parameters costs 1.6× the time, so the kernel is
memory-bound, not compute-bound. A 1080p frame is ~135 tiles, which across
eight workers is 12–19 seconds — enough to denoise a finished render in the
browser, or to sharpen a progressive one between passes, and not an
interactive viewport. Getting there means putting the convolutions on the GPU,
which the crate already has the wgpu plumbing for.
Progressive denoising. render_progressive traces in batches and denoises
the accumulated film after each, so a viewport shows a usable image from the
first sample rather than noise until the end — which is what Cycles does, and
Blender's default is to denoise from sample 1. Worth knowing what that buys: on
this content the denoiser at ~4 spp matches a raw render at ~110 spp, about 29×
fewer samples.
Adaptive sampling tracks each pixel's own standard error and stops it once
that falls below adaptive_threshold (1 % by default). Noise falls as
1/sqrt(n), so the last halving of the error costs three quarters of the
render, and most of an image gets there long before its worst pixels do —
typically 10–40 % of the sample budget goes unspent for an image that is
indistinguishable. It does not bias anything: a pixel that stops early is still
the mean of its own samples, and the film divides by each pixel's own count.
The decision reads only what the pixel has accumulated, so an adaptive render is
still independent of how it was batched. On the CPU the saved samples are saved
time; on the GPU a workgroup runs until its slowest pixel, so the saving only
lands where whole tiles converge. RaytraceSettings::final_quality() turns it
off.
What is simulated: multi-bounce diffuse and glossy GI; the principled BSDF
(Lambert + anisotropic GGX + rough dielectric transmission + clearcoat) with
Kulla–Conty energy compensation; emissive geometry as area lights;
Directional / Point / Spot / RectArea lights, optionally with an angular
or spherical size for soft shadows; Ambient and Hemisphere lights and
scene.environment as importance-sampled image-based lighting; alpha cutouts
whose shadows are cutout-shaped; Beer–Lambert absorption inside transmissive
solids; depth of field.
What is not: participating media, subsurface scattering, spectral dispersion,
and caustics through next-event estimation. Materials with no physical reading —
MeshNormalMaterial, MeshToonMaterial, ShaderMaterial — are mapped to the
nearest surface that has one, and every such choice is listed in
renderer.report().approximated rather than made silently.
Metal backend (Apple)
--features metal, macOS and iOS. A second renderer for the same Scene, written
against the Objective-C runtime directly: objc_msgSend declared and transmuted
per call site in src/metal/objc.rs, frameworks pulled in with
#[link(kind = "framework")]. No metal-rs, no objc crate, no build script,
and no new dependency — the feature adds a directory, not a line to Cargo.lock.
On any other platform the feature compiles to nothing.
// Cargo.toml: threers = { version = "0.0.4", features = ["metal"] }
use MetalHeadlessRenderer;
let mut renderer = builder.size.msaa.build?;
let rgba = renderer.render_to_rgba?; // tightly packed RGBA8
On screen, given an NSView from any window toolkit:
use ;
let device = new?;
let mut renderer = with_device?;
let surface = unsafe ;
if let Some = surface.next_frame
Or into textures you already own — an AVFoundation pipeline, an MTKView, a
Core Image chain — with PassAttachments::from_raw.
Covers: meshes, instanced meshes, line segments, points and sprites; Basic,
Lambert, Phong, Standard, Physical, Normal, Depth, Toon, Matcap,
Line, Points and Sprite materials; one base-colour map with the sampler,
wrap modes and UV transform from the Texture; ambient, directional, point, spot
and hemisphere lights; linear and exp² fog; alpha blend, alpha test, vertex
colours, wireframe, MSAA, and depth-sorted transparency. Geometry, textures,
samplers and pipeline states are cached across frames.
Does not cover — use the wgpu Renderer for these: shadow maps,
post-processing, environment maps and IBL (so a metal-heavy material has only its
specular highlights), skinning and morph targets, and the normal / roughness /
metalness / AO / emissive map slots. Materials outside the list draw unlit in
their base colour rather than failing, so a scene authored for the wgpu path
still renders. Both backends share the same conventions — 0..1 clip depth, CCW
front faces, flip_y applied at upload, three.js punctual attenuation — so the
two agree on a scene as far as this one goes.
visionOS
--features visionos (which implies metal). An immersive visionOS app owns no
layer and no swap chain: SwiftUI hands it a cp_layer_renderer_t and it pulls
frames. That API is C rather than Objective-C, so this is extern "C"
declarations transcribed from the XROS SDK headers — still no new dependency, no
build script, no metal-rs.
// Cargo.toml: threers = { version = "0.0.4", features = ["visionos"] }
use ImmersiveRenderer;
pub extern "C"
// The Swift side is one call.
ImmersiveSpace(id: "scene") {
CompositorLayer(configuration: MyConfiguration()) { layerRenderer in
threers_visionos_run(Unmanaged.passUnretained(layerRenderer).toOpaque())
}
}
What it does per frame: waits for the compositor's optimal input time, asks
ARKit for the device anchor at the predicted presentation time, takes the
drawable's textures and per-eye transforms, computes each eye's projection with
cp_drawable_compute_projection, draws, and presents on the same queue.
Both eyes in one pass. With the compositor's layered layout the eyes are
two slices of one texture array, and render_views draws them in a single pass —
the vertex stage reads its eye from the instance id and writes
render_target_array_index, so the second eye costs pixels, not a second walk
of the scene graph. The dedicated and shared layouts work too, one pass per
eye. Reverse-Z throughout, because the compositor accepts nothing else
(drawable.h: "It only supports reverse-Z depth").
Both of those work on any Mac, which is where they are tested — cargo test --features metal renders a stereo pair into a two-slice array offscreen and
checks each eye's parallax, and renders a reverse-Z scene and checks the depth
test inverted with it:
Building for the device. The
visionoscode is written against the XROS SDK and verified against it (everycp_*andar_*symbol checked against the SDK stubs, and the whole frame loop compiled and linked against the same two frameworks on macOS 26). Building the whole crate foraarch64-apple-visionosdoes not work yet, and the reason is upstream: wgpu 0.20 predates visionOS, so itscfg(all(unix, not(ios), not(macos)))routes the target into the Vulkan backend, which pullsash→libloading 0.7, which has noRTLD_*constants for it. It clears when the crate moves to a wgpu that knows the target, or whenwgpubecomes an optional dependency — nothing insrc/metalneeds it.
Native codecs (GIF, APNG, VP9, H.264, HEVC)
Enable native-codec for dependency-free encoders (and a GIF decoder) that also build on wasm32:
// Cargo.toml: threers = { version = "0.0.4", features = ["native-codec"] }
use ;
let mut enc = new
.colors
.dither
.diff_rects
.palette_mode;
// enc.add_frame(&rgba, 1, 10);
let bytes = enc.finish;
let = decode_gif.unwrap;
See threers::codec module docs and tests/{gif,apng,webm,h264_*,hevc_*}.rs for VP9/WebM, APNG, H.264/MP4, and HEVC usage.
Subtitles and captions
threers::captions is always available — pure Rust, no dependencies, no font
files, and it builds for wasm32. It parses and writes SubRip and WebVTT,
rasterizes cue text, and hands the pixels to whichever path you need.
On screen — the renderer blends the active cue over the frame it just drew:
use ;
let track = parse?;
let mut overlay = new.auto_scale;
renderer.render;
renderer.draw_caption_overlay;
The text is rasterized only when the active cue changes, so a frame in the middle of a cue costs one texture upload — and a frame with no cue costs nothing.
In an exported video — pick how the cues ship:
use ;
new
.size.frames.fps.codec
.captions
.caption_mode // pixels *and* out.srt
.export?;
CaptionMode |
Result |
|---|---|
Burn (default) |
text composited into the frames — works with every codec, including GIF and APNG |
Sidecar |
a separate out.srt / out.vtt beside the video |
Embed |
a soft subtitle track in the container: MP4 mov_text, WebM WebVTT |
BurnAndSidecar |
both of the first two |
Styling is a CaptionStyle — type size, fill, outline, shadow, background box,
alignment, frame anchor, margins, and wrap width — and for_height rescales a
1080p-authored style for any output size. Text draws with a built-in 8×8 bitmap
face by default (zero assets, Latin-1 accents fold to their base letter); pass a
.ttf to CaptionFont::from_ttf_bytes / VideoOptions::caption_font for real
typography.
The muxers can also write soft subtitles without ffmpeg:
codec::mp4::mux_hevc_with_captions (a tx3g timed-text track) and
codec::webm::mux_webm_with_captions (a D_WEBVTT/SUBTITLES track). Both are
round-trip verified against ffmpeg in tests/captions_mux.rs.
In the browser, renderer.setCaptions(overlay) makes every render() draw the
current cue — see web/examples/captions.html:
import THREE from './web/threejs-shim.js';
const overlay = ;
overlay.;
renderer.;
renderer. = video.; // then render() as usual
Animating OpenSCAD models
OpenSCAD animates by re-evaluating the whole program with $t stepped from 0 to
1 — geometry is a function of time. openscad::animate drives that loop and
renders it.
use ;
let mut animation = from_file.frames.fps;
new
.supersample
.camera
.export_video?;
color()survives evaluation.Solid::parts()splits the model into separately colored pieces — CSS names,#rrggbb,[r,g,b,a], and alpha for see-through parts. Booleans distribute over the pieces exactly, so a cut through a colored body keeps its color. A model with nocolor()is still one part, identical toto_geometry_exact().- Cameras that frame the model:
Autofits it exactly (a per-corner frustum fit, not a loose bounding sphere),Turntableorbits at a fixed distance so the model does not breathe,Viewportobeys the model's own$vpr/$vpt/$vpd— including written as functions of$t— andFixedtakes an explicit eye and target. Z-up, like every model written for OpenSCAD. - It avoids the work where it can. A model that never reads
$tis evaluated once and shared by every frame; the rest are evaluated several at a time (concurrency, defaultmin(4, cores)), which is ~3× on the example model.--features paralleladditionally parallelises the CSG inside a frame. - Output:
render_frames(RGBA),render_png,export_png_sequence, andexport_video/export_video_with— the latter takes aVideoOptions, so subtitles and codec settings come along.
Colors. A ScadPalette is a background plus a cycle of part colors; eight
ship built in (studio, cornfield, metallic, sunset, midnight,
blueprint, nature, monochrome) and ScadPalette::from_hex takes your own.
ScadColoring decides where a part's color comes from:
use ;
new
.palette // also sets the background
.coloring // ignore color(), re-skin the model
// …or ModelThenPalette: keep color() and dress only the untagged parts
.part_colors; // explicit list
Lights. The default is a three-point studio rig placed relative to the camera, so a turntable never rotates the model into its own shadow — the usual failure of a fixed rig. The key light casts shadows, sized to the model's bounds.
use ;
new
// Camera-relative key/fill/rim over a sky-and-ground hemisphere.
.lighting
// …or a fixed sun, so the shading says which way a face points:
.lighting
// …or flat and shadowless, like the OpenSCAD GUI:
.lighting
// …or exactly what you specify:
.lighting;
Ambient light comes from the palette — each scheme carries its own sky and
ground colors, so blueprint is lit coolly and sunset warmly with no extra
setup.
Speed comes in three flavours, because "faster" can mean three things:
| Knob | Changes |
|---|---|
speed(2.0) / seconds(4.0) |
how fast it plays — same frames, different frame rate |
ping_pong(true) / easing(…) |
how fast the model moves through the loop |
quality(ScadQuality::Draft) |
how fast it renders — kernel, curve resolution, supersampling |
use ;
let animation = from_file
.frames
.seconds // retime the loop
.speed // …then play it at half speed
.ping_pong // out and back, no snap at the loop point
.easing // accelerate away from rest, settle at the end
.quality; // rough it in first
Driving a model from Rust rather than $t works the same way:
// Any root-scope name can be the animation variable.
let animation = from_file
.frames
.var
.var;
// …or skip `.scad` entirely and animate the Rust DSL.
let animation = from_fn;
Web (browser)
Build the wasm package and serve the repo root (or use the parity server below):
# Default (no mesh-bvh / CSG addon)
&&
# Or via the feature build scripts:
MESH_BVH=1 BVH_CSG=1 NATIVE_CODEC=1 OPENSCAD=1
OpenSCAD in the browser (after OPENSCAD=1 build): the live playground
web/openscad-playground.html parses .scad code
to a watertight mesh and renders it with WebGPU, with STL/OBJ/OFF/3MF/GLB download.
See also the demo gallery and the parametric 3D-printer / NEMA-17 assemblies
(web/openscad-gallery.html, web/openscad-printer.html, web/nema17.html).
Export video in the browser (after NATIVE_CODEC=1 build): open
web/examples/export-video.html — render frames, encode GIF/APNG/WebM/MP4 in-process, download the file. No ffmpeg.
JS/TS API (native-codec wasm) — prefer VideoExporter:
import from '/web/threejs-shim.js';
await ;
;
const result = await
.
.
. // pipeline GPU readbacks (1–8)
.
.
.
.;
// or events:
// exporter.on(VideoExportEvent.Progress, (e) => …)
// exporter.on(VideoExportEvent.Complete, ({ detail }) => …)
Trace progress with events:
exporter
.
.;
Rust (same event model via callbacks):
use ;
new
.size
.frames
.fps
.codec
.on_progress
.on_event
.export?;
Shorthands: .gif(), .apng(), .webm({ alpha: true }), .mp4(). Format strings like "webm-alpha" and "h264" work via .format(...) / parseVideoFormat. Filenames need no extension ("cube" → "cube.gif"). Scene size defaults to the canvas; WebM sizes snap to multiples of 8, MP4 to even dimensions. .parallel(N) overlaps render + async pixel readback across N targets. .worker(true) streams frames into a Web Worker (video-export-worker.js) while capture continues.
Buffer-only: VideoExporter.encode(frames, { width, height, format, … }) or encodeVideoFramesInWorker(...) from /web/video-export.js.
Headless check (needs Chromium + NATIVE_CODEC=1 wasm):
NATIVE_CODEC=1
&&
Then load web/examples/index.html or any page that imports /web/threejs-shim.js and calls initThreers('/web/pkg/threers_bg.wasm').
import THREE from '/web/threejs-shim.js';
await ;
const renderer = await THREE.;
// … same patterns as three.js
CSG in the browser (after BVH_CSG=1 build):
import from '/web/bvh-csg-addon.js';
;
Earth, sun and lens flare
A full PBR scene with no downloaded assets. Five equirectangular maps — albedo,
normal, roughness, night lights and clouds — are generated from one shared
elevation field, so the coastlines in the colour map, the relief in the normal
map, the shine on the oceans and the shoreline glow of the city lights all line
up. At --texture 8192 that is five 33.6-Mtexel maps, built in under a second
across cores.
The noise is sampled in 3D on the sphere rather than in UV space, which is what keeps an equirectangular map free of both a date-line seam and the smearing that 2D noise suffers at the poles. The lens flare and the atmosphere rim are composited in screen space after the render — a flare is a property of the camera, not the scene, and doing it there is what lets it be occluded as Earth passes in front of the sun.
Rendering it needs mip-mapped textures to not shimmer, which the renderer now builds for every 2D texture.
Planets (planet)
earth_sun_flare builds all of that by hand. The planet feature is the same
machinery as an API, so a believable planet is a builder rather than a thousand
lines of example:
// Cargo.toml: threers = { version = "0.0.4", features = ["planet"] }
use ;
let mut scene = new;
// Real NASA imagery where it is on disk, generated maps for whatever is not.
let maps = from_dir.load;
let earth = earth.maps.add_to;
procedural.add_to;
Planet::add_to puts three objects in the scene and returns their ids: the
body, a cloud shell above it, and an atmosphere above that. The details that are
easy to get wrong are handled — colour maps tagged sRGB and data maps not,
longitude wrapping while latitude clamps, cloud cover living in the alpha
channel, the night map gating the emissive so city lights do not flood the day
side, and the atmosphere shaded as a volume the view ray passes through rather
than as a surface.
The browser port (web/examples/earth.html) builds the globe from eight
sphere patches, each streaming its own NASA tile at 1024, 2048 or 4096 px
depending on how close the camera is and whether the patch faces it. That is a
16384x8192 globe at the top level — a single-texture globe cannot exceed
8192x4096, because that is all WebGPU guarantees for one texture. Sliders drive
the sun's longitude and height, city-light brightness, atmosphere strength,
cloud cover and relief.
The Moon is there at its real distance — 60.3 Earth radii, on a Keplerian
ellipse with the actual eccentricity, inclination and sidereal period, tidally
locked, sharing Earth's clock. That makes it four pixels wide from anywhere that
frames Earth, so the scene opens beside it and flies in: a held shot by the
Moon, a turn to Earth while it is still a distant blue marble, then an eased
descent into orbit that hands over to OrbitControls. replay intro runs it
again; ?flyover=0 skips it.
Without the download the example still runs: every map falls back to a procedural one built from a shared elevation field. With it, you get Blue Marble surface colour, Black Marble city lights, a MODIS cloud composite, relief and ocean gloss derived from GEBCO elevation, the CGI Moon Kit Moon (LRO colour + LOLA relief), and the Deep Star Maps sky — the last read straight out of its ZIP-compressed OpenEXR as half-float, because over half of that map sits below 1/100th of full scale and clipping it to 8 bits leaves a black sky.
RLX bridge
RLX is an ML compiler and runtime. The rlx
and rlx-geo features put it beside the renderer — the renderer is unchanged
either way — and convert between the two crates' data: vertex attributes and
pixels become tensors of a declared shape, tensors become attributes and
textures. Both features are off by default and both build for wasm32 as well as
native.
# Cargo.toml
= { = "0.0.4", = ["rlx", "rlx-geo"] }
use ;
// A 3×3 convolution, compiled once and run per frame.
let mut sharpen = new;
let crisp = sharpen.apply?;
// Mesh smoothing as a graph over the [n, 3] positions tensor.
taubin_smooth?;
// A colour grade *learned* from a reference, by gradient descent.
let report = fit?;
let graded = report.grade.apply;
| Example | Features | What it shows |
|---|---|---|
rlx_frame_filter |
rlx |
A Reinhard tone map as three IR nodes over a rendered frame |
rlx_conv_postfx |
rlx |
Blur / sharpen / Sobel / Laplacian / emboss, plus CPU-vs-GPU timings |
rlx_mesh_smooth |
rlx |
Laplacian against Taubin smoothing, with the volume each one keeps |
rlx_fit_grade |
rlx |
Learns a colour grade from a reference, then transfers it to another shot |
rlx_video_grade |
rlx,video,native-codec |
The compiled grade applied across 60 frames → GIF |
rlx_palette |
rlx,rlx-geo |
k-means palette, posterise, and a Voronoi mosaic snapped to it |
rlx_geo_terrain |
rlx-geo |
Scattered samples → exact Delaunay mesh, plus a Voronoi map |
rlx_geo_materials |
rlx-geo |
Cell textures: albedo, roughness and normals from wall distance |
rlx_geo_refine |
rlx-geo |
Adaptive refinement against a uniform grid at equal vertex budget |
rlx_geo_erosion |
rlx,rlx-geo |
120 diffusion passes over a terrain, one compiled graph |
In the browser
RLX=1 web/build.sh (and RLX_GEO=1) exports the same work as rlxConvolve,
rlxDiffuse, rlxSmoothMesh, rlxFitGrade, rlxApplyGrade, rlxPalette,
rlxPosterize, geoDelaunay, geoHeightfield, geoVoronoiLabels,
geoVoronoiWallDistance and geoNormalMap — plain typed arrays in and out.
Run them in a worker. web/rlx-worker.js is one, and web/rlx-bench.html
drives it: every op is tens of milliseconds, which on the main thread is a
dropped frame or twenty. Pixel buffers go in the transfer list rather than
being cloned — a 4K frame is 33 MB, and copying it costs more than filtering
it does.
const worker = ;
worker.; // ← transferred, not copied
rlx's GPU backend is available on wasm32 as of the wgpu 30 upgrade. It used
not to be: rlx was on wgpu 30 while this renderer was on wgpu 0.20, and two
majors in one wasm binary both generate bindings for the same WebGPU interfaces,
which wasm-bindgen rejects outright (duplicate string enums: GpuAutoLayoutMode). The Rust compiled — it was the bindgen step that could not
resolve it — so the browser build left rlx's gpu feature off. Both are wgpu 30
now, one set of bindings, and wasm-bindgen accepts the build. Ask
rlxDevices() at startup rather than assuming: whether a given browser then
hands you a working WebGPU adapter is still its own question.
Two numbers from those examples, since both cut against the feature as much as for it. Adaptive refinement reaches ~9× lower error than a uniform grid of the same vertex count — worth having. A 640×640 convolution costs ~10 ms per frame through host memory against ~5 ms to render the frame in the first place — so for effects that belong to the frame, the renderer's own post-processing chain is still the better tool. What the bridge buys is a kernel in the same graph as the rest of the pipeline, and one autodiff can see.
Speed
preferred_device() returns the CPU
for a reason — the GPU column is what rlx's own priority order would have
picked:
Milliseconds, best of five. Native is an M-series laptop; the browser column is
Chrome 131 running web/rlx-bench.html, measured by
web/scripts/rlx-bench-validate.mjs. preferred_device() returns the CPU
for a reason — the GPU column is what rlx's own priority order would pick:
| operation | native CPU | native GPU | Chrome (wasm) |
|---|---|---|---|
ConvFilter gaussian, 512² |
11.3 | 17.6 | 45.3 |
Palette::extract, 8 colours |
29.7 | 67.0 | 34.1 |
posterize, 512² |
22.8 | 47.6 | 53.0 |
ColorGrade::fit, 400 steps |
479 | 29 312 | 481 |
Diffusion, 20 passes, 256² |
3.9 | 15.6 | 6.6 |
taubin_smooth, 8 iterations |
8.9 | 33.3 | 12.5 |
voronoi_labels, 400 sites, 512² |
106 | — | 87 |
delaunay, 5 000 points |
0.9 | — | 8.3 |
Wasm costs 1–4× native across most of the table, and the fit — the one that
matters — is at parity (481 ms against 479). delaunay is the outlier at 9×,
and that is not the engine: the browser takes rlx-geo's Guibas-Stolfi path
because the Dwyer one calls a clock wasm does not have (see below). Measured on
the same target, that path costs 1.9–2.4× the Dwyer build for identical output.
Run-to-run variance on this machine is up to ~1.5×, and the fit is the noisiest
row.
The GPU column is the finding: every one of these is either small or a chain of
dependent steps, and dispatch latency eats the arithmetic. fit is 400 round
trips, hence 61×. Convolution crosses over around four megapixels — at
3840×2160 the GPU takes 373 ms against the CPU's 920 — so pass Device::Gpu
explicitly for work that size.
Why the worker, measured
Five 512² convolutions, driven from the page, counting animation frames:
| time | frames painted | |
|---|---|---|
| on the main thread | 338 ms | 0 |
| in the worker | 341 ms | 22 |
Same work, same wasm, no measurable throughput cost — and the page keeps
painting instead of freezing solid. node web/scripts/rlx-bench-validate.mjs
reproduces both columns in headless Chrome.
Payload
wasm-bindgen --target web, bytes, against the same build without the feature:
| build | raw | gzip | brotli |
|---|---|---|---|
| baseline (default features) | 1 368 963 | 395 840 | 300 916 |
+rlx-geo |
1 439 365 | 418 025 | 317 030 |
+rlx |
6 511 319 | 1 476 290 | 976 191 |
+rlx,rlx-geo |
6 583 531 | 1 497 478 | 990 578 |
rlx-geo costs 16 KB brotli — it is a triangulator and a predicate kernel.
rlx costs 675 KB brotli, a 3.2× payload, because it brings a whole ML
compiler: IR, autodiff, fusion, the compile pipeline and a CPU backend. That is
a real decision for a web build, not a rounding error, which is why it is its
own flag and off by default.
Physics
Rigid-body physics lives in the companion crate
threers-physics, a workspace member:
[]
= "0.0.4"
= "0.0.1"
use *;
let mut world = new;
world.add_body;
let ball = world.add_body;
world.step; // per frame
world.sync_to_scene_interpolated;
Shapes, joints, sleeping, collision filtering, sensors, raycasts, shape casts, inverse kinematics (FABRIK and cyclic coordinate descent), a kinematic character controller, raycast vehicles and routed tendons. Bodies can opt into continuous collision detection, so a projectile is swept rather than sampled and cannot cross a thin wall between two frames. Colliders can be built straight from the geometry you are already drawing.
Optional features: parallel (rayon narrow phase, native), gpu (broad phase on
a wgpu compute shader — works on wasm32/WebGPU, where rayon cannot run), async
(tokio), openscad (colliders straight from Solids, no STL round trip). Full
documentation in the crate README.
Mechanisms
threers-mechanism-tourisexcluded from the workspace: it builds as a library, but its examples still call an older shape of its own API, so thecargo run -p threers-mechanism-tour …lines below need that reconciled first.threers-robot-armandthreers-physics-benchare members and build. See docs/releasing.md.
A .scad file can declare its own parts, joints and drives, and the assembly
stack reads them: it puts the mechanism together, checks it for interference,
sweeps its travel, runs it, records the run as poses, reduces that to keyframes,
and then asks the geometry whether the declarations were true.
The mechanism tour — twelve mechanisms in a browser.
(The banner picture is regenerated by cargo run -p threers-mechanism-tour --example look --docs,
which needs that crate back in the workspace first.)
threers-mechanism-tour is twelve of them in a
browser — a bench, a pendulum, a gear train, a four-bar, a slider-crank, a
universal joint, a worm and wheel, a Geneva, a cam, a ratchet, a stage and a
latched gate. Four have a closed form to check against and none has it written
down: the pendulum's period lands within 0.04% of 2π√(I/mgd), the slider-crank's
piston within 0.006 mm of R·sinφ + √(L²−R²cos²φ), the universal joint's wobble
within 0.01° of tan θ_out = cos β·tan θ_in, and the cam's lift within 0.1 mm rms.
Joints have bearings: friction and bearing = [mu, radius] give a mate
Coulomb friction of its own, scaled by what it carries. That is what makes a worm
drive irreversible — driven backwards, a frictionless mesh spins the worm 3,022°
and one at μ 0.05 moves it 0.0°, while driving forward costs 1.2%.
OpenSCAD parts, without an STL round trip
A Solid evaluates straight to the same BufferGeometry the renderer draws, so
the collider and the mesh come from one evaluation:
use SolidPhysics;
let part = dynamic
.density
.fit
.build
.unwrap;
let = part.spawn;
A machine that has to survive its own numbers
threers-robot-arm is a four-axis pick-and-place
cell that runs the same programme on two different machines — one kinematic,
one built from dynamic bodies and PI position servos — so what you are looking
at is the difference between the models rather than between two demos.
It is also where the physics gets held to account. performance runs the whole
trajectory, differentiates it for accelerations, and sums
τ = Σ [(c−p) × m(a−g) + Iα + ω×Iω] · axle per axis — so the motors are chosen
against measured demand, and every link section is sized against the peak bending
moment and torsion at its own root, checked for stiffness and for strength:
axis motor holding peak rms headroom
base yaw NEMA 17 0.00Nm 0.33Nm 0.06Nm 6.9×
shoulder NEMA 23 1.37Nm 1.89Nm 0.90Nm 2.9×
elbow NEMA 17 0.56Nm 1.09Nm 0.36Nm 2.1×
wrist NEMA 11 0.07Nm 0.36Nm 0.05Nm 1.9×
link section mass bending torsion margin sized by
upper arm 20×26 mm 92 g 1.89 Nm 0.38 Nm 4.1× stiffness
forearm 16×21 mm 58 g 1.09 Nm 0.12 Nm 4.5× stiffness
wrist 14×14 mm 35 g 0.36 Nm 0.09 Nm 6.6× printability
The loop is closed — the simulation weighs what the optimiser specifies, to within 1% — so those torques are the torques of the arm as drawn.
Browser benchmark
Six scenes — stacking, bouncing, chains, orbits, mixed shapes, bullets — with live step-time, body count and sleep stats, and switchable quality presets.
Parity compare UI
Side-by-side three.js r165 vs threers wasm for 113 regression scenes:
Open http://localhost:8087/ — navigate scenes, toggle light/dark theme, view source (JS / TS / Rust tabs).
CI helpers: scripts/ci-mesh-bvh.sh, scripts/ci-bvh-csg.sh.
After changing Rust or wasm, rebuild and hard-refresh the browser (⌘⇧R) or click ↻ in the compare UI so cached wasm/shim are busted.
Project layout
src/ Rust library (scene graph, renderer, loaders, …)
codec/ Pure-Rust media codecs (`native-codec`)
video.rs Frame-sequence export (`video`, native)
renderer/ wgpu pipelines, post-fx, headless offscreen
metal/ Metal backend (`metal`, macOS/iOS) — objc runtime, MSL, headless + CAMetalLayer
metal/visionos/ visionOS (`visionos`) — CompositorServices frame loop, ARKit world tracking
prelude.rs `use threers::prelude::*`
materials/ PBR + ShaderMaterial
csg/ Rust CSG (`bvh-csg`) — Evaluator, Brush, hierarchy
mesh_bvh/ Rust BVH (`mesh-bvh`)
openscad/ OpenSCAD front end (`openscad`) — scad interpreter, Solid/scad! DSL
exact_csg/ Watertight mesh-arrangement CSG kernel (curved∧curved)
rlx/ RLX bridge (`rlx`, `rlx-geo`) — tensors, graph runner, Delaunay
wasm.rs #[wasm_bindgen] exports (web only)
web/
threejs-shim.js THREE-compatible JS API over wasm
openscad-*.html OpenSCAD playground / gallery / assemblies
csg/ JS three-bvh-csg port (loaded when BVH_CSG=1)
robot-arm/ Scrubbable player for the robot cell
physics-bench/ Physics benchmark UI
mesh-bvh-*.js mesh-bvh addon / stub
pkg/ wasm-pack output (threers.js, threers_bg.wasm)
post-build.sh Patches wasm glue for Safari; generates .d.ts
crates/
threers-physics/ Rigid bodies, joints, queries, IK, swept CCD, vehicles, tendons
threers-probe/ Screen-space neural GI from a G-buffer and lighting probes
threers-continuum/ Tendon-driven continuum robots: elastic-hinge rods, cables
threers-mechanism-tour/ Twelve .scad mechanisms, assembled and checked
threers-animation/ Easing, tweens, springs, timelines, ragdoll blending
threers-js/ npm / Deno / Node ESM publish root (THREE shim + wasm)
threers-node/ npm native Node addon (napi-rs; per-arch @threers/node-*)
threers-py/ PyPI publish root (PyO3 / maturin)
threers-ocean/ Ocean-water demo, as a browser package
threers-physics-bench/ Browser benchmark (six scenes)
threers-robot-arm/ Pick-and-place cell + inverse-dynamics sizing
tests/ Codec / video integration tests + parity/
examples/ Native demos (cube, headless_video, shader_material, …)
scripts/ Feature CI (mesh-bvh, bvh-csg)
CHANGELOG.md Release history
Architecture
┌─────────────────────────────────────────────────────────┐
│ Browser: three.js app code (or parity scene HTML) │
│ ↓ import │
│ web/threejs-shim.js ──► wasm WebRenderer / WebScene │
│ (+ optional mesh-bvh / bvh-csg addons) │
└──────────────────────────────┬──────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ Rust: Scene → Renderer (wgpu) → surface or RenderTarget │
│ Materials / lights / post-fx (EffectComposer) │
│ Optional: MeshBvh, CsgEvaluator │
│ Optional: HeadlessRenderer → video / native-codec │
└──────────────────────────────────────────────────────────┘
- Native path:
Renderer::new(device, queue, format)→render()/render_to(); orHeadlessRendererfor offscreen RGBA. - Web path:
WebRendererowns the wgpu surface for a<canvas>; render targets and post-fx are registered by integer id across the JS boundary. - Post-fx: A single WGSL module (
src/renderer/shader.rs) switches oneffect_kind(copy, FXAA, glitch, bloom, …). The JSEffectComposermirrors three.js pass order. - CSG: Rust
CsgEvaluatorfor native/tests; browser parity scenes use the JS port underweb/csg/with wasm BVH for splits. - Codecs:
native-codecencodes/decodes in-process (no ffmpeg);videoshells out to ffmpeg except for GIF/APNG/WebM/H.264 when both features are enabled.
Development
| Task | Command |
|---|---|
| Native check | cargo build |
| With CSG | cargo build --features bvh-csg |
| Video + codecs | cargo build --features "video,native-codec" |
| CSG unit/parity tests | cargo test --features bvh-csg --lib csg |
| GIF codec tests | cargo test --features native-codec --lib codec::gif --test gif |
| H.264 codec tests | cargo test --features native-codec --test h264_ffmpeg --test h264_animation_parity |
| H.264 wgpu GPU | cargo test --features native-codec --test h264_gpu |
| H.264 Metal GPU | cargo test --features "metal,native-codec" --test h264_metal |
| Planet tests (incl. GPU) | cargo test --features planet --lib planet --test planet_render |
| RLX bridge tests | cargo test --features "rlx,rlx-geo" --lib rlx:: --test rlx_bridge |
| No default features | cargo build --no-default-features (drops captions) |
| Wasm release | wasm-pack build --target web --out-dir web/pkg && bash web/post-build.sh |
| Feature wasm | BVH_CSG=1 / MESH_BVH=1 / NATIVE_CODEC=1 web/build.sh |
| Physics tests | cargo test -p threers-physics -p threers-animation |
| Robot cell | cargo run -p threers-robot-arm --example console |
| Robot cell (wasm player) | crates/threers-robot-arm/build.sh |
| Parity scenes | cd tests/parity && node generate-scenes.js |
| Rust scene snippets (parity UI Rust tab) | cd tests/parity && node generate-rust-scenes.js |
| Regenerate shim types | node web/scripts/generate-shim-types.mjs (also runs in post-build) |
| Docs | cargo doc --features "video,native-codec" --open |
| Release versions | ./scripts/release-versions.sh |
| Release build/pack | ./scripts/release-all.sh pack — npm mini+full, node, PyPI wheel |
| Release publish | PUBLISH=1 ./scripts/release-all.sh publish — see docs/releasing.md |
Status
Active development toward pixel parity with three.js r165 on the core parity scene set. Opt-in mesh-bvh and bvh-csg suites report 0% pixel diff on their dedicated manifests; hierarchy CSG also has exact ordered TriKey topology parity in Rust vs JS.
The openscad front end is functional end to end: the exact-CSG kernel produces watertight meshes for planar and curved∧curved booleans (verified by cross-op volume consistency + a 2-manifold gate), deferring to the float kernel only on measure-zero degeneracies. Remaining edges: minkowski/color in the DSL, some 3MF component metadata, and per-boolean cost on very large sequential folds.
Some core scenes are approximate (PMREM, SSR, etc.) — the compare UI marks these and stores diff percentages in compare-results.json. See docs/ for the roadmap notes and CHANGELOG.md for release history.
License
MIT