threers 0.1.0

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
Documentation

threers

A drop-in three.js replacement for Rust and the browser, on wgpu. One Rust core runs natively, headless, and as WebAssembly on WebGPU or WebGL2. A JavaScript shim exposes the THREE.* API, so existing three.js code runs with an import change.

crates.io docs.rs · 0.1.0 · Changelog · MIT

Quick start

Rust: cargo add threers, then render a frame to a PNG with no window:

use threers::prelude::*;

fn main() {
    let mut scene = Scene::new();
    scene.add(Object3D::mesh(Mesh::new(
        BoxGeometry::new(1.0, 1.0, 1.0),
        Material::Standard(StandardMaterial::new(Color::from_hex(0xff8844))),
    )));
    let mut sun = DirectionalLight::new(Color::WHITE, 3.0);
    sun.direction = Vector3::new(-1.0, -2.0, -1.5).normalize();
    scene.add_light(sun);
    scene.add_light(AmbientLight::new(Color::WHITE, 0.4));

    let mut camera = PerspectiveCamera::new(50.0, 16.0 / 9.0, 0.1, 100.0);
    camera.position = Vector3::new(3.0, 2.0, 4.0);
    camera.look_at(Vector3::ZERO);

    let mut renderer = HeadlessRenderer::builder().size(1280, 720).build().unwrap();
    renderer.set_msaa(4); // antialiasing: off by default, as in three.js
    let rgba = renderer.render_to_rgba(&mut scene, &camera);
    std::fs::write("cube.png", threers::encode_png(1280, 720, &rgba)).unwrap();
}

Browser: npm i @threers/threers, and keep writing three.js:

import THREE, { initThreers } from '@threers/threers';

await initThreers();
const renderer = await THREE.WebGLRenderer.create(canvas, { antialias: true });
const scene = new THREE.Scene();
scene.add(new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshStandardMaterial({ color: 0xff8844 }),
));
scene.add(new THREE.DirectionalLight(0xffffff, 3));
scene.add(new THREE.AmbientLight(0xffffff, 0.4));
const camera = new THREE.PerspectiveCamera(50, 16 / 9, 0.1, 100);
camera.position.set(3, 2, 4);
camera.lookAt(0, 0, 0);
renderer.render(scene, camera);

The shader does its own tone mapping and output encoding, because Chrome's WebGPU canvas is bgra8unorm rather than sRGB. Use the canvas's preferred format and leave colour to threers (Web). Python and Node bindings: docs/bindings.md.

What's in it

The core is unconditional: scene graph, geometry, PBR materials, lights and shadows, custom WGSL, post-processing, controls, animation, and loaders for glTF, OBJ, STL, PLY, FBX, Collada, HDR and EXR. Each of the following is a self-contained subsystem, behind a Cargo feature where it says so.

Materials Clearcoat, transmission, dispersion, anisotropy, sheen, iridescence; HDR pipeline, IBL, area lights
Fur and hair Shell fur and strand hair, on static or skinned meshes: wind, drag and inertia, shadows, MSAA per strand, a hand that strokes them; THREE.Fur and THREE.Hair in the shim, demo in web/examples/fur.html
Particles, snow and sand Emitters with drag, turbulence and buoyancy; snow and sand that pile up at their angle of repose, drift and form dunes; lit, shadowed, black-body fire and smoke; GPU weather; dune seas shaded after Journey's sand; THREE.Particles, THREE.SandBed and THREE.DesertSky in the shim, demos in web/examples/particles.html and dunes.html
Gaussian splats (splats) Captured scenes as millions of splats, drawn with the scene on WebGPU, WebGL2 and Metal: the reference trainer's PLY, compressed PLY, Niantic's .spz and .splat; projection and colour checked against the reference rasteriser; a SIMD radix sort; scene.addSplats in the browser, viewer in web/splats.html
Soft bodies Gummy creatures that tear and grow back: XPBD on tetrahedral lattices, built from SDF shapes, parts glued on, chains, goo; on the CPU (bit for bit the JavaScript original) or as WebGPU compute; THREE.SoftBody in the shim, demo in web/examples/jelly.html
Time smear Echoes in time over a rendered or decoded clip: moving things ghost at Gray-coded frames before and after themselves, still ones come back byte for byte; streams into the video exporters, any renderer (wgpu, Metal); THREE.TimeSmear in the shim, demo in web/examples/time-smear.html
Interactive effects · SDF Glossy liquids that react to the pointer on buttons and any shape (Venom, Gloss), as components, effects and a stage you can add to; exact 2D/3D signed distance fields with smooth operators, ray marching and meshing, the same in WGSL
Colour Colour spaces (OkLCh, CIELAB, HSV, …), every CSS Color 4 string, ColorBrewer and Tableau schemes, d3-style log, quantile and threshold scales
Marks Data layers for maps, from points, paths and polygons to labels, heatmaps and tiles. f64 precision, GPU filtering and picking, MapView and globe controls
Headless Offscreen rendering to RGBA, with no window or display; choosing the GPU, and testing on NVIDIA under Linux
Embedding Viewports on an app's own windows (Tauri, Wry, tao, winit, raw handles), lazy pipelines warmed on worker threads, and a pipeline cache kept between runs
Deploying A static site for Vercel, GitHub Pages, Netlify or Cloudflare: hashed wasm, preloading, caching headers, sizes
Web · WebGL2 (webgl) WebAssembly on WebGPU, or WebGL2 where WebGPU is missing
Path tracing (raytrace) Global illumination, refraction and depth of field, on CPU and GPU, with denoising
Fluid (fluid, metal-fluid) 2D and 3D fluids as render passes, so they run on WebGL2 too; both on Metal alone too, without wgpu
Planets (planet) Atmospheres, starfields, Earth from NASA imagery
Mesh BVH and CSG (mesh-bvh, bvh-csg) Accelerated raycasts, and booleans with three-bvh-csg parity
OpenSCAD (openscad) .scad front end, Solid DSL, watertight exact-CSG kernel
NURBS, B-rep, STEP (nurbs, brep, step) Exact curved surfaces, analytic booleans, ISO 10303-21
Lattices · Kirigami 44 lattice generators — TPMS, struts, textiles, infill, foams on random, crystal, relaxed and two-size seeds, grown grains, and scale-rich networks grown ligament by ligament in any polygon — with physical properties, print checks and simplification; foldable sheets
USD (usd) · glTF · Draco · KTX2 · Alembic Interchange, read and written where the format allows
Video (threers-video; native-codec, native-decode, gif, nvidia, vaapi) · Captions · SVG Video playing on meshes at up to 8K, colour converted on the GPU, with its soundtrack (VideoPlayer); GIF, APNG, WebM, H.264 and HEVC encoders, H.264/HEVC/VP9/AV1 and AAC/MP3/Opus/Vorbis/FLAC decoders in pure Rust (also standalone as threers-codec), hardware through VideoToolbox (macOS), NVENC/NVDEC (NVIDIA) and VAAPI (AMD, Intel); SRT/WebVTT; vector output
Metal and visionOS (metal, visionos) A second renderer on Metal, and the CompositorServices loop
XR (xr, xr-visionos) Headsets: any scene per eye, a UI on a panel, controllers, hands and look-and-pinch, on WebXR and natively on Apple Vision Pro; a new Vision Pro app with scripts/new-visionos-app.sh
RLX (rlx, rlx-geo) · Physics Tensors and learned grading; rigid bodies in threers-physics
Finite and boundary elements threers-fem: a tetrahedral mesher for any closed geometry; stress, natural frequencies and heat by FEM; capacitance and acoustic radiation and scattering by BEM; from Rust, the browser, Python and Node, demo in web/fem/
Games · tutorial threers-ecs: entities, components and systems over the scene graph, parallel systems, input, sound, physics and cars, dev tools, rewind and replays; runs in a window (wgpu or Metal), a browser or a Tauri app

Bundles turn on related features together: cad, media, gi, apple, full (native) and wasm-full (browser). The full table is in the crate docs. Long form: docs/features.md.

The core builds on its own: default-features = false is math, the scene graph, geometry, materials and loaders, with no GPU stack, and render adds the renderer. The pieces that stand alone are crates of their own — threers-math, threers-captions, threers-audio, threers-codec, threers-splat-sort and threers-ui underneath, threers-video, threers-physics and threers-animation on top.

Examples

Voronoi foams on random, Kelvin, Weaire–Phelan, C15, relaxed and two-size seeds — open, closed and wet (lattice_foams; see docs/lattices.md).

78 examples render a picture; each is in docs/examples.md with the command that makes it. They all run headless, so they work the same on a laptop and in CI.

backend_parity campfire captions_render cuboct
data_charts denoise_ab denoise_compare dunes
earth_sun_flare fluid3d fluid_render fur
fur_closeup fur_motion fur_stroke glass_modes
hair hdri_lighting ik_servo_demo kirigami
lattice lattice_engineering lattice_foams lattice_print
lattice_scale_rich lattice_shapes lattice_textiles map_demo
marks_map material_chart metal_headless metal_stereo
nema17 neon_logo ocean_water openscad_gallery
openscad_render origami origami_gallery origami_miura
origami_twist particles path_trace path_trace_gpu
pole_probe postfx_chain printer_assembly progressive_denoise
quad_view raspberry realistic_earth retrofuturism
rlx_conv_postfx rlx_fit_grade rlx_frame_filter rlx_geo_erosion
rlx_geo_materials rlx_geo_refine rlx_geo_terrain rlx_mesh_smooth
rlx_palette sand scad_profile shadow_types
simcity_render skinned_animation snow spacecraft_render
starfield_probe svg_gallery tower_collapse ui_panel
usd_stage venom_button venom_gallery viewport_path_trace
volume_slices splats splats · hornedlizard.spz splats · racoonfamily.spz

Interactive ones open a window, for example cargo run --release --example map_demo --features captions, --example marks_map or --example venom_button. The rest of examples/ export video or print numbers.

Gaussian splats (--features splats) load the trainer's PLY, compressed PLY, .spz and .splat, and web/splats.html views them in the browser; the two captures above are Niantic's .spz samples (MIT, from nianticlabs/spz). See docs/splats.md.

In the browser, web/examples/jelly.html is a set of gummy creatures you can pull apart: tentacles, arms, tails and ears tear off, twitch on the table and grow back. Each is a few THREE.SDF fields meshed by surface nets in wasm, on an XPBD soft body (THREE.SoftBody), drawn as refracting gel. See docs/softbody.md.

?creature=jellyfish ?creature=octopus ?creature=gecko ?creature=bear

Documentation

Start with getting started. Every guide is in docs/, and each one stands alone: architecture · controls · interactive effects · signed distance fields · soft bodies · Gaussian splats · time smear · animation · camera animation · scroll video · parity with three.js · releasing.

License

MIT