In this piece
img2threejs: Turn an image into editable Three.js code
A product photo shows your desk lamp. A configurator also needs a shade that changes colour and a head that rotates around the correct hinge. The model needs distinct parts that your application can control.
img2threejs is an agent skill that rebuilds a reference image as a procedural Three.js model written in TypeScript. It gives your coding agent a staged reconstruction workflow. The output is source you can inspect and change, with an object hierarchy that can support interactions. The official img2threejs repository explains that contract.
Sources checked: . This guide draws on project documentation and generator source at release v2.0.1. The lamp example and acceptance checks are proposed exercises; we have not run an image reconstruction or measured its speed, fidelity or cost.
img2threejs.org identifies itself as a separate hosted service. Its Native Mesh pipeline and download packages are not features of the GitHub skill covered here.
What does img2threejs generate?
img2threejs produces a structured reconstruction specification and TypeScript that builds a Three.js object. Your agent provides visual judgment; scripts validate the specification and control stage progression. An application must display and operate the finished model.
The pipeline architecture describes the sequence from blockout through structure, form, materials, surface detail, lighting, interaction and optimisation. In practical terms:
- The agent studies the reference and records visible features and uncertainty.
- It describes components, materials and their relationships in a specification.
- Code builds the current stage, which is rendered in a browser.
- The agent compares that render with the reference and corrects deficiencies before advancing.
The inspected TypeScript factory generator derives the function name from the target name. That function takes one options object and returns a THREE.Group; the specification is compiled into its source. The file imports Three.js and addon helpers, so the model still has runtime dependencies.
Why is editable TypeScript useful for a 3D web app?
Editable TypeScript exposes how the object is assembled, so a developer can change the parts a configuration or animation needs. Demonstrate this with a real change request before adopting the workflow. Readable source does not automatically give you convenient controls.
The generator exposes component maps through root.userData.sculptRuntime. The runtime hierarchy guide explains pivots for movement, sockets for attachments and collider descriptions. A collider description does not add a physics simulation to your app.
| Change you need | Implementation to request | Check before accepting it |
|---|---|---|
| Change the shade colour | Expose the relevant material through an application control | Other lamp instances keep their own colours |
| Rotate the lamp head | Use a named pivot with an agreed axis and motion limits | The shade rotates around its hinge without detaching |
| Change the arm length | Edit the specification and regenerate, or deliberately add a geometry parameter | Attachments and proportions still match the intended variant |
| Select a purchasable configuration | Connect scene controls to validated application state | The displayed combination matches the saved product variant |
Arbitrary dimensions are not built-in factory options. Decide whether the specification or hand-maintained TypeScript owns future edits; regenerating from an old specification can discard a fix.
After inspecting the generated export, add it to your existing scene. This filename and factory name are illustrative:
import { createDeskLampModel } from "./generated/desk-lamp";
const lamp = createDeskLampModel({ castShadow: true });
scene.add(lamp);This adds the constructed object to the scene. Camera placement, rendering, controls and resource cleanup remain application work.
How do you install img2threejs for your coding agent?
Install the skill for one supported coding agent, then restart the agent. The installation guide lists macOS and Linux, Git, Node.js 18 or newer, and Python 3.10 or newer. Runtime versions must also meet your agent’s requirements. The reviewed installer does not support Windows.
npx --yes img2threejs@latest install --host codex
npx --yes img2threejs@latest doctorReplace codex with claude, opencode or hermes for that host. Hermes needs the guide’s additional profile-link step. doctor reports installation state, not model quality. If an existing unmanaged skill blocks installation, inspect that path before changing it.
The commands follow the documented installation route and were not executed for this article. Record the resolved skill release and commit: @latest can change. The npm package manifest identifies an installer CLI. Adding this package to your web application does not give it an image-conversion API.
What should you ask the agent to build?
Ask img2threejs for an object with named, editable parts and explicit review requirements. The input suitability rubric favours readable silhouettes and identifiable objects; it excludes exact mesh extraction and manufacturing-grade dimensions.
Use this original trial brief with a reference image you are authorised to provide. Replace the illustrative 400 mm height with a measured dimension. Supply side and rear references when those surfaces matter.
Use the installed img2threejs skill for ./reference.png.
Build the desk lamp as a procedural Three.js model in TypeScript.
Target: an interactive browser product prototype.
Set one scene unit to one metre and neutral-pose height to 0.4 units.
Keep the base, arm and shade separately identifiable.
Give the shade a named pivot at the physical hinge.
List inferred surfaces and dimensions before building them.
Ask for another view when a required feature cannot be established.
Keep the reconstruction specification with the generated source.
Identify the exported factory and its actual options.
Render a matched reference view plus side and rear views.
Show an untextured view so material detail cannot hide geometry errors.
Demonstrate one shade-colour change and one hinge movement.
Report remaining defects, dependencies and any external assets or calls.
Stop for review if the agreed interaction needs a different asset workflow.Check the silhouette and hinge before refining surface detail. A texture pass cannot fix a misplaced hinge. Keep the accepted specification and source in the same commit so another developer can reproduce the edit.
Where does procedural image-to-3D fit?
We would start with a browser prototype whose separate parts must respond to user input. A desk lamp gives you a concrete editing task. Check whether the reconstruction supports that task before commissioning a catalogue of similar objects.
| Intended use | Why evaluate it | Condition that changes the decision |
|---|---|---|
| Interactive product prototype | Named components can support selection and movement | Missing geometry prevents the required interaction |
| Stylised explanatory scene | Source edits can express the features needed to teach a concept | Approximation would communicate the wrong mechanism |
| Early configurator | You can test how product choices affect the scene | The scene cannot represent valid variants consistently |
| Dimension-critical or deforming asset | A prototype may help clarify the requirement | Acceptance needs CAD accuracy, verified topology or specialist rigging |
The project’s character-likeness workflow can project reference imagery onto procedural geometry. TypeScript output alone does not establish a texture-free workflow. Inspect the generated model’s dependencies.
The plugin architecture separates the base workflow from specialist extensions. Characters still need rigging and deformation checks before their hierarchy can support the intended motion.
If your decision concerns a wider game-asset pipeline, our AI 3D generator comparison for game development covers tool selection, topology and engine handover.
Can you export the result to GLB or Blender?
Three.js can export a scene to GLB; inspect the result in Blender or your intended destination before accepting it. The official exporter reference lists supported scene data and extensions. The file does not preserve the TypeScript program that constructed the scene.
After import, test materials, animation and scale. Custom shaders and application logic need separate handling. Keep the source alongside the exported asset. GLB remains editable in suitable tools; procedural source gives you another way to maintain it.
The optional img2glb plugin documents hosted TRELLIS image-to-mesh generation, with its own network and dependency requirements. That route generates a mesh from the image; it does not export your procedural factory’s result.
How do you check a generated model before shipping?
Test img2threejs output in the destination application against the change a user must perform. A matching reference view can hide an incorrect rear surface or pivot. The project’s self-correction guide also warns that passing a two-dimensional comparison is insufficient to establish three-dimensional realism.
These are proposed checks, not reported test results. Agree device and performance budgets before the run, then record observations and unresolved defects.
| Check | Exercise | Evidence to retain |
|---|---|---|
| Shape and scale | Compare the reference view, side and rear; verify the agreed overall height | Labelled captures, dimension result and a list of inferred regions |
| Editable geometry | Change one arm dimension through the chosen source of truth | Reviewable diff and a model whose attachments still align |
| Independent materials | Show two lamp instances and recolour only one shade | The second instance remains unchanged |
| Part motion | Move the head through its intended range | Correct hinge axis and documented intersections or limits |
| Product state | Select, save and reload a configuration | The same valid variant appears in the controls and scene |
| Device performance | Load and interact on the slowest supported device | Measured startup, frame time, draw calls and memory against agreed budgets |
| Lifecycle | Repeatedly enter, leave and reopen the viewer | No accumulating application-owned GPU resources or duplicate controls |
| Fallback | Use keyboard controls and disable the 3D path | Product information and configuration remain usable |
The Three.js resource-cleanup guide explains that unused geometries, materials and textures need explicit disposal. Removing an object from a scene is not enough. Track ownership so you do not dispose of a resource another model still uses.
Include these checks in your QA for AI-generated code. Geometry approval can miss a broken configuration save, while a passing TypeScript build can miss an incorrect shape.
What does an img2threejs workflow cost?
Budget for agent usage, rejected attempts and the work needed to integrate an accepted asset. The project’s token-cost document calls its figures engineering estimates, so we would not use them as a production quote.
Record the pilot’s output, agent usage, human minutes and remaining defects, then compare that result with your existing modelling workflow. Judge fidelity against the intended use: a prototype and a customer-facing catalogue have different acceptance bars.
Local files do not establish where your agent processes images. Confirm the host, model endpoint and optional plugin calls before supplying confidential product references.
When would we use img2threejs?
Try img2threejs when editable parts are central to your browser prototype and the team can review the reconstruction. Start with one object and a meaningful interaction. Keep the workflow if its source makes the next approved change easier to implement and verify.
Our guide to moving an AI-built prototype into production helps define the handover. The Hyperstate AI case study provides adjacent AI application experience; it does not document img2threejs or 3D modelling work.
For an actual viewer or configurator, our interactive 3D development service is the relevant starting point. Discuss one product, its required interactions and target devices so the pilot has a clear acceptance decision.