img2threejs

Files (200)

• FUNDING.yml · .github/
• bug_report.yml · .github/ISSUE_TEMPLATE/
• contribution_intent.yml · .github/ISSUE_TEMPLATE/
• feature_request.yml · .github/ISSUE_TEMPLATE/
• pull_request_template.md · .github/
• release.yml · .github/
• beta-release.yml · .github/workflows/
• ci.yml · .github/workflows/
• issue-triage.yml · .github/workflows/
• pr-issue-close-policy.yml · .github/workflows/
• release.yml · .github/workflows/
• .gitignore
• CHANGELOG.md
• CLAUDE.md
• CONTRIBUTING.md
• LAB-FINDINGS.md
• LICENSE
• README.md
• ROADMAP.md
• SKILL.md
• logo.svg · assets/
• atlas-cloud-logomark-black.svg · assets/sponsors/
• atlas-cloud-logomark-white.svg · assets/sponsors/
• hyper3d-logomark-black.png · assets/sponsors/
• hyper3d-logomark-white.png · assets/sponsors/
• tripo-logomark-black.svg · assets/sponsors/
• tripo-logomark-white.svg · assets/sponsors/
• ARCHITECTURE.md · docs/
• GLB_ANIMATED_CHARACTER_PROMPT.md · docs/
• GLB_CHARACTER_ANIMATION_PROMPT.md · docs/
• GLB_CHARACTER_POLISH_PROMPT.md · docs/
• GLB_CHARACTER_PROMPT.md · docs/
• HAIR_PIPELINE.md · docs/
• RESEARCH_TRELLIS2_TO_IMG2THREEJS.md · docs/
• STAGE_R_BACKLOG.md · docs/
• STAGE_R_TEST_PLAN.md · docs/
• TOKEN_COST.md · docs/
• UPGRADE_PLAN.md · docs/
• gloves.md · docs/cs2-anatomy/
• heavy.md · docs/cs2-anatomy/
• knives.md · docs/cs2-anatomy/
• pistols.md · docs/cs2-anatomy/
• rifles.md · docs/cs2-anatomy/
• smgs.md · docs/cs2-anatomy/
• snipers.md · docs/cs2-anatomy/
• 3D_Technical_Mapping.json · docs/cs2/
• 3D_Technical_Reference.md · docs/cs2/
• 3D_Vocabulary_CS2.json · docs/cs2/
• 3D_Vocabulary_CS2_Dictionary.md · docs/cs2/
• distill.md · docs/cs2/
• review-gates.md · docs/cs2/
• reference_fidelity_tooling.md · docs/integrations/
• issue-triage.md · docs/
• IMAGE_MATERIAL_ANALYSIS.md · docs/materials/
• README.md · docs/materials/
• THREEJS_MATERIAL_REFERENCE.md · docs/materials/
• material-reference.json · docs/materials/
• character-rigging-animation-1.5.2.md · docs/pipelines/
• .keep · docs/raw/
• img2threejs-skill-dataset.json · docs/raw/
• …and 140 more

SKILL.md (first lines)

# img2threejs — Image to procedural Three.js

Rebuild the object visible in a reference image as a **code-only** procedural Three.js model,
gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is
reconstruction-by-code, **not** photogrammetry, mesh extraction, or downloaded art packs.

Agent-agnostic: works under Claude Code, Codex, or OpenCode. Wherever this doc says "agent
vision" or "agent browser tool", use whatever the host provides — native image reading, a
browser MCP (playwright/chrome-devtools), the project preview, or a user-supplied screenshot.

This file is the always-loaded router: it holds the order of operations and every hard rule as one
line. The full contract behind each rule lives in the `grimoire/` or `docs/` file that rule names —
read the named file at the moment you reach that stage, not before.

## Canonical shared checkout

Keep one checkout of this repository and let every host enter it through a symlink, so Claude and
Codex execute the same code instead of drifting apart:

```text
~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>
```

## When To Use

The user attaches/points to an object image and wants a procedural Three.js model, a
reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies,
action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.

## Core Promise

Sculpt from a photo, in order — never one-shot a mesh:
1. **Run `python3 forge/next.py --state .img2threejs/state.json [<spec>]` first**, at every start,
   resume, and before every correction iteration. It reports the ordered checklist, exact next
   command, evidence status, and bounded correction-loop status; it never replaces the spec/pass
   gates. Obey a hard stop; never continue from memory.
2. **Validate** the image is a suitable 3D target (`grimoire/intake/validation_rubric.md`).
3. **Assess** object class + complexity, then write a `qualityContract` before any code.
4. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors.
5. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization.
6. **Verify** each pass with a screenshot compared against the reference; fail a pass if an
   identity-defining feature is wrong even when the global score looks fine.

State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal
hidden sides or guarantee exact geometry — say so instead of faking confidence.

## Mandatory Local State Gate

Conversation context is disposable; `.img2threejs/state.json` is the local checklist authority.
Initialize once per reconstruction, then gate every step through it:

```bash
python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|cs2|character|animated-character> --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>
```

- `next.py` prints the current step, pass, incomplete mandatory steps, exact next command, and
  `loop/max`. Exit code 3 or `status=stopped` is a hard stop: report the reason and request input.
  Never bypass it by reconstructing progress from chat history.
- Every completed step needs evidence; mark a non-applicable step `skipped` only with `--reason` —
  silent omission is forbidden. Loop counts derive from `reviewHistory` actions
  (`refine-spec`/`refine-code`), not agent memory. Defaults: 3 corrections per pass, 6 total.
- Profiles add mandatory gates without changing the core order: `cs2` requires classification,
  manifest, and a machine-readable CS2 review before AI review; `character` requires the character
  contracts and landmark evidence; `animated-character` adds all of `character` plus the nine Stage R
  steps (`grimoire/readiness/animation_contract.md`). Pick it whenever the rig must MOVE — on
  `character` the Stage R gates are absent and the build completes without ever running them, which
  is how animation used to ship broken. Its order is load-bearing: repair the mesh, freeze it, bind
  additively, then verify parity. Every profile records suitability, projection applicability, and
  material-evidence applicability. The state file is a resumability index, not visual evidence:
  renders, specs, review history, and deterministic gates remain the authoritative artifacts.

## Required Inputs

- one image path / screenshot / URL / attached image (if missing or unreadable, ask)
- intended use: prop, game object, hero render, playable/destructible object, animation rig
  (default: real-time browser prop with interactive performance)
- for a CS2 request, an authoritative classification record (family/subtype and evidence refs) or
  an explicit request for the user/vision provider to supply one; heuristic detection alone is not
  enough to select a geometry adapter

## The Loop (scripts do enforcement; agent vision does judgment)

Run scripts from the skill root (`forge/...`). Pure Python 3.10+ stdlib, no pip installs.
Full flags: `grimoire/scripts.md`. Never let a script *score* visuals — that is the agent's job.

1. **Analyze the image first** (agent vision, before any script): work the layered observation
   protocol in `grimoire/intake/image_analysis.md` — identify/classify, decompose macro→meso→micro,
   map part relationships, name materials in PBR terms, list identity-defining features, and flag
   what the single view hides. Observation before inference; controlled 3D vocabulary; 3D
   object-space not 2D image-space. Then probe local images:
   `forge/stage1_intake/probe_image.py <image>` (metadata only, not a visual check).
1a. **Local Spec Search** — after image analysis, before writing or refining a spec, pull local
    domain evidence (anatomy/PBR/wear/geometry/runtime/physics) rather than inventing it:
    `python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json`
    (auto-runs BM25, auto-picks `cs2`/`core_3d` collection, writes a `localSpecSearch` bundle that
    `new_sculpt_spec.py --assessment` carries into the spec). Full query-expansion recipe
    (bilingual terms, focused `search_specs.py` retrieval, cache rules):
    `grimoire/intake/local_spec_search.md`. MUST read it before retrying an incomplete or
    domain-specific query.
1b. **CS2 intake manifest** — for a CS2 request, create and validate `cs2-intake.json` before
    pre-spec authoring (admission, heuristic signal, classification, family/route resolution).
    MUST read `grimoire/intake/cs2_intake_contract.md` completely before creating the manifest or
    running pre-spec assessment.
1c. **Optional fidelity evidence adapters** — only when they improve an observed weak point; the
    stdlib core remains authoritative. Thin/complex masks → local SAM2; character face/pose →
    MediaPipe; weak front/back cues → Depth Anything V2
    (`forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...`; every adapter emits
    provenance; monocular depth is relative only). **MCP-only scene mutations never count as
    implementation** — write the proven change back to the spec or TypeScript, rebuild, recapture.
    Full adapter + MCP routing and authority boundaries:
    `docs/integrations/reference_fidelity_tooling.md`.
2. **Pre-Spec Assessment Gate** — classify + score complexity + write the quality contract:
   `forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json`. Rules: `grimoire/intake/quality_contract.md`.
   Set `objectClass.primaryDomain` (`object` | `character` | `hybrid`) and fill the seeded
   `detailInventory` (its `targetMinDetails` scales with complexity). **Supported CS2 knife skins
   and Glock-18 assets**: always pass `--cs2`, which defaults the complexity tier to `ultra-complex`

From anbeime/skill, Apache-2.0.

More from anbeime/skill