Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(material-presets): render the preset comparison sheet and its reference images

nirholas064bf774708f
diff --git a/docs/assets/material-presets/presets-neutral.png b/docs/assets/material-presets/presets-neutral.png
new file mode 100644
index 000000000..370025f80
Binary files /dev/null and b/docs/assets/material-presets/presets-neutral.png differ
diff --git a/docs/assets/material-presets/presets-none.png b/docs/assets/material-presets/presets-none.png
new file mode 100644
index 000000000..0a7ab819b
Binary files /dev/null and b/docs/assets/material-presets/presets-none.png differ
diff --git a/docs/assets/material-presets/presets-venice-sunset.png b/docs/assets/material-presets/presets-venice-sunset.png
new file mode 100644
index 000000000..c10c46018
Binary files /dev/null and b/docs/assets/material-presets/presets-venice-sunset.png differ
diff --git a/scripts/material-preset-sheet.html b/scripts/material-preset-sheet.html
new file mode 100644
index 000000000..8d6e8c592
--- /dev/null
+++ b/scripts/material-preset-sheet.html
@@ -0,0 +1,152 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <title>Material preset contact sheet</title>
+ <style>
+ html,
+ body {
+ margin: 0;
+ padding: 0;
+ background: #14161a;
+ color: #e8eaee;
+ font: 13px/1.4 system-ui, -apple-system, 'Segoe UI', sans-serif;
+ }
+ #sheet {
+ display: grid;
+ grid-template-columns: repeat(5, 200px);
+ gap: 10px;
+ padding: 16px;
+ }
+ figure {
+ margin: 0;
+ }
+ canvas {
+ display: block;
+ width: 200px;
+ height: 200px;
+ border-radius: 8px;
+ background: #0b0d10;
+ }
+ figcaption {
+ padding-top: 6px;
+ font-size: 12px;
+ letter-spacing: 0.01em;
+ color: #b9bfc9;
+ }
+ h1 {
+ margin: 0;
+ padding: 16px 16px 0;
+ font-size: 15px;
+ font-weight: 600;
+ }
+ </style>
+ </head>
+ <body>
+ <h1 id="title">loading</h1>
+ <div id="sheet"></div>
+ <script type="module">
+ /*
+ * Renders every @three-ws/viewer-presets material preset on the same
+ * geometry under one shipped environment, using the SAME renderer
+ * configuration src/viewer.js uses (NeutralToneMapping, exposure 0,
+ * environmentIntensity 1.15, sRGB output) so a value tuned here is a
+ * value the platform viewer actually produces. Driven by
+ * scripts/material-preset-sheet.mjs; the environment is chosen with
+ * ?env=<id> against src/environments.js.
+ */
+ import {
+ WebGLRenderer,
+ Scene,
+ PerspectiveCamera,
+ SphereGeometry,
+ TorusKnotGeometry,
+ MeshPhysicalMaterial,
+ Mesh,
+ PMREMGenerator,
+ NeutralToneMapping,
+ SRGBColorSpace,
+ DirectionalLight,
+ AmbientLight,
+ } from 'three';
+ import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+ import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+ import { MATERIAL_PRESETS, MATERIAL_PRESET_NAMES, applyMaterialPreset } from '@three-ws/viewer-presets';
+ import { environments } from '/src/environments.js';
+ import * as THREE from 'three';
+
+ const params = new URLSearchParams(location.search);
+ const envId = params.get('env') ?? 'neutral';
+ const shape = params.get('shape') === 'knot' ? 'knot' : 'sphere';
+ const env = environments.find((e) => e.id === envId);
+ if (!env) throw new Error(`unknown environment "${envId}"`);
+
+ const sheet = document.getElementById('sheet');
+ document.getElementById('title').textContent = `${env.name} — ${MATERIAL_PRESET_NAMES.length} presets`;
+
+ // One shared renderer, drawn once per preset and copied into that
+ // preset's own 2D canvas: 20 live WebGL contexts exceed the browser's
+ // per-page limit and start evicting each other mid-capture.
+ const SIZE = 400;
+ const renderer = new WebGLRenderer({ antialias: true, alpha: false });
+ renderer.setSize(SIZE, SIZE, false);
+ renderer.setPixelRatio(1);
+ renderer.toneMapping = NeutralToneMapping;
+ renderer.toneMappingExposure = Math.pow(2, 0);
+ renderer.outputColorSpace = SRGBColorSpace;
+
+ const pmrem = new PMREMGenerator(renderer);
+ pmrem.compileEquirectangularShader();
+
+ async function loadEnvMap() {
+ if (env.id === '') return null;
+ if (env.id === 'neutral') return pmrem.fromScene(new RoomEnvironment()).texture;
+ const texture = await new EXRLoader().loadAsync(env.path);
+ const map = pmrem.fromEquirectangular(texture).texture;
+ texture.dispose();
+ return map;
+ }
+
+ const envMap = await loadEnvMap();
+
+ const scene = new Scene();
+ scene.environment = envMap;
+ if ('environmentIntensity' in scene) scene.environmentIntensity = 1.15;
+
+ // The viewer's punctual rig, reduced to the key + ambient terms that
+ // matter on a single centered object. Without it the "None"
+ // environment renders pure black and proves nothing.
+ const key = new DirectionalLight(0xffffff, 0.8 * Math.PI);
+ key.position.set(1.4, 1.6, 1.2);
+ scene.add(key);
+ scene.add(new AmbientLight(0xffffff, 0.45));
+
+ const camera = new PerspectiveCamera(35, 1, 0.1, 100);
+ camera.position.set(0, 0, 4.2);
+ camera.lookAt(0, 0, 0);
+
+ const geometry =
+ shape === 'knot' ? new TorusKnotGeometry(0.75, 0.26, 220, 32) : new SphereGeometry(1.1, 96, 64);
+ const mesh = new Mesh(geometry, new MeshPhysicalMaterial({ color: 0xffffff }));
+ scene.add(mesh);
+
+ for (const name of MATERIAL_PRESET_NAMES) {
+ applyMaterialPreset(THREE, mesh, name);
+ renderer.render(scene, camera);
+
+ const figure = document.createElement('figure');
+ const out = document.createElement('canvas');
+ out.width = SIZE;
+ out.height = SIZE;
+ out.getContext('2d').drawImage(renderer.domElement, 0, 0);
+ const caption = document.createElement('figcaption');
+ const p = MATERIAL_PRESETS[name];
+ caption.textContent = `${p.label} — m ${p.metalness ?? 0}, r ${p.roughness ?? 0}`;
+ figure.append(out, caption);
+ sheet.append(figure);
+ }
+
+ document.body.dataset.ready = 'true';
+ </script>
+ </body>
+</html>
diff --git a/scripts/material-preset-sheet.mjs b/scripts/material-preset-sheet.mjs
new file mode 100644
index 000000000..44658ba4a
--- /dev/null
+++ b/scripts/material-preset-sheet.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * Material preset contact sheets — renders every `@three-ws/viewer-presets`
+ * material preset under EVERY environment the platform viewer ships
+ * (src/environments.js: None, Neutral/RoomEnvironment, Venice Sunset,
+ * Footprint Court) and writes one PNG per environment.
+ *
+ * A measured-value preset is only correct if it reads correctly under the
+ * lighting a user will actually see it in. Tuning skin roughness against a
+ * single studio HDRI and shipping it is how a "measured" value ends up looking
+ * like wet plastic at sunset, so this sheet is the gate: look at all of them,
+ * then tune.
+ *
+ * The harness page (scripts/material-preset-sheet.html) runs the SAME renderer
+ * configuration src/viewer.js uses (NeutralToneMapping, exposure 0,
+ * environmentIntensity 1.15, sRGB output) through real three.js in real
+ * Chromium, so nothing here is a stand-in for the viewer.
+ *
+ * Usage:
+ * npm run dev # the harness is served by Vite
+ * node scripts/material-preset-sheet.mjs
+ * node scripts/material-preset-sheet.mjs --out=docs/assets/material-presets
+ * node scripts/material-preset-sheet.mjs --base=http://localhost:3000 --shape=knot
+ *
+ * Exits nonzero if any environment failed to render.
+ */
+
+import { chromium } from 'playwright';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const args = Object.fromEntries(
+ process.argv
+ .slice(2)
+ .filter((a) => a.startsWith('--'))
+ .map((a) => {
+ const [k, ...rest] = a.replace(/^--/, '').split('=');
+ return [k, rest.length ? rest.join('=') : 'true'];
+ }),
+);
+
+const BASE = args.base || 'http://localhost:3000';
+const OUT_DIR = path.resolve(args.out || 'docs/assets/material-presets');
+const SHAPE = args.shape === 'knot' ? 'knot' : 'sphere';
+// A 2K EXR decoded and PMREM-filtered under SwiftShader is slow; the sheet also
+// renders 20 full-quality frames after that.
+const READY_TIMEOUT = Number(args.timeout || 180_000);
+
+// Mirrors src/environments.js. Kept as ids only: the harness page imports the
+// real module, so this list just drives which pages to open and what to call
+// the files.
+const ENV_IDS = [
+ { id: '', file: 'none' },
+ { id: 'neutral', file: 'neutral' },
+ { id: 'venice-sunset', file: 'venice-sunset' },
+ { id: 'footprint-court', file: 'footprint-court' },
+];
+
+async function main() {
+ await mkdir(OUT_DIR, { recursive: true });
+ const browser = await chromium.launch({
+ args: ['--use-gl=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'],
+ });
+ const failures = [];
+
+ for (const env of ENV_IDS) {
+ const page = await browser.newPage({ viewport: { width: 1120, height: 1400 }, deviceScaleFactor: 1 });
+ const consoleErrors = [];
+ page.on('console', (msg) => {
+ if (msg.type() === 'error') consoleErrors.push(msg.text());
+ });
+ page.on('pageerror', (err) => consoleErrors.push(String(err?.message || err)));
+
+ const url = `${BASE}/scripts/material-preset-sheet.html?env=${encodeURIComponent(env.id)}&shape=${SHAPE}`;
+ try {
+ await page.goto(url, { waitUntil: 'load', timeout: READY_TIMEOUT });
+ await page.waitForSelector('body[data-ready="true"]', { timeout: READY_TIMEOUT });
+ const file = path.join(OUT_DIR, `presets-${env.file}.png`);
+ await page.screenshot({ path: file, fullPage: true });
+ const count = await page.locator('#sheet figure').count();
+ console.log(`✓ ${env.file.padEnd(16)} ${count} presets → ${path.relative(process.cwd(), file)}`);
+ if (consoleErrors.length) console.warn(` console: ${consoleErrors.slice(0, 3).join(' | ')}`);
+ } catch (err) {
+ failures.push({ env: env.file, message: err?.message || String(err), consoleErrors });
+ console.error(`✗ ${env.file}: ${err?.message || err}`);
+ } finally {
+ await page.close();
+ }
+ }
+
+ await browser.close();
+ if (failures.length) {
+ console.error(`\n${failures.length} environment(s) failed.`);
+ process.exit(1);
+ }
+ console.log(`\nAll ${ENV_IDS.length} shipped environments rendered into ${path.relative(process.cwd(), OUT_DIR)}.`);
+}
+
+main().catch((err) => {
+ console.error('[material-preset-sheet] fatal:', err);
+ process.exit(1);
+});