img2threejs turns one reference image into an animation-ready Three.js model written in TypeScript

The problem img2threejs solves, and who ends up using it

Most image-to-3D pipelines give you a mesh: a photogrammetry pass, a mesh extraction model, or a downloaded art pack. That output is heavy, hard to edit, and awkward to rig. img2threejs takes the opposite route. It reads one reference image of an object and writes a TypeScript factory that rebuilds the object from primitives, procedural shaders, and generated geometry. The README calls this "reconstruction-by-code" and states plainly that it is not photogrammetry, mesh extraction, or downloaded art packs.

The audience follows from that choice. If you are building a browser scene and want a model you can open, read, and adjust line by line, a generated factory fits. If you want a photoreal asset, it does not. The README also notes that the result carries a runtime hierarchy of pivots, sockets and colliders, which is what separates it from an inert lump of geometry. That hierarchy is the part you would otherwise build by hand after importing a mesh.

The project is agent-agnostic in a specific sense. It runs under Claude Code, Codex, or OpenCode, and wherever the documentation says "agent vision" or "agent browser tool", it uses whatever the host provides: native image reading, a browser MCP, the project preview, or a user-supplied screenshot. So the tool is not a standalone binary you point at a JPEG. It is a workflow that assumes an agent host is already in place.

How reconstruction-by-code actually works

The output is a THREE.Group factory in TypeScript. That is the contract the README states, and it shapes everything else. A factory means the model is constructed at runtime from code, not loaded from a file. Primitives, procedural shaders, and generated geometry are the three building blocks named in the README.

The gallery makes the data flow concrete. Each demo row lists a subject, the version recorded in that demo's registry entry under generatedWith, a live link, and a source link. The source links point at files in the img2threejs-showcase repository, for example src/demos/talon-doppler-ruby/createTalonDopplerRubyModel.ts. A generated model, then, is a TypeScript module that exports the creation function for one subject, and the gallery renders it in the browser with no mesh files and no downloads.

Two details in the README deserve attention because they are easy to misread. First, the Built with column is the version each demo's own registry entry records in generatedWith, not an inference from dates. Second, the row for awp-medusa-v2 records V2, which the README describes as that demo's rebuild pass rather than a release number. Rows are ordered newest first by the commit that added the demo. If you use the gallery as a quality reference, read it with those rules in mind rather than assuming every row maps to a tagged release.

The README also marks some demos with a warning symbol: their registry status is still placeholder rather than final. The README says such a demo renders but is not finished work. That is an unusually honest signal, and it tells you the gallery is a workbench, not a catalogue of finished assets.

Installing img2threejs and generating a first model

The README describes the project as running under Claude Code, Codex, or OpenCode, and the repository root carries the files that support that: SKILL.md, CLAUDE.md, skills/, scripts/, and an integrations/ directory. The README does not give a pip or npm install line, so the practical route is to clone the repository and let your agent host read the skill definition rather than to install a package.

Start by cloning the repository so the skill files and scripts are on disk:

git clone https://github.com/img2threejs/img2threejs.git
cd img2threejs

Then open your agent host in that directory. The repository ships SKILL.md at the root, which is the file an agent host reads to learn the workflow, and CLAUDE.md alongside it for Claude Code specifically.

claude

With the agent running in the repository, give it a reference image and ask for the reconstruction. The README does not print the exact prompt string, so treat the wording as yours to write; what the README does commit to is the output shape. You should end up with a TypeScript module exporting a THREE.Group factory.

To see what a finished one looks like before you generate your own, open the gallery at https://img2threejs.io/ and follow the code link on any demo row. The Talon Knife row, for instance, points at src/demos/talon-doppler-ruby/createTalonDopplerRubyModel.ts in the showcase repository. Reading that file tells you more about the expected structure than any prose description will.

Where img2threejs is the wrong tool

The README is explicit that this is not photogrammetry and not mesh extraction. That single sentence rules out a large class of use cases. If your reference image is a real object that must be reproduced with its actual surface detail, a scan-based pipeline will beat generated primitives, because the code route approximates form rather than sampling it.

The gallery's placeholder markers are the second limitation, and they come from the project itself. Several demos carry a warning symbol because their registry status is still placeholder. The README says they render but are not finished work. A tool whose own gallery contains unfinished entries is telling you the output quality is uneven across subjects, and the README does not claim otherwise.

There is also a dependency the README states rather than hides: the project runs under Claude Code, Codex, or OpenCode. If none of those is part of your workflow, img2threejs is not a drop-in library. The agent-agnostic design means it adapts to whatever vision or browser capability the host provides, but it still needs a host. A team that wants a deterministic CLI that takes an image path and writes a file will not find that contract described in the README.

Finally, the character track is recent. The v1.5-beta release notes describe a character track, a material pipeline, and a release path that actually runs, and v1.5.1 added the GLB-reference route on 2026-08-23. Character work is the newest part of the project, not the most settled.

How img2threejs differs from mesh-generating image-to-3D services

The obvious alternative is a hosted image-to-3D service that returns a mesh or a GLB. The README links to two such services, tripo3d.ai and hyper3d.ai, in its badge row, which is a fair signal of the category it sits next to. The difference is not quality, it is what lands in your repository.

A mesh service gives you a binary asset. You load it, you get geometry, and any animation rig is your problem afterward. img2threejs gives you a TypeScript file. You can read it, diff it in a pull request, change a parameter and see the shape move, and the README states the output includes pivots, sockets and colliders so it is ready to animate. For a codebase where every asset is reviewed, that is a real distinction. For a pipeline that just needs a file on a CDN, it is extra work with no payoff.

The token-efficiency claim in the README belongs to the same argument. Generating code is described as deliberately token-efficient compared to the alternatives the project rejects. Whether that holds for your subjects depends on how complex the object is, and the README does not publish per-subject token figures.

A second alternative is writing the Three.js model by hand. That remains the baseline for anything simple, and it is the honest comparison for a project like this: if you can build the object from a dozen primitives in an afternoon, the agent round-trip is overhead. img2threejs earns its place on objects with enough parts and enough hierarchy that hand-authoring the factory would take days.

Maintenance, releases, and the Apache-2.0 licence

The last push to the repository was on 2026-08-23, the same day v1.5.1 shipped. The release cadence visible in the release notes is tight: v1.4.0 on 2026-07-26, v1.5-beta on 2026-08-06, and v1.5.1 on 2026-08-23. The repository is not archived. Upgrade cost is the thing to watch, because the output is generated code that lives in your project. When the generator changes, existing generated files do not update themselves; you regenerate, and you review the diff. The gallery's generatedWith field exists precisely because demos carry the version that produced them, and the README warns against inferring that version from dates. Expect the same discipline in your own repository.

The licence is Apache-2.0, stated in the README badge row and the repository LICENSE file. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices. What that means for generated output is a question for your own legal review, not something the README settles; the README does not state whether generated model code carries the same licence or belongs to you. Verify that before shipping generated files in a commercial product.

The repository also carries a ROADMAP.md, a CHANGELOG.md, a CONTRIBUTING.md, and a LAB-FINDINGS.md at the root. LAB-FINDINGS.md is worth reading before you commit to the workflow, since it is where the project records what it learned while building the demos.

Editorial conclusion

Adopt img2threejs if you need a procedural, animatable Three.js object and you already work inside Claude Code, Codex or OpenCode, because the output is a THREE.Group factory with pivots, sockets and colliders rather than a mesh. Do not adopt it if you need a faithful replica of a scanned object or a finished asset today: the README marks several gallery demos as placeholder, and the GLB-reference route only arrived in v1.5.1 on 2026-08-23. Before relying on it, open the source file linked next to a demo whose subject resembles yours and check whether the generated hierarchy is something you would ship.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes