Generate Animated Web3D Models from a Single Image – img2threejs Outputs TypeScript Code Instead of GLB

Problem Statement

Traditional 3D generation tools (Meshy, Tripo3D) take an image, run cloud inference, and output binary GLB/FBX files. These files are opaque, hard to edit, large (several MB), and unsuitable for Git diff.

Paradigm Shift

img2threejs treats the 3D asset as engine code. The pipeline is: image → structured specification → Python script pipeline → AI visual scoring → TypeScript factory code. The core output is TypeScript source + JSON spec instead of a binary mesh.

Feature Comparison

Core output : TypeScript source + JSON spec (plain text) vs. binary GLB/FBX/OBJ.

Version control : Git diff on code vs. no diff on binary files.

Editability : Direct code edits for colour, chamfer, part position vs. mandatory Blender/Maya round‑trip.

Animation capability : Native pivots, sockets, colliders vs. manual bone binding.

Runtime size : Lightweight code without massive textures vs. MB‑scale mesh files.

Runtime environment : Local Python 3.10, zero dependencies, Claude/Codex/OpenCode skill vs. cloud‑only API that requires paid calls.

Quality control : Eight sequential validation steps, failing stages lock the pipeline vs. one‑shot generation that relies on luck.

License : Apache 2.0 open source vs. closed‑source SaaS.

Applicable scenarios : Web product demos, game prototypes, CS2 weapon skins, marketing pages, lightweight digital twins vs. high‑fidelity rendering, 3D printing, film assets.

Eight‑Step Quality Pipeline

Browser renders the current stage’s 3D preview.

Automatic side‑by‑side comparison of original vs. rendered image.

AI visual score ≥ 0.7 on details (bevels, screws, wear) before unlocking the next stage.

Four‑Stage Architecture

stage1_intake : Image quality check, object classification, detail scanning, pose matching; rejects blurry or <1024 px images.

stage2_spec : Assesses complexity (simple → ultra‑complex), generates ObjectSculptSpec; strict mode aborts on missing parts.

stage3_build : Generates Three.js factory TypeScript using primitive geometry and procedural shaders, no external textures.

stage4_review : Records scores, screenshots, and corrections; non‑passing stages trigger automatic re‑run.

Token Efficiency

Full object consumes 80 k‑180 k tokens; character consumes 150 k‑350 k tokens. Deterministic Python work handles image parsing, grid scanning, JSON generation, and code scaffolding, while the LLM only performs visual judgment, dramatically reducing token usage.

Zero‑Dependency Deployment

Python ≥ 3.10 with only the standard library is required; no third‑party packages need to be installed.

Installation

# Clone repository for Claude Code
git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs
# Alternative path for Codex
# git clone https://github.com/hoainho/img2threejs.git ~/.codex/skills/img2threejs

Basic Generation Command

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

Strict Quality Command (Production Models)

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity Hold proportions and silhouette to the reference. Enumerate the identity-defining details first — bevels and rounding, panel seams, fasteners, engraved or painted linework, gloss vs matte zones, wear — and drop any detail you cannot place on a real component instead of faking it.
Materials Derive the finish class and gradient stops from the reference pixels, not from memory. Flag any colour that will not survive tone‑mapping.
Runtime Expose pivots and sockets for whatever should move, plus a userData.tick for a looping idle animation.
Gates Run --strict-quality, and do not advance a pass until the side‑by‑side review passes. Report per‑region confidence for anything the image cannot show.

Manual Script Pipeline (No AI)

# 1. Image inspection
python3 forge/stage1_intake/probe_image.py your_image.png
# 2. Complexity assessment
python3 forge/stage2_spec/new_pre_spec_assessment.py "ModelName" --image your_image.png --out assessment.json
# 3. Full spec generation
python3 forge/stage2_spec/new_sculpt_spec.py "ModelName" --image your_image.png --assessment assessment.json --out spec.json
# 4. Strict validation (fails fast)
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
# 5. Generate final TypeScript factory
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createModel.ts

Example TypeScript Output

export function createEarbudsModel(spec, options) {
  const group = new THREE.Group();
  const caseGeo = new THREE.BoxGeometry(2, 1.2, 0.8);
  const caseMat = new THREE.MeshStandardMaterial({color: 0x1a1a1a, roughness: 0.4, metalness: 0.8});
  const caseMesh = new THREE.Mesh(caseGeo, caseMat);
  group.add(caseMesh);
  group.userData.sculptRuntime = {
    nodes: { caseLid: caseLidPivot },
    sockets: { handle: handleSocket },
    colliders: [collider]
  };
  return group;
}

Supported Runtime Features

Pivots for opening/closing animations.

Sockets for attaching accessories.

Colliders for physics or ray‑casting.

Destruction groups for break‑apart effects.

Use Cases

E‑commerce product 3D display – fast, lightweight, replaces costly modelers.

Game rapid prototyping – props, weapons, vehicles with collision and animation ready.

CS2 player‑generated content – web showcase of skin screenshots.

Marketing / landing pages – interactive 3D beats static images.

Frontend digital twins – small devices or buildings turned into interactive Web3D scenes.

Limitations

Single‑image input cannot fully reconstruct hidden or occluded geometry; complex curves may be inaccurate.

Only stylized characters; photorealistic human reconstruction is not supported.

Soft organic materials (cloth, flesh) perform poorly; hard surfaces are recommended.

High token usage for ultra‑complex assets; batch generation should be throttled.

Generated models inherit the source image’s copyright.

Repository

https://github.com/hoainho/img2threejs

Demo Gallery

https://hoainho.github.io/img2threejs-showcase/