img2threejs — Code-Only 3D Reconstruction
Rebuild objects from a reference image as code-only, procedural, quality-gated, animation-ready Three.js models, token-efficiently.
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.
- 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.
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
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 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.