img2threejs
Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
What is it?
What it is
A skill that takes a single reference image of an object and produces a fully procedural Three.js model written in TypeScript, built from primitives, shaders, and generated geometry, ready for animation and interaction.
Why it exists
To enable fast, token‑efficient, code‑only 3D reconstruction that avoids heavy mesh files or photogrammetry, provides a reviewable, version‑controlled source, and keeps the model generation logic deterministic while delegating visual judgment to an agent’s vision.
Who should use it
AI engineers building autonomous agentsThree.js developers looking for procedural generation toolsGenerative AI researchers3D web developersDevelopers using Claude Code or similar LLM-based coding agents
Who should avoid it
Users requiring high-fidelity photogrammetryUsers needing complex organic mesh extraction from single imagesUsers looking for traditional 3D modeling software (Blender/Maya) alternativesDevelopers without access to LLM vision capabilities
How it works
A quick walkthrough in plain English
How img2threejs works
Step 1 of 3
You interact with it
Open img2threejs, send a request, or connect it to your stack.
Features
Advantages
- Highly token‑efficient – minimal model context usage
- Deterministic, repeatable scripts reduce errors and debugging
- No external dependencies simplify installation and CI integration
- Animation‑ready output with sockets, pivots, and colliders
- Clear staged pipeline allows incremental review and refinement
- Open source with active roadmap and community contributions
- Supports procedural material and lighting for realistic rendering
- No need for mesh files or downloads – everything is code‑generated
Disadvantages
- Single image input limits visibility of hidden sides and geometry accuracy
- Best suited for hard‑surface objects; character reconstructions are stylized, not photoreal
- Requires agent vision or browser tool for review, adding complexity
- Python scripts must run in a compatible environment (Python 3.10+ only)
- Setup requires cloning the repo into a skills directory and running multiple scripts manually
- Multiple passes may be needed for complex objects, increasing review time
- Limited to Three.js runtime; not directly exportable to other formats without extra tooling
Installation
native
git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs
FAQ
How do I install and run the img2threejs skill?
Clone the repository into your Claude skills directory: ```bash git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs ``` Then, in Claude Code, point to an object image and invoke the skill with: ``` /img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours. ``` The skill will validate the image, generate a spec, and walk you through each build pass with side‑by‑side comparisons.
What is a build pass and how does the pipeline progress?
The model is sculpted in a fixed sequence of passes: 1. blockout 2. structural‑pass 3. form‑refinement 4. material‑pass 5. surface‑pass 6. lighting‑pass 7. interaction‑pass 8. optimization‑pass After each pass the agent reviews a rendered comparison sheet. Only if the review scores meet the thresholds does the next pass unlock. This staged approach keeps the output animation‑ready and prevents wasted token usage.
What gates control whether a pass can continue?
Several gates must be satisfied: - **Suitability** – the image must be a viable 3D target. - **Pre‑spec & strict‑quality** – the spec must be deep enough for the object’s complexity. - **Screenshot feedback** – a render, comparison sheet, and vision score are required. - **Action‑ready** – the model must expose a runtime hierarchy via `root.userData.sculptRuntime`. - **Attachment correctness** – child parts must declare proper parent joins. - **Material & lighting realism** – PBR channels and real lights must be present. If any gate fails, the agent chooses an action such as `refine‑spec` or `refine‑code` before proceeding.
How does img2threejs ensure detail accuracy and quality?
Before code generation the pipeline builds a **detail inventory** by slicing the reference image into zones and cataloguing identity‑defining features (gloss, bevels, screws, engravings, etc.). Each detail must map to a real component or material entry. A strict‑quality gate blocks shallow specs, and the review process scores each feature against per‑feature thresholds defined in the grimoire. Only when all required details meet their thresholds does the pass unlock.
How can I contribute or add new demos to the showcase?
Contributions are welcome! You can add new procedural material recipes, gates, or host coverage. For demos, create a new TypeScript factory in the showcase repository (`hoainho/img2threejs-showcase`) and link it in the gallery. Follow the contributing guidelines in `CONTRIBUTING.md` and the roadmap in `ROADMAP.md` to align with upcoming features.
Featured in Videos
YouTube tutorials and walkthroughs for img2threejs
Alternatives
Similar projects ranked by category, topics, and text overlap.
