vinhhien112/img2obj

Purpose and Entry Points

img2obj is a local Codex plugin that turns a reference image into a quality-gated procedural Three.js asset: a structured sculpt specification plus generated TypeScript factory code. Plugin discovery begins at .codex-plugin/plugin.json; the unified Python CLI is scripts/sculpt.py. The Codex-facing workflow and modeling guidance live in skills/object-to-threejs-procedural/SKILL.md.

Reference Intake and Feasibility

Reference images are assessed before modeling for visibility, separation, complexity, and usable views. scripts/new_pre_spec_assessment.py creates the assessment, while scripts/probe_reference_image.py extracts image evidence and scripts/visual_feature_gate.py enforces visual-feature readiness. This boundary prevents unsupported or ambiguous references from silently becoming geometry plans.

ObjectSculptSpec Contract

The central artifact is an ObjectSculptSpec, which records hierarchy, parts, geometry intent, materials, pivots, sockets, critical features, phase status, and review requirements. Its contract and validation are implemented in scripts/sculpt_contract.py and scripts/validate_sculpt_spec.py; spec creation/migration is handled by scripts/new_sculpt_spec.py and scripts/migrate_sculpt_spec.py. All later stages consume this structured plan rather than infer directly from pixels.

Pass-Orchestrated Production Workflow

Model creation advances through controlled phases—blockout, form, lookdev, and interaction—rather than generating a finished asset in one step. scripts/sculpt_pass_orchestrator.py controls transitions and dependencies; scripts/sculpt_checkpoint.py persists phase checkpoints; scripts/sculpt_user_approval.py gates promotion on explicit approval. The workflow uses state and module abstractions in scripts/sculpt_module_state.py and scripts/sculpt_modules.py.

Procedural Geometry and Generated Output

The generator emits code-only Three.js construction logic intended for a separate browser/Three.js project. Core geometry construction is in scripts/sculpt_geometry.py, with TypeScript factory emission in scripts/generate_threejs_factory.py. Specialized procedural domains are deliberately separated: scripts/sculpt_tree_generator.py, scripts/sculpt_landform_generator.py, and scripts/sculpt_special_geometry_typescript.py. Generated code is the integration boundary; this repository does not host the runtime renderer/application.

Materials, Style, and Reference-Derived PBR

Style classification and material intent are captured before look development through scripts/sculpt_style.py and scripts/sculpt_perception.py. scripts/extract_reference_pbr.py can derive palette and PBR-oriented evidence from the source image. Capability-specific guidance for glass, fur, fabric, emissive effects, vegetation, and hard surfaces is maintained under skills/object-to-threejs-procedural/references/patterns/.

Visual Review and Correction Loop

The quality system compares rendered browser screenshots against the active reference, emphasizing both overall identity and critical recognizable features. Review artifacts are organized by scripts/sculpt_image_io.py and scripts/make_visual_comparison_sheet.py; review decisions and corrections flow through scripts/sculpt_module_review.py and scripts/sculpt_corrections.py. AI image/vision access is an external dependency for source cleanup, planned views, and acceptance judgment; local Python scripts package evidence but do not independently determine visual similarity.

Runtime and Infrastructure Boundaries

The control plane is Python 3.10+ CLI tooling and Codex plugin/skill instructions. Output targets TypeScript and Three.js in an external browser project, where rendering, screenshots, controls, and animation execute. No database, server, or hosted service is represented in the repository; external AI vision is required for final visual review.