img2threejs: Rebuilding Reference Images as Code-Only Three.js Models
Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
At a glance
- What is it?
- img2threejs turns a single reference image into a TypeScript Three.js model built from primitives and procedural shaders, with a quality gate and animation-ready hierarchy. It targets agents like Claude Code and Codex, not manual modeling workflows.
- Who is it for?
- Adopt img2threejs if you need fast, token-efficient, code-only reconstructions of objects or characters for web-based Three.js demos, especially when you want the output to be animation-ready with pivots and sockets. Do not use it if you require photorealistic or physically accurate geometry, since it deliberately avoids mesh extraction and photogrammetry.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Problem Does It Solve?
img2threejs addresses a narrow but real pain point: turning a single reference image of an object into a Three.js model without producing mesh files or downloading art packs. The README is explicit that this is reconstruction-by-code, not photogrammetry or mesh extraction. The target user is someone working with an AI coding agent, such as Claude Code, Codex, or OpenCode, who wants a model that is ready to animate, not just a static lump. The output is a THREE.Group factory written in TypeScript, which means the result is source code you can inspect, modify, and version control. This is a different trade-off from traditional 3D pipelines: you trade raw visual fidelity for editability and token efficiency. The project also claims to be quality-gated, meaning there is a checkpoint to determine whether the reconstruction is good enough to be marked final.
How the Reconstruction Pipeline Works
The core mechanism is procedural generation. The input is one reference image. The output is a TypeScript function that builds a THREE.Group from primitives, procedural shaders, and generated geometry. The README mentions a runtime hierarchy that includes pivots, sockets, and colliders, which are added so the model can be animated. This is not a single-step magic process. The pipeline is agent-agnostic: it relies on whatever the host agent provides, such as native image reading, a browser MCP, a project preview, or a user-supplied screenshot. The documentation calls this 'agent vision' or 'agent browser tool' generically. There is also a quality gate. The demo gallery shows a registry status field that can be 'placeholder' or 'final'. A placeholder status means the model renders but is not finished work. This suggests the pipeline has a self-evaluation step where the agent decides whether the reconstruction meets a quality bar. The exact criteria are not detailed in the material, but the existence of the status field is concrete evidence of a gate.
Getting It Running: Commands and Config
The README does not provide a direct installation command or a setup script. It states that the project runs under Claude Code, Codex, or OpenCode. That is the entire execution model: you invoke the agent and give it a reference image. There is no standalone CLI described in the material. The repository layout includes a scripts directory, and the README references a CHANGELOG.md and CONTRIBUTING.md, but no specific commands are listed. The live demo gallery at img2threejs.io is the primary way to see the output. Each demo entry records a generatedWith version and a registry status. For example, the Dual-Sword Warrior demo is built with v1.5.1 and has a placeholder status, while the Talon Knife demo is built with v1.4.4. If you want to run the pipeline yourself, you would need to clone the repository and inspect the scripts directory, but the README does not document a one-line run command. This is a gap for users who expect a turnkey tool.
The Quality Gate and Its Implications
The quality gate is a distinctive feature, but it also exposes a limitation. The demo gallery marks several entries with a warning symbol and a status of 'placeholder' rather than 'final'. The README says these models render but are not finished work. This means the pipeline can produce output that looks acceptable at first glance but fails a deeper quality check. The gate is not automatic perfection; it is a manual or agent-driven review. For an engineering team, this is a real operational cost: you cannot trust every output as production-ready. You must verify the status and likely inspect the generated code. The gate also implies that the agent needs to have a notion of what 'good' means, which is not specified. This is a trade-off: the gate prevents garbage from being labeled final, but it does not guarantee that final models are actually high quality. The README does not explain how the gate is enforced, so the criteria remain opaque.
Limitations and Wrong Use Cases
The most obvious limitation is the deliberate avoidance of mesh extraction and photogrammetry. That means the output is not a faithful reproduction of the reference image's surface details. Complex textures, organic shapes, and fine surface imperfections will not be captured. The README's examples are mostly hard-surface objects: knives, guns, a bike, earbuds. Characters are present, but the low-poly humanoid and the Pikachu-style mascot are stylized, not realistic. If you need a model for a product configurator where visual accuracy is critical, this tool is the wrong choice. Another limitation is token efficiency. The project claims to be token-efficient, but that is a relative claim. Generating a complex model as code can consume a large number of tokens, and the quality gate may require multiple iterations. The README does not provide concrete token counts. Also, the pipeline depends on the host agent's ability to read images and preview the scene. If your agent lacks a browser tool or image input, you will need to supply screenshots manually, which adds friction.
Alternatives and How They Differ
The main alternative is traditional photogrammetry or mesh extraction pipelines, such as using a tool like Meshroom or a commercial service like Tripo3D or Hyper3D, which are linked in the README. Those approaches generate a textured mesh from multiple images or a single image, and the result is a .glb or .obj file. The difference is fundamental: img2threejs produces code, not a mesh. With a mesh, you get geometric fidelity but a static asset that requires a separate rigging step for animation. With img2threejs, you get a procedural model with pivots and sockets built in, but you lose surface detail. The README also mentions a GLB-reference route in v1.5.1, which suggests you can use a GLB as a reference for the code generation, but it is not the primary output. Another alternative is manual modeling in Blender or Three.js, which gives full control but is slow and not agent-driven. The choice depends on whether you value editability and animation-readiness over visual accuracy.
Maintenance, Upgrades, and License
The project is under active development, with releases v1.4.0, v1.5-beta, and v1.5.1 between July and August 2026. The release notes indicate a weapon pipeline, a character track, and a material pipeline. This rapid iteration means the API and the generated code structure may change between versions. The demo gallery records the version each demo was built with, so you can track compatibility. The CHANGELOG.md is linked, but its contents are not in the material. The license is Apache-2.0, which is permissive for commercial use, but it does not grant any trademark rights. You should check the license file for specifics, but Apache-2.0 generally allows modification and redistribution with attribution. The maintenance cost is moderate: because the output is code, you must keep up with Three.js API changes and the project's own version updates. The README does not document a migration path between versions, so upgrading may require regenerating models.
Who Should Adopt It
img2threejs is best suited for developers who are already working with AI coding agents and need quick, disposable or iterable 3D models for web demos, prototypes, or low-poly games. The fact that the output is code means you can tweak parameters, add custom animation logic, and integrate directly into your Three.js scene without loading external assets. It is also a good fit for projects where file size matters, since a procedural model can be much smaller than a textured mesh. The quality gate, while imperfect, provides a checkpoint that is missing in many generative tools. However, if your project demands photorealistic detail or accurate proportions, you will be disappointed. The tool is not a replacement for a 3D artist. Before adopting, verify that your agent environment supports the required image input and preview capabilities. The showcase gallery is a good place to assess the output quality, but remember that some demos are marked as placeholders.
Editorial conclusion
Adopt img2threejs if you need fast, token-efficient, code-only reconstructions of objects or characters for web-based Three.js demos, especially when you want the output to be animation-ready with pivots and sockets. Do not use it if you require photorealistic or physically accurate geometry, since it deliberately avoids mesh extraction and photogrammetry. Before adopting, verify that the generated code meets your quality bar by checking the registry status: demos marked 'placeholder' are unfinished. Also confirm your agent environment supports the image reading and preview tools the pipeline depends on.
Community notes