3d-image-renderer

3D Image Renderer

Renders a text prompt into a PNG by writing a Three.js scene and capturing one frame with headless-gl under Xvfb. Think of every image as frame 0 of a TSX animation composition: deterministic, seeded, time = 2.0s.

Inputs

• prompt — what to render
• aspect ratio — one of 1:1 (1080×1080), 16:9 (1920×1080), 9:16 (1080×1920). Default 16:9 if unspecified. No custom sizes.

Workflow (follow in order)

1. Setup

bash <skill_dir>/scripts/setup.sh

Idempotent; instant when cached. Installs npm deps into /home/claude/scene-render/ and drops the bundled prebuilt gl binary in place (compiles from source only if the binary fails its smoke test). It also copies pipeline.mjs and validate.mjs into the workdir. If it prints SETUP FAILED, report the error to the user — do not hand-roll a fallback.

2. Plan the scene

• Pick ONE style preset → read references/style-presets.md now.
• List the hero elements: every concrete noun in the prompt ("headphones", "tree", "flowers") is a hero element.
• Read references/geometry-recipes.md for any element it covers before inventing geometry.

3. Write the scene

Create /home/claude/scene-render/scene.mjs. Import ONLY from the local pipeline — never re-implement renderer setup, pixel readback, or PNG writing:

import {
  THREE, createRenderer, captureFrame, addStudioEnvironment,
  seededRandom, visibleHeightAt,
} from './pipeline.mjs';

const time = 2.0; // the captured "frame"
const { renderer, glContext, W, H, OUT_W, OUT_H } =
  createRenderer('16:9', { exposure: 1.15 /* from style preset */ });

const scene = new THREE.Scene();
// ... build: sky, lights, ground, hero elements (per preset + recipes) ...

await captureFrame({
  renderer, glContext, scene, camera, W, H, OUT_W, OUT_H,
  outPath: '/home/claude/scene-render/out.png',
});
console.log('DONE');

Scene-authoring rules:

• All randomness via seededRandom(seed) — never Math.random().
• InstancedMesh for anything repeated 50+ times; per-instance color via setColorAt + instanceColor.needsUpdate = true.
• Bake rotations into geometry (geometry.rotateZ(...)) — do not stack Euler rotations on meshes for construction.
• Validate every horizon/background element with visibleHeightAt (the FOV rule in geometry-recipes.md) BEFORE rendering.
• No post-processing. Glow = emissive + additive blending + fog.
• WebGL1 only: no transmission, no WebGL2-only features, three stays at 0.152.2 (pinned by setup — do not upgrade).