threers 0.0.7

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.0.7 · 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, and keep writing three.js:

import THREE, { initThreers } from '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
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
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) 2D and 3D fluids as render passes, so they run on WebGL2 too
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 35 lattice generators with physical properties; foldable sheets
USD (usd) · glTF · Draco · KTX2 · Alembic Interchange, read and written where the format allows
Video (video, native-codec, gif) · Captions · SVG GIF, APNG, WebM, H.264 and HEVC in pure Rust; SRT/WebVTT; vector output
Metal and visionOS (metal, visionos) A second renderer on Metal, and the CompositorServices loop
RLX (rlx, rlx-geo) · Physics Tensors and learned grading; rigid bodies in threers-physics

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.

Examples

66 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 captions_render cuboct data_charts
denoise_ab denoise_compare 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_shapes 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 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 scad_profile shadow_types
simcity_render skinned_animation spacecraft_render starfield_probe
svg_gallery tower_collapse ui_panel usd_stage
viewport_path_trace volume_slices

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

Documentation

Start with getting started. Every guide is in docs/, and each one stands alone: architecture · controls · animation · camera animation · scroll video · parity with three.js · releasing.

License

MIT