img2threejs

What it is

img2threejs is a Python-based tool that rebuilds an object from a reference image into a code-only, procedural Three.js model. It outputs a THREE.Group factory in TypeScript that uses primitives, procedural shaders, and generated geometry, with a runtime hierarchy for animation.

How it works

The project describes a staged pipeline: input image goes through blockout, structural, form, material, surface, lighting, interaction, and optimization passes. Deterministic Python scripts perform validation and gating, and model tokens are spent only on visual judgment and code. A full pipeline diagram and gate details are referenced in docs/ARCHITECTURE.md.

Getting started

Quick start steps are provided under Quick start:

1. Install - place this folder in your skills directory:

git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

2. Invoke - in Claude Code, attach or point to an object image and run:

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

3. Follow the pipeline - the skill validates the image, writes an assessment and spec, generates the factory passes, and shows side-by-side comparisons until the render matches.

Additional script usage examples are provided in the README, including lines like:

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

Recent releases

Latest releases include:

• v1.5.0 v1.5.0 (2026-07-28): Chore: relicensing MIT to Apache-2.0; docs: fix Star History chart with sealed token.
• v1.4.0 v1.4: Weapon pipeline (2026-07-26): Focus on reconstruction quality and production-ready procedural assets. Added internal structure reconstruction for supported object categories and automatic decomposition.
• v1.3 v1.3: Upgrade quality and efficiency (2026-07-23): Added reference-grounded gradient extraction via band-median analysis.
• v1.0 img2threejs v1.0 — Forge (2026-07-21): Added character/hybrid domain detection, humanoid template, proportion-lock & feature-placement passes, per-part materials; engine improvements.

Traction

Stars: 7539; Stars in last 24h: 649; Open issues: 30. Forks: 576. Language: Python. License: Apache-2.0.

Behind the repo

Hosted under img2threejs/img2threejs with related live gallery in img2threejs/img2threejs-showcase. The project emphasizes code-generated, animation-ready outputs rather than mesh downloads.

Caveats

License is Apache-2.0. Created 2026-07-15; last_push 2026-07-28. The README notes that a single image cannot guarantee exact geometry and that outputs may be approximate or stylized for hard-surface objects; characters are described as stylized reconstructions.