img2threejs Rebuild the object in a reference i @codeKK pythonOpen Source Website

img2threejs

Introduction: Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

More: Author ReportBugs OfficialWebsite

Tags:

Rebuild the object in a reference image as a code-only, procedural Three.js model.

Quality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.

	_DAILY	_WEEKLY
_Python
_{All languages}

Reference images reconstructed in code as animation-ready Three.js models, running live in the browser.

→ Open the Live Demo Gallery

Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.

Live demos

Reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open any model to orbit it, inspect its reference, and read the generated source.

Demo	Subject	Built with	View	Source
Dual-Sword Warrior — TypeScript procedural surfaces ⚠︎	character	`v1.5.1`	Live	code
Low-Poly Humanoid — Rigged Character ⚠︎	character	`v1.5.0`	Live	code
★ Talon Knife \| Doppler Ruby (Factory New)	object	`v1.4.4`	Live	code
AWP \| Medusa (Minimal Wear) · V2 rebuild	object	`V2`	Live	code
Pikachu 10K Star Celebration ⚠︎	character	`v1.5-beta`	Live	code
Glock-18 \| Ghost Protocol (Well-Worn)	object	`v1.4.1`	Live	code
Classic Knife \| Fade (Minimal Wear)	object	`v1.3`	Live	code
BMX Endurance Bike	object	`v1.3`	Live	code
M9 Bayonet \| Doppler Phase 2	object	`v1.3`	Live	code
Sony WF-1000XM3 Earbuds + Case	object	`v1.2`	Live	code
ISSACA 12 Gauge Shotgun	object	`v1.2`	Live	code
Gerber Paracord Knife	object	`v1.2`	Live	code
Doraemon House (isometric diorama)	object	`v1.2`	Live	code
War-Hauler "SECTOR 07"	object	`v1.2`	Live	code
Crowned Loot Chest ⚠︎	object	`v1.2`	Live	code

⚠︎ marks a demo whose registry status is still placeholder rather than final — it renders, but it is not finished work. The Built with column is the version each demo's own registry entry records in generatedWith, not an inference from dates; awp-medusa-v2 records V2, which is that demo's rebuild pass rather than a release number. Rows are ordered newest first by the commit that added the demo.

The gallery source lives in img2threejs/img2threejs-showcase. If this project is useful, a star on this repo helps others find it.

What it does

You give it one reference image of an object. It produces a THREE.Group factory written in TypeScript that recreates that object from primitives, procedural shaders, and generated geometry — with a runtime hierarchy (pivots, sockets, colliders) so the result is ready to animate, not an inert lump.

It runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say "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.

Subjects and detail accuracy

Objects and characters. Each subject is classified object, character, or hybrid. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in grimoire/character/reconstruction.md.
Detail-first analysis. Before code generation the pipeline enumerates a detailInventory of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: grimoire/intake/detail_inventory.md.
Maximum likeness for a specific person or character. An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details: grimoire/character/likeness_maximization.md.
Multi-view silhouette carving. An opt-in geometryDescriptor.visualHull intersects at least two deterministic orthographic binary silhouettes into a bounded, welded voxel mesh. It records unseen areas as low-confidence rather than inventing hidden detail. Schema and runtime check: grimoire/scripts.md.
CS2 weapon review gates. Knife and Glock-18 routes use family-specific component contracts. The review records exactness tier, family identity, painted-region and projection coverage, per-region confidence, approximation notes, and versioned review-scene metadata; component-coverage and map-stripped blockout gates prevent a convincing texture from standing in for real structure. Ships with the CS2 domain plugin; see its docs/cs2/review-gates.md.
Resumable local workflow. forge/state.py records an ordered, evidence-backed intake/pass checklist for the generic profile and every registered domain (in-repo character, plus installed domain plugins such as CS2 and animated-character from plugin-character). forge/next.py --state resumes from that checklist while the existing spec, render, and review gates remain authoritative.
Material reference pipeline. Every visible material region can be cropped, analyzed, resolved against the versioned Three.js material registry, fitted into ObjectSculptSpec, rendered from controlled camera views, and accepted only after a per-region comparison gate. See docs/materials/README.md.
Python-assisted browser rendering. Python may orchestrate camera batches, hashes, manifests, and deterministic diagnostics, but the target browser Three.js route remains the rendering authority. See grimoire/build/python_threejs_render_bridge.md.

How it works

A staged sculpting pipeline turns the reference image into a spec, then generates and vision-reviews one build pass at a time — blockout → structural → form → material → surface → lighting → interaction → optimization — self-correcting until every identity-defining feature clears its threshold.

→ Full pipeline diagram, gates, self-correction logic, and the token-efficiency design: docs/ARCHITECTURE.md A staged sculpting pipeline turns the reference image into a spec, then generates and vision-reviews one build pass at a time — blockout → structural → form → material → surface → lighting → interaction → optimization — self-correcting until every identity-defining feature clears its threshold. Deterministic Python scripts handle validation and gating; model tokens are spent only on visual judgment and code.

→ Full pipeline diagram, gates, self-correction logic, script reference, and the token-efficiency design: docs/ARCHITECTURE.md

Quick start

Which project and CLI do I need?

Project	Role	CLI
img2threejs — this repository	Base reconstruction skill, procedural Three.js pipeline, scripts and quality gates	`npx --yes img2threejs@latest <command>`
img2	Optional plugin harness: catalog, registry, host links and capability lookup	`npx --yes @img2threejs/img2@latest <command>`
Domain and output plugins — linked below	Additional workflows, domain rules or explicitly selected output routes	Install through `img2 add <plugin-id>`

The two CLIs are separate packages with independent versions. Installing the harness does not install this base skill; adding a plugin does not generate a model. Start with the base skill. Add the harness only when you need plugins.

1. Install the base skill

The CLI needs Node.js ≥ 18 and Git; the reconstruction scripts need Python ≥ 3.10. Configure your agent host first. The base installer detects Hermes, Claude Code, Codex and OpenCode; the plugin harness currently integrates with Claude Code, Codex and OpenCode.

Preview, install into all detected hosts, then inspect their base-skill links:

npx --yes img2threejs@latest install --dry-run
npx --yes img2threejs@latest install
npx --yes img2threejs@latest doctor

To install into just one detected host instead, use:

npx --yes img2threejs@latest install --host claude

The --yes above belongs to npx, allowing the CLI package download. It is not an overwrite flag for the base installer.

Supported host directories are ~/.hermes, ~/.claude, ~/.codex, and $XDG_CONFIG_HOME/opencode (default ~/.config/opencode). The CLI fetches the base skill from GitHub at v2.0.0 by default. Its --ref accepts a semantic tag (including prereleases) or a full 40-character commit SHA, not a branch:

npx --yes img2threejs@latest update --ref v2.0.0

Checkouts live under ~/.img2threejs/releases/<sha>/img2threejs; hosts installing the same commit share that checkout. update refuses lower skill versions, including prerelease downgrades. The installer refuses manual installs and unrelated links rather than overwriting them. Keep those installations, or deliberately move their entries yourself before switching to CLI-managed installs. --dry-run is offline and writes nothing; it does not verify remote ref availability or downgrades.

Manual alternative — choose this or the CLI, not both at the same skill path:

git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

For multiple hosts, keep one checkout and point each host's img2threejs skill entry at it with a symlink so copies cannot drift apart. A manual clone follows the repository's default branch rather than the CLI's pinned release.

You can also install the CLI globally with npm install -g img2threejs, then run img2threejs install. To test it from this checkout, run node bin/img2threejs.mjs install --dry-run; see CONTRIBUTING.md for packaging and publication checks.

2. Install the plugin harness, if needed

Use harness CLI 0.4.0 or newer for short plugin IDs:

npx --yes @img2threejs/img2@latest install --yes
npx --yes @img2threejs/img2@latest plugins

The harness uses ~/.img2 and tries to link an img2 launcher onto your PATH. Read the install output for its location. plugins lists the official live catalog; list shows registrations on your machine.

For short commands that use the latest published harness, set this bash/zsh alias:

alias img2='npx --yes @img2threejs/img2@latest'

It lasts for this shell session. Add it to ~/.zshrc and run source ~/.zshrc to keep it in future zsh sessions. Every img2 ... command below also works with the explicit npx --yes @img2threejs/img2@latest ... prefix. An existing harness checkout and its older launcher are not automatically upgraded by running install again.

The first --yes in the harness install command belongs to npx; the final one skips the harness consent prompt. Neither permits replacing an existing plugin.

3. Choose plugins — do not install everything by default

Plugin / source README	Adds	Access	Install after harness setup
cs2	`cs2` profile — CS2 weapon/glove skin reconstruction, family adapters, finish rules and blocking domain review gates	Public	`img2 add cs2 --yes`
character	`animated-character` profile — character workflow plus Stage R rigging/animation gates	Public	`img2 add character --yes`
environment	The environment plugin, distributed from a private repository	Private — authorized Git access required	`img2 add environment --yes`
img2glb	Explicit `image → glb` route through the hosted TRELLIS space; generated mesh output, not the default code-only route	Public	`img2 add img2glb --yes`
hello-cube	Small deterministic image-to-Three.js cube example and plugin contract exerciser	Public	`img2 add hello-cube --yes`

These are announced plugins; use img2 plugins for the current catalog. Open each plugin's linked README for its input requirements, dependencies and tool setup. For CS2 and character workflows:

img2 add cs2 --yes
img2 add character --yes
img2 list
img2 doctor
img2 sync --check

An installed domain plugin contributes its checklist steps, evidence collection, spec augmentation (quality floors merge raise-only), and blocking review gates. With no plugins installed, the base has generic and character profiles. A profile whose plugin is missing (cs2, animated-character) fails loud naming what is installed; it never silently downgrades. The base skill is not a plugin: do not use img2 add to install this repository.

Private environment source: GitHub access and working Git credentials are required. The link may return 404 when you are signed out or lack permission. The public img2-environment npm installer can bootstrap the harness, but does not grant access to the private source:

npx --yes img2-environment install --dry-run
npx --yes img2-environment install --yes

That installer has its own SDK pin and may retain older CLI presentation. For lifecycle and trust details, read the harness usage guide. To write a plugin, follow WRITING_A_PLUGIN.md.

4. Run a reconstruction in your agent

Start a new agent session or restart the current one after installing skills. In Claude Code, attach an image or give its path and invoke:

/img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
Keep its proportions, silhouette and colours. Follow the quality gates.
Report the output files, render-review evidence and any inferred regions.

In another host, ask the agent to use the installed img2threejs skill with that image. For a plugin workflow, name the profile explicitly, for example:

Use img2threejs with the installed cs2 domain and ./reference.png.
Follow the cs2 profile and its family-specific reconstruction and review gates.

Use img2threejs with the installed character plugin and ./reference.png.
Follow the animated-character profile. Do not claim animation readiness until its rig gates pass.

The agent validates the image, writes an assessment and spec, generates the factory pass by pass, and reviews rendered comparisons. Installation alone does none of that. For a multi-session reconstruction, run these from the skill root:

python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json

5. Audit and maintain the installation

npx --yes img2threejs@latest doctor   # base-skill host/link report
img2 doctor                         # static audit of registered plugins
img2 update cs2 --check              # read-only check for a newer plugin version
img2 update cs2                     # install a newer available plugin version
img2 remove cs2                     # unlink owned links and back up the managed checkout

Neither doctor command proves visual likeness or animation quality; those require the reconstruction's render and domain gates. img2 update --check exits 1 when an update is pending, not only on errors. Local --link checkouts are live and are not fetched by update.

Finding / refusal	Meaning and next action
`WARN ... multi-capability provider`	The plugin declares multiple capabilities; each edge resolves independently. This warning alone does not fail `img2 doctor`. Do not delete capabilities or reinstall just to remove it.
`FAIL ... opencode link missing`	The reported OpenCode skill link is missing. Inspect the reported path and registered checkout; it is not proof that the reconstruction code is broken. `sync` regenerates harness data, not host links.
Plugin already registered	Use `img2 list` and `img2 update <id>`, not another ordinary `add`. Use `add --force` only when deliberately replacing a registration; it backs up and reinstalls rather than merely repairing a link.
Unmanaged base skill	Keep the manual checkout, or deliberately move its host entry before using the base installer. The base CLI does not overwrite it.
Private source returns 404 / access denied	Sign in with a GitHub account authorized for that repository and configure Git credentials. A public npm installer cannot bypass source permissions.

For plugin audit exit codes, replacement behavior and additional troubleshooting, see the img2 README.

Driving it harder

The one-liner leaves the judgement calls to the skill. When you already know what "correct" means for your subject, say so — each line below maps onto a real gate or artifact in the pipeline, so it changes what gets enforced rather than just adding adjectives:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.

Fidelity   Hold proportions and silhouette to the reference. Enumerate the identity-defining
           details first — bevels and rounding, panel seams, fasteners, engraved or painted
           linework, gloss vs matte zones, wear — and drop any detail you cannot place on a
           real component instead of faking it.
Materials  Derive the finish class and gradient stops from the reference pixels, not from
           memory. Flag any colour that will not survive tone-mapping.
Runtime    Expose pivots and sockets for whatever should move, plus a userData.tick for a
           looping idle animation.
Gates      Run --strict-quality, and do not advance a pass until the side-by-side review
           passes. Report per-region confidence for anything the image cannot show.

Useful additions depending on the subject:

A specific person or character — Maximize likeness: fit the parametric template to the landmarks, de-light and camera-match the reference, then project it. Tell me which regions are inferred.
An animal or creature — This is a creature, not a humanoid — use the quadruped body plan and the body-unit proportion system.
A saturated anodized or candy finish — The coat is candy-coat, not gem-metal. Keep the hue; do not let the environment steal it.
A cost ceiling — Stay at low effort and skip the presentation composer; I only need the evaluation render.

The scripts run from the skill root and need only Python 3.10+ — nothing to install.

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

The factory generator repeats the strict-quality gate and is fail-closed: on failure it returns BLOCKED with the spec artifact, failure metrics, causes, and next action, and does not write a factory. --allow-nonstrict is only for explicit legacy test fixtures, never production output.

Copy-paste prompts for the GLB-reference route

Rebuilding a character from a GLB reference rather than a photo is a different route with its own gates — the GLB is a measurement instrument and never ships. Three prompts cover it, each in its own copy block:

Prompt	Use it when	Do not use it when
Build	you have a GLB and no built surfaces yet	there is no GLB, or the build already completed and merely looks wrong
Polish	the build completed and the result does not look like the GLB	the surfaces were never built — that is a build re-run, not a polish
Animation	the figure looks right standing still and has passed the build gates	the surface is ungated, or `joint_loops.py` fails — that is a surface finding no weight tuning reaches

They force every parameter the GLB genuinely carries — size, proportions, per-band widths and centroids, base colour, roughness and metalness — to the measured value, with the check that proves it landed. Three things are not 1:1 and each prompt says so: rigging and animation are usually absent from the asset (skinCount: 0, animationCount: 0), texture images and normal maps are deliberately not copied per this skill's code-only contract, and nothing finer than the node's cell size can be carried at all.

These are reference material, not a guarantee. They are written to be general, so the measured figures in them came from one character and are there to show what to measure — not values to copy. Run the one that matches your situation rather than all three in sequence; each notes the cost of being used out of turn.

For the script-by-script reference, the full scripts table, and expected artifacts, see docs/ARCHITECTURE.md.

Why it is token-efficient

Most image-to-3D agent loops burn tokens by asking the model to do mechanical work — re-reading the whole model every pass, scoring pixels, validating JSON by hand, re-running steps it already did. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required.

Scripts enforce, the model judges. The Python scripts handle validation, gating, spec authoring, PBR extraction, comparison-sheet packaging, and pipeline state. They never score visuals. The model's tokens go to one thing: looking at a single side-by-side sheet and deciding pass or fail.
Zero dependencies, zero install churn. Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read/write is done with struct and zlib. Nothing to install means nothing to debug in-context.
Pass-gated generation. The code generator emits only the currently unlocked build pass. The model does not regenerate or re-read the entire model on every iteration — each step is small and scoped.
Fail fast, before codegen. A strict-quality gate blocks shallow specs before a single line of Three.js is generated, so you never spend tokens rendering a model that was underspecified from the start.
One image per review. Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.
Text output, not binaries. The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.

The net effect: you still get a faithful 3D model from an image, but the expensive model context is reserved for visual judgment and code, not bookkeeping. For the full per-stage and per-cycle token breakdown, see docs/TOKEN_COST.md.

Scripts

Script	Role
`stage1_intake/probe_image.py`	Image metadata and obvious technical issues (not a visual check).
`stage2_spec/new_pre_spec_assessment.py`	Classify the object, score complexity, emit a quality contract.
`stage2_spec/new_sculpt_spec.py`	Author the ObjectSculptSpec from the assessment.
`stage2_spec/validate_sculpt_spec.py`	Validate the spec; `--strict-quality` blocks shallow specs before codegen.
`stage1_intake/extract_pbr_evidence.py`	Reference-derived PBR evidence per crop (inference, not inverse rendering).
`stage1_intake/material_region_analysis.py`	Crop material regions, run texture/PBR evidence, and resolve registry profiles.
`stage2_spec/apply_material_analysis.py`	Wire region assignments, priors, maps, and provenance into ObjectSculptSpec.
`stage3_build/orchestrate_passes.py`	Locked pass state: status, check, sync.
`stage3_build/generate_threejs_factory.py`	Emit the Three.js `Group` factory for the current unlocked pass.
`stage4_review/material_views.py`	Emit multi-angle, zoomed, microscope, environment, and capture-readback contracts.
`stage4_review/material_comparator.py`	Compare the visible material crop and classify per-channel mismatches.
`stage4_review/material_feedback.py`	Apply bounded, material-scoped corrections through the existing stop policy.
`stage4_review/material_gate.py`	Block material-pass until registry, crop, render, compatibility, and comparison evidence passes.
`stage4_review/make_comparison_sheet.py`	Package one reference-vs-render sheet for review.
`stage4_review/append_review.py`	Record a per-pass review: scores, decision, evidence.
`_shared/feature_acceptance_policy.py`	Internal helper enforcing per-feature score thresholds.
`stage1_intake/build_detail_inventory.py`	Slice the reference into zones and scaffold a detail inventory.
`stage1_intake/extract_landmarks.py`	Overlay a landmark grid and scaffold an anatomy block for characters.
`stage1_intake/solve_camera_pose.py`	Emit a reference-camera block so the render can be camera-matched.
`stage1_intake/delight_albedo.py`	Approximate a neutral albedo from the photo before texture projection.
`stage3_build/bake_projected_texture.py`	Emit a projection/UV-bake descriptor for photo-texture projection.

| stage5_rig/rig_spec.py | Derive and validate a skeleton from the component tree, so bones cannot drift from the geometry. | | stage5_rig/geodesic_skinning.py | Vertex weights from distance measured through the solid; keeps rigid roles out of smooth skinning. | | stage5_rig/validate_rig_payload.py | Blocking payload-integrity gate before a THREE.Skeleton is bound. | | stage1_intake/extract_hair_evidence.py | Hair/skin split, banded coverage, hairline, highlight band, root-to-tip delta. | | stage4_review/scalp_exposure.py | HARD gate: finds bald patches on geometry, before any render. | | stage4_review/hair_gate.py | Soft gate: hair coverage, hairline and highlight offsets against the reference. | | stage4_review/interior_difference.py | Appearance difference inside the silhouette, banded by height. Required per visual pass. | | _shared/chirality.py | Left/right as an importable convention, with the two gates the two chirality defects need. | | _shared/pipeline_routing.py | Fail-closed weapon/character routing; low confidence resolves to request-input. |

This is a curated selection — forge/ holds around ninety modules. The executable reference with every flag is grimoire/scripts.md, and the gate-by-gate contract is grimoire/review/gates_reference.md. The rest of grimoire/ holds the rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).

Optional reference-fidelity tooling

The stdlib-only core can use an isolated evidence layer without taking on runtime dependencies: SAM2 component masks, Depth Anything V2 relative-depth priors, MediaPipe face/pose landmarks, Chrome DevTools diagnostics, Three.js scene inspection, Playwright cross-browser fallback, and version-aware Context7 retrieval. These tools never approve a pass or silently provide geometry. Install, routing, provenance rules and exact commands: docs/integrations/reference_fidelity_tooling.md.

Optional GLB-baseline character pipeline

integrations/glb_character_pipeline reconstructs a character from a multipart GLB used as a measurement instrument plus its diffuse image, and emits the procedural TypeScript the demo actually ships — no .glb or .bin is fetched at runtime. It carries its own pyproject.toml/uv.lock so the stdlib-only forge core stays dependency-free, and operates on a companion showcase checkout via IMG2THREEJS_SHOWCASE_ROOT.

It applies only when a build has a GLB to measure — skip it entirely otherwise, and use the core image-driven pipeline instead. Reproduces girl-character's shipped crossSections.ts exactly (748 rings, 86,240 ring points). Method and per-stage rationale: PIPELINE.md.

What you get

An ObjectSculptSpec JSON: the full component tree, materials, repetition systems, sockets, and a recorded review history for every pass.
A TypeScript createObjectNameModel(spec, options) factory returning a THREE.Group, with root.userData.sculptRuntime exposing nodes, sockets, colliders, and destruction groups.
For character builds, root.userData.rig: bones, one shared Skeleton, bone order and index map, and a bound flag computed from whether every skinned mesh actually bound.
A render plus comparison sheets documenting the fidelity at each pass. For the script-by-script reference and the full list of output artifacts, see docs/ARCHITECTURE.md.

Roadmap

Shipped:

v1.0 — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy.
v1.1 — detail-first analysis: required detail inventory, strict-quality gate.
v1.2 — humanoid character generator: anatomy track, proportion-lock and feature-placement passes.
v1.3 — quality & efficiency: the Divine Eye deterministic review harness, input-integrity and geometry-truth gates, reference-grounded texture and gradient analysis, CIEDE2000 colour math.
v1.4 — The Weapon Update — CS2 image-matched reconstruction: provenance-aware intake, projection-first finishes, family-specific weapon adapters, and structural review gates.
v1.4.1 — CS2 hardening: explicit component coverage, a dedicated Glock-18 assembly contract, map-stripped blockout evidence, and stricter geometry-integrity checks.
creature generator — 4 body plans (quadruped / avian / winged-dragon / serpentine), animalAnatomy spec, spine-loft geometry, ΔE00 colour gates.
v1.5 — The Character Update — a skeleton derived from the component tree and bound to SkinnedMesh geometry, geodesic skinning, hair as a five-stage subsystem with a hard scalp-exposure gate, chirality gates, interior-difference review, the tapered-sweep primitive, the material pipeline with a blocking acceptance gate, and resumable workflow state. Not included: the hairProfile compiler, IK, pose-sweep gating, clothing.
v2.0 — The Plugin Update — the domain registry, pull-based spec augmentation with raise-only quality floors, the emission-target socket with provenance, per-plugin blocking gates, and the img2 harness (img2 install/add/doctor). CS2 extracted into plugin-cs2, animated-character served by plugin-character; the base names no domain. The "plugin ecosystem and API" originally slotted for the Procedural World bundle, shipped first as its own major.

Next — one theme per release:

v2.1 — The Character Split: the in-repo character domain joins plugin-character, so the base names no domain and the v2.0 plugin split closes.
v2.2 — The Environment Update: buildings, rooms, streets, vegetation, terrain-aware and multi-object reconstruction.
v2.3 — The Game Pipeline Update: Unity and Unreal exporters, a Blender bridge, LOD and collision-mesh generation.
v2.4 — The Animation Update: auto rigging, auto skin weights, Mixamo compatibility, facial rig.
v2.5 — The AI Studio Update: web UI, batch processing, visual prompt builder, cloud rendering.
v3.0 — The Procedural World Update: multi-view reconstruction, procedural city generation, semantic world understanding.

The arc: assets (v1.4–v1.5) → the plugin ecosystem (v2.0–v2.1) → worlds (v2.2–v2.3) → production (v2.4–v2.5) → an AI game-asset platform that generates playable worlds from reference images (v3.0).

→ Full roadmap — per-version detail, the four-phase long view, and the tracked capability gaps: ROADMAP.md. Technical specification: docs/UPGRADE_PLAN.md.

Honesty about limits

A single image cannot reveal hidden sides or guarantee exact geometry. The skill states plainly when output is approximate, stylized, or low-poly, and infers unseen faces by mirroring visible ones rather than faking confidence. It is strong for hard-surface objects; characters are stylized reconstructions, not photoreal likeness. "This cannot reach the requested fidelity from this image" is a valid, expected result.

Star history

If img2threejs is useful to you, a star helps others find it.

Support the project

img2threejs is free and open source. If it saved you time or found its way into your project, consider supporting continued development:

VietQR / MoMo / PayPal also work — see the donate page.

Contributing

Contributions are welcome — procedural material recipes, new gates, host coverage, and demos especially. See CONTRIBUTING.md and the roadmap for where the project is headed.