# img2threejs — AI Image-to-3D Model Converter for Three.js

> An open-source tool that uses AI coding agents to convert reference images into procedural, animation-ready Three.js models with quality-gated output and token-efficient generation.

## Install

Save as a script file and run:

# img2threejs — AI Image-to-3D Model Converter for Three.js

## Quick Use
```bash
pip install img2threejs
# Convert an image to a Three.js scene
img2threejs generate --input photo.jpg --output scene.html
# Preview the result in your browser
open scene.html
```

## Introduction
img2threejs is an open-source tool that converts reference images into procedural Three.js 3D models using AI coding agents. Rather than generating mesh data directly, it produces clean TypeScript/JavaScript code that recreates the object procedurally in Three.js. The output is animation-ready, quality-gated, and optimized for token-efficient generation, making it practical for both interactive web experiences and agent-driven 3D content creation.

## What img2threejs Does
- Converts reference images into procedural Three.js scene code
- Generates clean, readable TypeScript that builds 3D objects from primitives
- Applies quality gates to validate geometry, lighting, and proportions
- Produces animation-ready models with configurable motion parameters
- Optimizes prompts for minimal token usage during generation

## Architecture Overview
img2threejs works as a Python CLI that orchestrates an AI coding agent to interpret a reference image and produce Three.js code. The pipeline has three stages: image analysis extracts shape, color, and spatial information; code generation produces procedural Three.js geometry using primitives and materials; quality validation renders the scene headlessly and compares it against the reference for fidelity. Failed quality checks trigger automatic refinement loops.

## Self-Hosting & Configuration
- Install via pip with Python 3.10+
- Configure your LLM provider API key for the code generation backend
- Run the generate command with an input image path
- Customize quality thresholds in the configuration file
- Export scenes as standalone HTML files or importable Three.js modules

## Key Features
- Procedural code output instead of opaque mesh files enables easy customization
- Quality-gated pipeline validates output before finalizing
- Animation-ready models with configurable rotation, bounce, and morph targets
- Token-efficient prompting minimizes API costs per generation
- Standalone HTML export for instant browser preview

## Comparison with Similar Tools
- **Three.js Editor** — manual 3D scene building; img2threejs automates from images
- **Blender** — full 3D suite requiring modeling skills; img2threejs uses AI for generation
- **TripoSR** — generates 3D meshes; img2threejs outputs editable procedural code
- **Shap-E** — OpenAI 3D generation; img2threejs produces Three.js-native output
- **Meshy** — SaaS 3D generation; img2threejs is open source and self-hosted

## FAQ
**Q: What LLM providers does it support?**
A: Any OpenAI-compatible API, including Anthropic via proxy, DeepSeek, and local models.

**Q: Can I edit the generated Three.js code?**
A: Yes, the output is clean procedural code designed to be human-readable and modifiable.

**Q: How accurate are the 3D models?**
A: Accuracy depends on image complexity. Simple objects achieve good fidelity; complex scenes may need manual refinement.

**Q: Does it require a GPU?**
A: No GPU is needed for generation. The headless quality-check renderer uses software rendering.

## Sources
- https://github.com/hoainho/img2threejs
- https://github.com/hoainho/img2threejs/blob/main/README.md

---
Source: https://tokrepo.com/en/workflows/asset-b25dc790
Author: Script Depot