3d-image-renderer
Skill87 starsChanged 4 months agoMITView on GitHub
Generate PNG images by building a real Three.js 3D scene and capturing one frame headlessly — no image model involved. Takes a text prompt and an aspect ratio (1:1, 16:9, or 9:16) and produces a rendered PNG. Use this skill whenever the user asks to generate, create, or render an image, picture, scene, wallpaper, thumbnail background, or product shot with this system — especially with phrases like "generate an image of", "render a scene", "create a PNG", "no image model", "3D render of", or a prompt paired with an aspect ratio. Also use it when the user wants an image in a named visual style (dark studio, Apple light, nature, sunset, night, underwater). Not for editing existing images, 2D vector art, or animated video (VidTSX handles video).
In this repository7 other files it gives its agents.
- prompt-to-designSkill
- cf-imageSkill
- scene-splitterSkill
- storybook-pipelineSkill
- story-html-publisherSkill
- story-illustratorSkill
- story-narratorSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Read references/geometry-recipes.md for any element it covers before inventing geometry.
- Very specific: line 42
Create /home/claude/scene-render/scene.mjs.
- Very specific: line 66
All randomness via seededRandom(seed) — never Math.random().
- Distinctive: line 73
No post-processing. Glow = emissive + additive blending + fog.
- Distinctive: line 85
Write a hero spec covering each prompt-named element with its dominant material color, then:
- Distinctive: line 100
If it returns placeholders, rely on the validator output (histogram, ASCII map, presence checks) — it was designed for exactly that.
- Distinctive: line 129
No MSAA headless — SSAA 2× via the pipeline is the anti-aliasing.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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). Default16:9if unspecified. No custom sizes.
Workflow (follow in order)
1. Setup
bash <skill_dir>/scripts/setup.shIdempotent; 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.mdnow. - List the hero elements: every concrete noun in the prompt ("headphones", "tree", "flowers") is a hero element.
- Read
references/geometry-recipes.mdfor 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)— neverMath.random(). InstancedMeshfor anything repeated 50+ times; per-instance color viasetColorAt+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).
4. Render
cd /home/claude/scene-render && xvfb-run -a node scene.mjs5. Validate (mandatory — never skip)
Write a hero spec covering each prompt-named element with its dominant material color, then:
node validate.mjs out.png heroes.json[
{ "name": "flowers", "hex": "f5a8c8", "tolerance": 45, "minPct": 0.3 },
{ "name": "tree canopy", "hex": "5a9440", "tolerance": 60, "minPct": 2.0 }
]Also open the PNG with the view tool if image viewing works in this session. If it returns placeholders, rely on the validator output (histogram, ASCII map, presence checks) — it was designed for exactly that.
Fix and re-render when:
- any hero element FAILs presence (typical fixes: more instances, bigger scale, camera reframe, contrasting material)
- WASHED OUT / TOO DARK / LOW CONTRAST warnings (typical fixes: exposure and ambient per the style preset table; in light styles swap pure-white materials for metallic/mid-gray)
- the ASCII map shows a composition failure (subject cropped, background walling off the sky)
Maximum 2 fix iterations, then deliver best result and tell the user what still needs work.
6. Deliver
cp /home/claude/scene-render/out.png "/mnt/user-data/outputs/<descriptive_name>.png"Present the PNG with present_files. Keep the summary short: style preset
used, hero elements, and any validation fixes applied. Only include
scene.mjs in the delivery if the user asks for the code.
Hard rules (violating any of these produced real failures)
- three@0.152.2 pinned — r163+ drops WebGL1 and headless-gl is WebGL1-only.
- Pixel readback needs vertical flip + alpha forced to 255 (pipeline does it).
- No MSAA headless — SSAA 2× via the pipeline is the anti-aliasing.
- Light styles: exposure ≤ 1.08, ambient ≤ 0.35, and the hero MUST include a metallic or mid-gray material. Pure white on white is invisible.
- Background elements sized by intuition WILL wall off the sky — run the FOV check.
- Prompt-named elements must pass the presence validator before delivery.
- Everything deterministic:
seededRandom, fixedtime = 2.0.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

