img2threejs — Code-Only 3D Reconstruction
Rebuild objects from a reference image as code-only, procedural, quality-gated, animation-ready Three.js models, token-efficiently.
- Source repo
- img2threejs/img2threejs
- Stars
- ★ 18k
- Last updated
- 11d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 45/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Game developers needing to quickly prototype or reconstruct weapons, props, or hard-surface objects as animation-ready Three.js models directly in Claude Code
- Not a fit if
- Teams needing exact hidden geometry or photoreal character likeness
- Users who want a GUI instead of a CLI workflow
- Environments that cannot run Python 3.10+ scripts
- Source review
- 45/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
img2threejs is an agent skill that reconstructs a Three.js model from a single reference image using procedural generation, not photogrammetry or mesh extraction. It follows a staged sculpting pipeline (blockout → structural → form → material → surface → lighting → interaction → optimization) where each pass is gated by deterministic Python scripts (e.g., validate_sculpt_spec.py, material_gate.py) enforcing strict quality. The output is a TypeScript factory function returning a THREE.Group with runtime hierarchy (pivots, sockets, colliders) for animation readiness. It is agent-agnostic, running under Claude Code, Codex, or OpenCode, and leverages the host's visual capabilities for review. The design emphasizes token efficiency: mechanical tasks are delegated to Python stdlib scripts, reserving model tokens for visual judgment and code generation. Optional reference-fidelity tooling (SAM2, Depth Anything V2, MediaPipe) can be integrated without adding runtime dependencies.
The skill takes an image of an object as input and runs Python scripts (probe_image.py, new_pre_spec_assessment.py, new_sculpt_spec.py) to analyze image metadata, classify the subject, enumerate a detail inventory, and produce an ObjectSculptSpec JSON. Then generate_threejs_factory.py emits TypeScript factory code (createObjectNameModel) for the currently unlocked build pass, applying a strict-quality gate to block generation if the spec is too shallow. After each pass, make_comparison_sheet.py packages a reference-vs-render comparison sheet for the agent to visually judge pass/fail, and append_review.py records the outcome. It supports resumable workflows (forge/state.py, forge/next.py), CS2 weapon-specific review gates (cs2_review.py), and optional camera-matching, de-lighting, and texture projection (solve_camera_pose.py, delight_albedo.py, bake_projected_texture.py). The final artifacts are diffable TypeScript and JSON spec, not binary mesh files.
- Game developers needing to quickly prototype or reconstruct weapons, props, or hard-surface objects as animation-ready Three.js models directly in Claude Code
- 3D artists who prefer code-centric pipelines for version control and fine-grained control over geometry and materials
- Developers using Codex or OpenCode who want a consistent image-to-3D skill across different coding agents
- Creators reconstructing CS2 weapons (like Glock-18, M9 Bayonet) with strict structural review gates for fidelity
- Hobbyists and indie developers looking to experiment with image-to-3D conversion without large token costs
How do you install or deploy this agent?
- Clone the repository into your skills directory: git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs. 2. If using multiple hosts, keep a single checkout and create symlinks from each host's skills directory to that checkout (e.g., ~/.codex/skills/img2threejs). 3. Requires Python 3.10+ (stdlib only, no third-party dependencies).
How do you use this agent?
In Claude Code, attach or point to an object image and run: /img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours. The skill classifies the subject, runs the detail inventory, and guides you through each pass with side-by-side comparisons until the render matches. For more control, add directives such as 'Fidelity', 'Materials', 'Runtime', or 'Gates'. For multi-session reconstruction, first initialize state with python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json, then resume with python3 forge/next.py --state .img2threejs/state.json. Scripts can be run directly, e.g., python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality.
What are this agent's strengths and limitations?
- Token-efficient: delegates mechanical tasks to Python stdlib scripts, reserving model tokens for visual judgment and code generation
- Output is diffable TypeScript and JSON spec, enabling version control and code review rather than binary mesh files
- Strict quality gates (e.g., strict-quality, material gate) ensure spec depth, with fail-closed behavior
- Agent-agnostic: supports multiple hosts (Claude Code, Codex, OpenCode) with easy symlinking
- Resumable workflow via forge/state.py, suitable for long multi-session reconstructions
- Specialized pipelines for characters and CS2 weapons with honest limitation disclosure
- Single reference image cannot reveal hidden geometry or guarantee exact likeness; expects approximate results
- Character reconstructions are stylized, not photorealistic likenesses
- Requires Python 3.10+ environment and running scripts, though with zero third-party dependencies
- Primarily CLI-based, no GUI; visualization depends on host's browser tooling
- Specialized gates for specific domains (e.g., CS2) may add complexity and learning curve
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| img2threejs — Code-Only 3D Reconstruction This agent | 45 · Major gaps | Agent plugin / skillFree + model costs | ★ 18k | 11d ago | Python | Codex · Claude Code |
| Archimedes Patent Workspace | Insufficient evidence | — | ★ 104 | 6d ago | TypeScript | Codex · Claude Code |
| Plannotator | 78 · Good | CLIFreemium | ★ 9.5k | today | TypeScript | Codex · Claude Code |
| NeuroSquad Terminal Dashboard | 76 · Good | CLIFree + model costs | ★ 53 | 5d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows no explicit permission declarations, user confirmation mechanisms, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. All trust criteria are unmet, hence scores of 0.
Self-consistency: README, architecture docs, and tests are consistent in describing pure stdlib, zero dependencies, and strict quality gates. Dependency availability: Explicitly zero dependencies, only Python 3.10+, tests use unittest, low risk. Failure messages: Tests and docs mention BLOCKED with reasons, but no concrete examples, so score 2.
Audience and scenarios: Clearly targets agents like Claude Code, Codex, OpenCode, and supports multiple object types. Capability boundaries: Docs detail supported objects, characters, CS2 weapons, and limitations. Trigger precision: Provides clear command examples and parameter descriptions. Environment fit: Supports multiple hosts with installation and symlink instructions.
Information architecture: Clear structure with README, ARCHITECTURE, ROADMAP. Install notes: Provides git clone and symlink steps. Naming stability: Version numbers clear, CHANGELOG present. Examples and FAQ: Multiple demos and code examples. Known limitations: Explicitly states single-image limitations. License: Apache-2.0. Versioning and changelog: CHANGELOG and version numbers. Maintenance responsibility: Contribution guide and sponsor link, but maintainer identity not explicit, so score 1.
Output usability: Generated TypeScript factory and JSON spec are directly usable, with renders and comparison sheets. Marginal value: Unique code-generation approach vs traditional mesh extraction. Cost-benefit: Emphasizes token efficiency but no concrete cost data, so score 2.
Claim traceability: Most claims have corresponding files or docs. Cross-source corroboration: Tests and CI config exist, but no independent verification. Fact-inference separation: Docs clearly distinguish inference and fact, e.g., PBR evidence is inference.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- No permission declarations or data flow transparency; review before use.
- Dependency security not explicit; despite zero-dependency claim, verify.
- Maintainer identity unverified; update path unclear.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.0.0 2.0.0: The Plugin Update
Release notes excerpt
The Plugin Update. The plugin ecosystem — domain registry, img2 harness, plugin-served domains — ships as its own major, pulled forward from the original Procedural World bundle. Breaking - animated-character is served by the installed [plugin-character](https://github.com/img2threejs/plugin-character) (img2 add img2threejs/plugin-character, harness >= 0.2.3). The in-repo domain module is removed; without the plugin the profile fails loud naming what is available, and an in-flight workspace is refused while the provider is absent, resuming unchanged on reinstall. …View on GitHub ↗ -
v1.5.2 1.5.2: Support VFX / Animation for character
Release notes excerpt
Changelog [1.5.2] — 2026-09-03 Theme: a clip that exists is not a clip that plays, and rigging may only add. Rigging failures in 1.5.1 were total and silent: clips held actions, the mixer held state, buttons dispatched, and nothing moved. This release turns the measured repair pipeline into executable modules, wires it into the workflow, and freezes the source geometry so binding cannot silently damage the model. Workflow integration Added - animated-character workflow profile (forge/_shared/workflow_state.py RIG_STEPS, …View on GitHub ↗ -
v1.5.1 1.5.1: add the GLB-reference route
Release notes excerpt
[1.5.1] — 2026-08-23 Theme: the GLB-reference route. A GLB stops being an informal aid and becomes a measurement instrument with a packaged pipeline, three bounded prompts, and an explicit statement of which parameters it can be held to 1:1 and which it cannot. Added - Add integrations/glb_character_pipeline, an opt-in three-stage reconstruction — cross-section loft, implicit surface, TypeScript encode — carrying its own pyproject.toml and uv.lock so the stdlib-only forge core stays dependency-free. Nothing in forge/ imports it. Stage 1 reproduces …View on GitHub ↗