# img2obj gates a procedural Three.js rebuild behind four phases and an approval step, and ships no version number

> img2obj is a Codex plugin that turns a reference image into a code-only Three.js object through a spec, a phase gate and a visual review loop. The repository declares no release, no dependency list and no version, and two of its three demos live on a domain other than the project's.

**vinhhien112/img2obj** — Codex plugin that turns attached object images into code-only, animation-ready procedural Three.js models.

- Repository: https://github.com/vinhhien112/img2obj
- Stars: 1,671 · Forks: 168
- Language: Python
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/vinhhien112-img2obj

## No release, no version field and no dependency list

The repository has no GitHub releases, and nothing in the tree pins a version for the plugin itself. The top level holds .codex-plugin/, .gitignore, LICENSE, README.md and four directories: assets, scripts, skills and tests. There is no package manifest, no lockfile and no requirements file, so a checkout gives you Python scripts and a plugin manifest with nothing recording what those scripts import.

What the requirements section does state is the real dependency list, and it is mostly outside the repository: Codex with local plugin support, Python 3.10 or newer, a browser project already using Three.js for the generated factory, and AI image and vision access when source cleanup, planning views or visual review are needed. Three of those four are environmental. A person installing this has to assemble the surrounding toolchain themselves.

The last push on the default branch is dated 2026-08-06 and the repository is not archived, so the work is present but untagged. In practice that means there is no artifact to install and no version to pin: the install step is a clone followed by reading the script help, and the upgrade path is a pull.

The license is MIT and the readme links to it, which is the one unambiguous piece of packaging metadata here.

## Four phases, and each one needs approval before the next starts

The workflow is a gate rather than a single pass. Blockout, form, lookdev and interaction run in that order, and the stated rule is to keep later detail out of earlier passes, so the silhouette is settled before materials are touched.

What separates this from a prompt is the transition rule. Active phases require visual evidence and explicit user approval before the workflow advances, and review compares browser renders against the active source image, fixes the highest-impact differences, and requires approval again. A run therefore stops and waits rather than continuing until something plausible appears.

The evidence is concrete rather than a self-assessment. Reference-derived PBR data is extracted as palette, roughness, height, normal and ambient-occlusion maps, and reference and render screenshots are packaged into comparison sheets and evidence manifests for review. What img2obj produces as a result is a review history and phase checkpoints supporting refinement, promotion or rollback.

One instruction shows how narrowly the motion is scoped. A user asking for a hatch to open on its hinge is told to add no physics and no destruction, and the phases themselves reserve pivots, sockets, parent-child relationships and detachable parts as anchors so motion can be authored later without rebuilding geometry.

## A high overall score cannot cover a failed critical feature

The scoring model has two layers and one asymmetry. Overall identity covers silhouette, proportions, camera, materials and lighting, which is the broad resemblance of the whole object. Critical features are the small set of parts that makes the object recognizable, with a roof profile, a branch fork, a wheel cluster, a face or a hand-to-object contact given as examples.

The rule is that a high overall score cannot hide a failed critical feature. This is the part that makes the gate meaningful. A reconstruction that is broadly the right colour, the right proportions and the right lighting can still be useless if the roof pitch or the branch fork is wrong, and averaging those two layers together into a single number would let the good parts pay for the bad one. Keeping them separate means the recognizable part either passes or the phase does not close.

The output spec is where that distinction is written down. The ObjectSculptSpec describes geometry, materials, hierarchy, motion and review targets, so the review targets are part of the contract the generator reads rather than a judgement applied afterwards to a finished file.

The readme is also explicit about who makes the final call. AI vision review is required for visual acceptance, and the local scripts organize evidence but do not judge similarity by themselves, so the approval step is a human or model looking at the comparison sheet, not a threshold the code crosses on its own.

## One CLI entry point over compatibility scripts that stay behind

Everything is driven through a single script, and the new work path is explicit. Initialising a session takes a name, an image, a reference-separation mode and a complexity level, and writes a spec file:

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

The other three verbs in the documented path are context, which reads the spec, validate with a --for-pass flag naming the phase and a --strict-quality switch, and generate, which writes a generated TypeScript factory plus a wrapper file. That last detail is worth noting: the output is two files, one generated and one hand-editable wrapper, so the generated file is meant to be disposable.

The same script also carries the comparison, review, correction, capability, probe and PBR commands, which the readme defers to the help text rather than documenting. Older individual scripts remain available for compatibility, so the scripts directory holds two generations of interface at once, and the tree listing does not separate them.

The suite is run with the standard library runner rather than a project tool: python3 -m unittest discover -s tests. The readme asks for it after any change to workflow contracts or scripts, and separately asks that the local plugin be reloaded after changing a skill, script or manifest so a new Codex task picks up the change.

## Refusing work is written into the capability list

Several of the project's own capabilities are about what it will not do. One is that it generates procedural Three.js geometry instead of downloading meshes or art packs. Another is that it rejects unsupported geometry or unverified corrections instead of silently substituting guessed output.

That second one matters more than its position in a list suggests. The failure mode it rules out is the expensive one: a correction that has not been checked appearing in the spec and being built anyway. Pausing costs a round trip, and a silently wrong mesh costs considerably more to discover later in a browser.

The scope is bounded in the same spirit. The At a Glance table states the tool is not for photogrammetry, exact mesh extraction, or guaranteed production-ready geometry from one image, and the limitations repeat the point: one image cannot reveal hidden sides or exact dimensions, the result is a procedural approximation rather than a scanned mesh, and transparent glass, smoke, liquid, fur, fine cloth and exact likeness may need more references or a lower-fidelity target. The generated factory is described as a construction starting point, not a replacement for a production asset pipeline.

So the workflow is built for the cases a single photograph handles well, stylized props, mechanical objects, plants and scene assets, and it says so before you invest in a run.

## Two demos on a different domain, and one of them is marked unreleased

The three demonstrations are hosted off the project's own domain and the readme links two of them. The Tower Ship study is at 3dship.harrysoftware.com and the Ancient Autumn Tree study at tree.harrysoftware.com, both under a harrysoftware.com domain rather than the repository's namespace. The two studies are also described as demonstrating different things: the ship covers procedural geometry, articulated parts, material work and interactive browser controls, while the tree covers procedural curves, deterministic branching, layered bark, dense foliage and an animation-ready hierarchy.

The third study is where the honesty sits. The Cliffside Lantern House is labelled an unreleased preview and carries a note saying it was created with an unreleased version of img2obj and will be updated in future versions. A reader looking at that demo is therefore looking at output the plugin does not currently produce, and the note says so rather than letting the image imply otherwise.

Support is pointed at a Ko-fi page under a different name again, one that does not match either the repository owner or the demo domain. That inconsistency is not a problem for a user, but it does mean none of the surrounding links resolve to the same identity.

What the demos do establish is the intended output shape. Both are interactive browser pages, which is consistent with the requirement for an existing Three.js browser project and with the review loop that compares a browser render against the source image.

## The repository is mostly a skill, and the script is only its tool

The layout is four entries, and the split between them explains how the plugin works. .codex-plugin/ holds the manifest that makes the directory loadable as a local Codex plugin. skills/object-to-threejs-procedural/ holds the Codex workflow and the reference contracts, which is where the instructions, the phase definitions and the ObjectSculptSpec shape live. scripts/ holds validators, generators, visual-review tools and compatibility commands. tests/ holds the Python regression suite.

So the substance is the skill, and the Python is the tooling the skill calls. The workflow is expressed as instructions the model follows, and the scripts exist to hold state, generate code and organize evidence. That has a practical consequence for anyone modifying it: a change to the skill has no test to fail, because the suite covers scripts, and the readme's own instruction is to reload the plugin so a new task receives the latest version.

The assets directory is listed without a description of its contents in the readme, so what sample references or textures ship with the plugin is not written down.

The tree also has no CI configuration among the top-level entries, no contributing guide and no changelog, so the suite described as a regression suite appears to be something a person runs locally rather than something a pull request is checked against.

## Conclusion

img2obj suits someone who already works inside Codex and wants a procedural Three.js prop rather than a downloaded mesh, and who will supply the browser project, the Python 3.10 or newer runtime and the vision access the workflow assumes. Two checks belong before the first run. Verify that the plugin manifest and the skill directory match the checkout you cloned, since there is no tag to compare against and no release to roll back to, and confirm your host can reach the harness the review steps expect. Anyone needing photogrammetry, an exact mesh extraction or a finished production asset is outside its stated scope and will not find what it needs here. Anyone who wants a published, versioned artifact should treat an unreleased repository as a moving target and pin your own copy.

## FAQ

### What does img2obj turn an image into?

An ObjectSculptSpec describing geometry, materials, hierarchy, motion and review targets, plus a code-only procedural Three.js factory written as TypeScript. It does not convert pixels into a finished mesh, and it is not photogrammetry or exact mesh extraction.

### What does img2obj need before it will run?

Codex with local plugin support, Python 3.10 or newer, a browser project already using Three.js for the generated object factory, and AI image and vision access when source cleanup, planning views or visual review are needed. No package manifest or requirements file is included in the repository.

### How does img2obj decide a phase is finished?

Two scoring layers, where overall identity covers silhouette, proportions, camera, materials and lighting, and critical features cover the small set of recognizable parts. A high overall score cannot hide a failed critical feature, and active phases also require visual evidence and explicit user approval before the workflow advances.

### Does img2obj have a published release I can install?

No GitHub releases exist for it, and nothing in the repository pins a plugin version. The documented path is to clone the source, run python3 scripts/sculpt.py --help, and load the directory as a local Codex plugin. The default branch was last pushed on 2026-08-06.

## Sources

- [Issues](https://github.com/vinhhien112/img2obj/issues)
- [License: MIT](https://github.com/vinhhien112/img2obj/blob/main/LICENSE)
- [README](https://github.com/vinhhien112/img2obj/blob/main/README.md)
- [vinhhien112/img2obj on GitHub](https://github.com/vinhhien112/img2obj)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vinhhien112-img2obj