Three.js Wizard

# 🧊 Three.js Wizard > **Describe an object in plain words — get a three.js scene that really renders, a set of labelled camera views, and an STL / GLB / HTML you can ship.** Three.js Wizard is the 3D sibling of [SVG Wizard](../svg-wizard) and [HTML Wizard](../html-wizard). Instead of authoring vectors or DOM components, the model writes **`scene.js`** — a tiny ES module that builds geometry into a three.js scene. The app mounts it in a **sandboxed WebGL iframe**, measures it (meshes, triangles, bounding box), renders it from **several camera angles** (`render.png` + the contact sheet `render.views.png`), records `console.log.md`, and exports **`model.stl`**, **`model.glb`** and a stand-alone **`scene.html`** viewer with orbit controls. The renders are fed back to a vision model for an iterative *build → look → critique → fix* loop. --- ## 📦 The module contract ```js import * as THREE from "three"; // only "three" and "three/addons/*" may be imported export const meta = { name: "Coffee mug", units: "mm" }; export function buildScene({ THREE, scene }) { const body = new THREE.Mesh( new THREE.CylinderGeometry(40, 38, 95, 64), new THREE.MeshStandardMaterial({ color: 0xf2f2f2, roughness: 0.4 }), ); body.name = "body"; body.position.y = 47.5; // rests on the ground plane y = 0 scene.add(body); scene.add(new THREE.HemisphereLight(0xffffff, 0x445566, 1.1)); const sun = new THREE.DirectionalLight(0xffffff, 1.6); sun.position.set(120, 200, 160); scene.add(sun); return { update(dt, elapsed) { /* optional, preview only */ } }; } ``` Rules enforced by the built-in **linter**: a `buildScene` export, imports only from `three` / `three/addons/`, no external URLs (no textures, fonts or model files), no renderer / camera / DOM / animation-loop code (the harness owns all of that), lights present, meshes named. Conventions the model is asked to follow: **millimetres, Y-up, resting on `y = 0`, centred on the origin in X/Z, closed solids** so the STL is printable. --- ## 🚀 Getting Started ### Step 1 · Set up your inputs 📝 1. **Notes** — what the object is, its dimensions, parts, proportions, and what it is for (print? web viewer?). 2. **Design Directives** *(optional)* — palette, materials, level of detail, units, tolerances. 3. **Models** — Smart model (authoring), Fast model (edits), Image model (visual review). ### Step 2 · Run the pipeline ⚙️ | # | Step | What it does | |---|------|--------------| | 1 | **▶ Render Scene** | Generates `scene.js` from `notes.md` + `style.md`. | | 2 | **📸 Capture Views** | Mounts the scene, renders the selected views → `render.png` + `render.views.png`, exports `model.stl` and `scene.html`, writes `render.log.md` and `console.log.md`. | | 3 | **✏️ Update Scene** | Applies `update-notes.md` to `scene.js`. | | 4 | **🔍 Review Render** | Vision model inspects the views + logs and rewrites `update-notes.md`. | Then loop **4 → 3 → 2** until it looks right. Tick **Auto-capture** and every code change re-renders instantly. ### Step 3 · Inspect & export 📤 * **Live 3D preview** with orbit controls re-mounts as you type (debounced). * **🔎 Lint** validates the module contract at any time. * **⬇ HTML** — stand-alone viewer (`scene.html`), **⬇ STL** — binary STL for printing, **⬇ GLB** — for web/AR. --- ## 🎛 Capture Options | Option | Meaning | |--------|---------| | **Size** | Pixel size of each square view (512 / 768 / 1024). | | **Views** | *Isometric only*, *Standard* (iso + front + right + top) or *Full* (iso + six orthographic sides). | | **Background** | Transparent, white, dark or studio grey — also used by the exported `scene.html`. | | **Helpers** | Draw a grid on the ground plane and XYZ axes in the renders (not exported to STL/GLB). | | **Live preview** | Re-mount the iframe while you type. | | **Auto-capture** | Re-capture whenever `scene.js` changes. | Axis-aligned views (front, right, top, …) use **orthographic** cameras so proportions can be read like a blueprint; the isometric hero shot is perspective. Every camera is framed automatically from the scene's bounding box. --- ## 💡 Pro Tips * **three.js comes from a CDN** (`cdn.jsdelivr.net`, pinned version — see `threeRender.js`). The preview and `scene.html` need network access; STL/GLB files are fully offline. * **Procedural everything.** No `TextureLoader`, `GLTFLoader` or `FontLoader` — external assets taint the canvas and cannot be captured. Use `MeshStandardMaterial` colours, vertex colours or geometry detail instead. * **Printability:** prefer closed primitives (`BoxGeometry`, `CylinderGeometry`, `LatheGeometry`, `ExtrudeGeometry`) over `PlaneGeometry` and open shells; the STL exporter bakes each mesh's `position` / `rotation` / `scale`. * **Scale sanity:** `render.log.md` prints the bounding box in the units declared in `meta.units` — the reviewer compares that with the brief. * **Errors are gold:** anything thrown in `buildScene` lands in `console.log.md` and the review step will fix it. * `Ctrl/Cmd+S` saves every editor at once; autosave also runs as you type. * If your session's file API rejects binary uploads, the app writes `*.base64.txt` sidecars and warns you — use the download buttons to keep copies. --- ## 📂 Session files | File | Role | |------|------| | `notes.md` | Your brief (input) | | `style.md` | Design directives (input) | | `update-notes.md` | Revision instructions (written by review, read by update) | | `scene.js` | The generated three.js scene module | | `scene.html` | Stand-alone viewer with orbit controls (generated on capture / download) | | `model.stl` | Binary STL of every mesh (generated on capture) | | `model.glb` | glTF binary (generated on demand) | | `render.png` | Hero (isometric) render | | `render.views.png` | Labelled contact sheet of every captured view | | `render.log.md` | Capture report: lint, scene stats, bounds, views, exports, warnings | | `console.log.md` | Runtime console/error output from the live mount | Happy modelling with **Three.js Wizard**! 🧊✨