img2threejs is a specialized framework designed to reconstruct 3D objects from single reference images into animation-ready, code-only Three.js models. Unlike traditional photogrammetry or mesh-extraction tools, it utilizes a procedural "reconstruction-by-code" approach, generating TypeScript factories that define objects via primitives, shaders, and geometric logic rather than raw mesh data.

Core Methodology

The system operates through a staged, gate-controlled sculpting pipeline where the AI agent acts as both architect and reviewer. The process is divided into distinct build passes—including blockout, structural, form-refinement, material, surface, lighting, interaction, and optimization—ensuring each phase meets strict quality criteria before proceeding.

1. Intake and Assessment: The process begins with probe_image.py to evaluate the target's suitability. A pre-spec assessment classifies the subject (e.g., object, character, or hybrid) and defines a quality contract. A detailInventory is compiled to map identity-defining features (bevels, fasteners, seams) directly to real structural components.
2. Deterministic Gating: To optimize token usage, the system relies on standard library Python scripts (Python 3.10+) to handle bookkeeping, state management, and validation. This removes the need for the LLM to manage file I/O or mechanical syntax, focusing its reasoning solely on visual judgment.
3. Refinement Loop: After each pass, the agent generates a comparison sheet (reference image vs. current render). The agent then evaluates this using a vision model, choosing to either continue, refine-spec, or refine-code. This "fail-fast" mechanism prevents the propagation of errors from early build stages into the final geometry.
4. Procedural Architecture: The final output is a THREE.Group factory function. The model structure includes a root.userData.sculptRuntime object, providing a functional hierarchy of pivots, sockets, and colliders, ensuring the resulting model is immediately usable in animation or game environments.

Technical Specifications and Innovations

• Token Efficiency: By offloading logic to deterministic scripts—such as those using struct and zlib for PNG handling without external dependencies—the framework reserves expensive LLM tokens exclusively for visual assessment and high-level reasoning.
• Projection-First Path: For character or high-fidelity weapon reconstruction, the system employs a parametric template-fitting process. This involves de-lighting the source image to extract a neutral albedo, which is then projected onto the procedural mesh.
• CS2 Integration: The pipeline includes specialized review gates for CS2 (Counter-Strike 2) assets, enforcing strict component-coverage contracts and versioned scene metadata to ensure physical accuracy for high-spec weapon models.
• Quality Gates: The system enforces rigorous acceptance thresholds. For instance, material properties are derived from reference pixel gradients rather than relying on memory-based synthesis. The use of metrics like $\Delta E_{00}$ (CIEDE2000) for color math ensures that rendered colors survive tone-mapping without losing their characteristic finish (e.g., anodized vs. matte).

The project is structured around an incremental roadmap, moving from hard-surface objects (v1.0–1.4) to complex character rigging (v1.5), environment generation (v1.6), and eventually an integrated procedural world-building platform (v2.0).