img2obj: Turning a Reference Image into a Procedural Three.js Object

The Problem img2obj Targets: Code Instead of Downloaded Meshes

Most image-to-3D tools try to recover a mesh. img2obj does the opposite. It reads an attached object image, screenshot, or local image path, and produces an ObjectSculptSpec plus a code-only procedural Three.js factory. Nothing is downloaded: the geometry is written as Three.js code, which means the output is inspectable, editable, and diffable in version control like any other source file. The README states the goal as recreating the visible silhouette, structure, materials, and motion-ready hierarchy. That phrasing matters. The target is the visible object, not the whole object. The stated audience is people building stylized props, mechanical objects, plants, scene assets, and interactive models. The README is equally direct about who should look elsewhere: photogrammetry, exact mesh extraction, and guaranteed production-ready geometry from one image are all listed as out of scope. If your pipeline needs a scanned asset with measured dimensions, this is the wrong tool and the project says so before you install anything.

How the Reconstruction Workflow Actually Runs

The mechanism is a four-stage loop, and each stage gates the next. First, validate the reference: the workflow checks image quality, object visibility, and complexity, and can ask for a cleaner source image instead of proceeding. Second, plan the object by describing the component hierarchy, geometry, materials, pivots, sockets, and visual priorities inside an ObjectSculptSpec. Third, build in phases through blockout, form, lookdev, and interaction, with later detail deliberately kept out of earlier passes. Fourth, review and refine by comparing browser renders against the active source image, fixing the highest-impact differences, and requiring approval before advancing. The quality model splits evaluation into two layers: overall identity (silhouette, proportions, camera, materials, lighting) and critical features, described as the small set of parts that makes an object recognizable, such as a roof profile, a branch fork, a wheel cluster, a face, or a hand-to-object contact. The README states that a high overall score cannot hide a failed critical feature. That is a real design decision, not marketing: it prevents a model from passing review on background and lighting while the one part a viewer would notice is wrong. The README also notes that active phases require visual evidence and explicit user approval before the workflow advances, and that the tool rejects unsupported geometry or unverified corrections rather than silently substituting guessed output.

Installing img2obj and Running a First Spec

The README gives no package registry install. There is no Homepage field on the repository and no published release listed, so the only documented path is cloning the current source and checking that the CLI answers. You need Codex with local plugin support, Python 3.10 or newer, a browser project using Three.js for the generated factory, and AI image and vision access when source cleanup, planning views, or visual review are needed.

git clone https://github.com/vinhhien112/img2obj.git
cd img2obj
python3 scripts/sculpt.py --help

If the help text prints, the entry point is wired up. The README recommends scripts/sculpt.py as the unified entry point for new work and notes that older individual scripts remain available for compatibility. The first real step is initializing a spec from a reference image. The README's own example names a tree and passes separation and complexity flags:

python3 scripts/sculpt.py init "Ancient Autumn Oak" \
  --image ./reference/oak-tree.png \
  --reference-separation clear \
  --complexity complex \
  --out object-sculpt-spec.json

That writes object-sculpt-spec.json. From there the documented sequence is context, then a strict validation for the current pass, then generation:

python3 scripts/sculpt.py context object-sculpt-spec.json

python3 scripts/sculpt.py validate object-sculpt-spec.json \
  --for-pass blockout \
  --strict-quality

python3 scripts/sculpt.py generate object-sculpt-spec.json \
  --out src/AncientOak.generated.ts \
  --wrapper-out src/AncientOak.ts

The generate step emits TypeScript rather than a mesh file, which is the whole point of the project. Expect the strict validator to be the first place a weak reference image fails. The README says to run python3 scripts/sculpt.py --help to explore comparison, review, correction, capability, probe, and PBR commands; those are documented by the CLI itself rather than in the README body.

Where img2obj Breaks Down

The Limitations section is unusually candid, and it is the best guide to failure modes. One image cannot reveal hidden sides or exact dimensions, so anything the camera did not capture is inference. The result is a procedural approximation, not a scanned or extracted mesh. Transparent glass, smoke, liquid, fur, fine cloth, and exact likeness may need more references or a lower-fidelity target, which means the capability packs for glass, hair/fur, and fabric are not a promise of photorealism. The generated factory is a construction starting point, not a replacement for a complete production asset pipeline. And the sharpest constraint: AI vision review is required for visual acceptance, because local scripts organize evidence but do not judge similarity by themselves. That last point has a practical consequence. If you run the CLI without vision access, you can still generate and validate, but the review-and-refine loop that the quality model depends on cannot close itself. The README also flags one demo, Cliffside Lantern House, as a preview created with an unreleased version of img2obj, so it is not evidence of what the current source produces. Treat the two released demos as the reference points.

img2obj Against Photogrammetry and Mesh-Extraction Tools

The obvious alternative is a photogrammetry pipeline, or any tool that recovers a mesh from images. The difference is not quality, it is what you receive. Photogrammetry takes many overlapping photographs and produces a dense mesh with texture; the output is a fixed artifact you then clean up in a 3D editor. img2obj takes one attached image and produces TypeScript that constructs the object at runtime. The trade-off runs in both directions. A mesh carries surface detail that procedural code will not reproduce, which is why the README excludes exact mesh extraction. Code gives you parameters, named parts, pivots, and sockets you can animate and re-tune without re-running a reconstruction, which a baked mesh does not. If your requirement is a faithful scan of an existing physical object, photogrammetry wins and img2obj is not a candidate. If your requirement is a stylized prop that a developer can adjust in a pull request, the mesh route gives you a binary blob and the code route gives you a diff. The project also positions itself against downloading meshes or art packs, which is the third common approach for scene assets: buy or download a model, drop it in. img2obj generates instead, so licensing of third-party assets never enters the picture.

Maintenance, Upgrade Cost and the MIT Licence

The repository is not archived, and the last push was on 2026-08-06. There are no retrieved releases, so there is no versioned upgrade path to plan around; the README's install instruction is to clone the current source, which means pulling main is the upgrade mechanism. That has a cost. The README mentions that older individual scripts remain available for compatibility, which implies the unified sculpt.py entry point replaced an earlier set of scripts and that the project cares about not breaking existing invocations. It does not document a versioning policy, a changelog, or a rollback procedure for a generated factory, though it does say the workflow keeps review history and phase checkpoints for refinement, promotion, or rollback. That rollback is per-sculpt-phase, not per-release. The licence is MIT, which permits commercial use and modification with the copyright notice retained; the repository ships a LICENSE file at the top level. This is not legal advice, and MIT says nothing about the rights attached to the reference images you feed in, which is a separate question your own sources determine. The Python regression suite lives in tests/, and the README instructs running it after changes, so a fork that modifies scripts/ has a test target to run rather than a blank check.

Editorial conclusion

Adopt img2obj if you already work in Codex with Python 3.10 or newer and need stylized props, mechanical parts, or vegetation rebuilt as inspectable Three.js code rather than downloaded assets. Skip it if you need photogrammetry, exact dimensions, or a finished production mesh from a single photograph; the README lists hidden sides and exact dimensions as things one image cannot reveal. Before committing, run python3 scripts/sculpt.py init on one of your own reference images, then python3 scripts/sculpt.py validate with --for-pass blockout --strict-quality, and check whether the strict validator accepts the reference you actually have rather than the demo images.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. vinhhien112/img2obj on GitHub