Skip to content

anbeime/skill / skills/img2threejs/img2threejs

img2threejs

Verified

Turn an object or character reference image into a quality-gated, animation-ready procedural Three.js model built in code. Use for image-to-3D reconstruction, detail-accurate object rebuilds, stylized/likeness-maximized human characters, sculpt specs, and staged code generation.

FileKindSize
.github/FUNDING.ymlconfig94 B
.github/ISSUE_TEMPLATE/bug_report.ymlconfig2.3 KB
.github/ISSUE_TEMPLATE/contribution_intent.ymlconfig1.8 KB
.github/ISSUE_TEMPLATE/feature_request.ymlconfig1.4 KB
.github/pull_request_template.mdmarkdown1.1 KB
.github/release.ymlconfig471 B
.github/workflows/beta-release.ymlconfig1.9 KB
.github/workflows/ci.ymlconfig349 B
.github/workflows/issue-triage.ymlconfig783 B
.github/workflows/pr-issue-close-policy.ymlconfig279 B
.github/workflows/release.ymlconfig625 B
.gitignoreother2.4 KB
CHANGELOG.mdmarkdown33.1 KB
CLAUDE.mdmarkdown2.8 KB
CONTRIBUTING.mdmarkdown4.7 KB
LAB-FINDINGS.mdmarkdown5.7 KB
LICENSEother11.1 KB
README.mdmarkdown38.9 KB
ROADMAP.mdmarkdown16.3 KB
SKILL.mdskill md30.8 KB
assets/logo.svgother2.0 KB
assets/sponsors/atlas-cloud-logomark-black.svgother595 B
assets/sponsors/atlas-cloud-logomark-white.svgother595 B
assets/sponsors/hyper3d-logomark-black.pngbinary1.1 KB
assets/sponsors/hyper3d-logomark-white.pngbinary1.2 KB
assets/sponsors/tripo-logomark-black.svgother1002 B
assets/sponsors/tripo-logomark-white.svgother1002 B
docs/ARCHITECTURE.mdmarkdown14.0 KB
docs/GLB_ANIMATED_CHARACTER_PROMPT.mdmarkdown13.1 KB
docs/GLB_CHARACTER_ANIMATION_PROMPT.mdmarkdown14.6 KB
docs/GLB_CHARACTER_POLISH_PROMPT.mdmarkdown10.6 KB
docs/GLB_CHARACTER_PROMPT.mdmarkdown19.1 KB
docs/HAIR_PIPELINE.mdmarkdown10.5 KB
docs/RESEARCH_TRELLIS2_TO_IMG2THREEJS.mdmarkdown35.4 KB
docs/STAGE_R_BACKLOG.mdmarkdown18.0 KB
docs/STAGE_R_TEST_PLAN.mdmarkdown14.0 KB
docs/TOKEN_COST.mdmarkdown2.5 KB
docs/UPGRADE_PLAN.mdmarkdown30.4 KB
docs/cs2-anatomy/gloves.mdmarkdown11.6 KB
docs/cs2-anatomy/heavy.mdmarkdown13.8 KB
docs/cs2-anatomy/knives.mdmarkdown18.2 KB
docs/cs2-anatomy/pistols.mdmarkdown12.0 KB
docs/cs2-anatomy/rifles.mdmarkdown13.1 KB
docs/cs2-anatomy/smgs.mdmarkdown13.4 KB
docs/cs2-anatomy/snipers.mdmarkdown13.8 KB
docs/cs2/3D_Technical_Mapping.jsonconfig10.6 KB
docs/cs2/3D_Technical_Reference.mdmarkdown22.2 KB
docs/cs2/3D_Vocabulary_CS2.jsonconfig10.0 KB
docs/cs2/3D_Vocabulary_CS2_Dictionary.mdmarkdown26.6 KB
docs/cs2/distill.mdmarkdown9.9 KB
docs/cs2/review-gates.mdmarkdown2.5 KB
docs/integrations/reference_fidelity_tooling.mdmarkdown6.2 KB
docs/issue-triage.mdmarkdown1.8 KB
docs/materials/IMAGE_MATERIAL_ANALYSIS.mdmarkdown5.0 KB
docs/materials/README.mdmarkdown5.2 KB
docs/materials/THREEJS_MATERIAL_REFERENCE.mdmarkdown11.4 KB
docs/materials/material-reference.jsonconfig55.0 KB
docs/pipelines/character-rigging-animation-1.5.2.mdmarkdown22.3 KB
docs/raw/.keepother0 B
docs/raw/img2threejs-skill-dataset.jsonconfig107.3 KB
docs/specs/render-profile.v2.example.jsonconfig2.6 KB
docs/specs/render-profile.v2.schema.jsonconfig3.8 KB
docs/specs/vocabulary/README.mdmarkdown4.4 KB
docs/specs/vocabulary/core_3d.jsonlother13.2 KB
docs/specs/vocabulary/core_3d_reconstruction.jsonlother56.1 KB
docs/specs/vocabulary/cs2.jsonlother7.1 KB
docs/specs/vocabulary/cs2_reconstruction.jsonlother85.7 KB
docs/standard-prompts/README.mdmarkdown2.2 KB
docs/standard-prompts/build.mdmarkdown5.2 KB
docs/standard-prompts/glb-force-measured.mdmarkdown8.6 KB
docs/standard-prompts/polish.mdmarkdown2.7 KB
docs/standard-prompts/vfx.mdmarkdown5.7 KB
forge/_shared/artifact_cache.pyscript1.7 KB
forge/_shared/chirality.pyscript12.1 KB
forge/_shared/color_metrics.pyscript3.6 KB
forge/_shared/feature_acceptance_policy.pyscript4.2 KB
forge/_shared/image_hash.pyscript4.0 KB
forge/_shared/jpeg.pyscript16.0 KB
forge/_shared/material_physics.pyscript12.2 KB
forge/_shared/pipeline_routing.pyscript7.0 KB
forge/_shared/scalp_field.pyscript14.3 KB
forge/_shared/sdf_primitives.pyscript8.3 KB
forge/_shared/spec_search.pyscript61.9 KB
forge/_shared/spec_search_profiles.jsonconfig1.4 KB
forge/_shared/status_banner.pyscript1.4 KB
forge/_shared/subdivision.pyscript10.5 KB
forge/_shared/vertex_paint.pyscript10.8 KB
forge/_shared/workflow_state.pyscript20.5 KB
forge/materials/__init__.pyscript355 B
forge/materials/compatibility.pyscript5.1 KB
forge/materials/reference.pyscript10.2 KB
forge/next.pyscript4.4 KB
forge/report.pyscript1.5 KB
forge/requirements.txtmanifest335 B
forge/stage1_intake/analyze_texture.pyscript12.1 KB
forge/stage1_intake/bind_detail_properties.pyscript4.6 KB
forge/stage1_intake/build_detail_inventory.pyscript13.0 KB
forge/stage1_intake/camera_fitting_math.pyscript5.5 KB
forge/stage1_intake/camera_fitting_solver.pyscript8.2 KB
forge/stage1_intake/camera_fitting_types.pyscript8.2 KB
forge/stage1_intake/camera_image_helpers.pyscript6.0 KB
forge/stage1_intake/check_intake_correctness.pyscript4.8 KB
forge/stage1_intake/check_reference_admission.pyscript7.6 KB
forge/stage1_intake/cs2_foundation.pyscript7.9 KB
forge/stage1_intake/cs2_manifest.pyscript10.5 KB
forge/stage1_intake/cs2_review_contract.pyscript1.7 KB
forge/stage1_intake/delight_albedo.pyscript14.2 KB
forge/stage1_intake/detect_cs2.pyscript9.7 KB
forge/stage1_intake/detect_reference_effects.pyscript8.9 KB
forge/stage1_intake/extract_cs2_textures.pyscript5.6 KB
forge/stage1_intake/extract_gradient_stops.pyscript5.8 KB
forge/stage1_intake/extract_hair_evidence.pyscript18.6 KB
forge/stage1_intake/extract_landmarks.pyscript16.0 KB
forge/stage1_intake/extract_part_color_recipe.pyscript20.8 KB
forge/stage1_intake/extract_pbr_evidence.pyscript32.5 KB
forge/stage1_intake/fetch_cs2_metadata.pyscript6.4 KB
forge/stage1_intake/label_glb_nodes.pyscript13.0 KB
forge/stage1_intake/locate_cs2_vpk.pyscript2.6 KB
forge/stage1_intake/material_region_analysis.pyscript9.8 KB
forge/stage1_intake/probe_glb.pyscript15.0 KB
forge/stage1_intake/probe_image.pyscript5.4 KB
forge/stage1_intake/run_vision_adapter.pyscript1.6 KB
forge/stage1_intake/search_specs.pyscript7.5 KB
forge/stage1_intake/semantic_decomposition.pyscript4.5 KB
forge/stage1_intake/solve_camera_pose.pyscript10.7 KB
forge/stage2_spec/apply_material_analysis.pyscript8.6 KB
forge/stage2_spec/cs2_adapters.pyscript3.0 KB
forge/stage2_spec/derive_geometry.pyscript4.3 KB
forge/stage2_spec/hair_profile.pyscript14.5 KB
forge/stage2_spec/humanoid_proportions.pyscript9.0 KB
forge/stage2_spec/new_pre_spec_assessment.pyscript12.1 KB
forge/stage2_spec/new_sculpt_spec.pyscript127.4 KB
forge/stage2_spec/validate_sculpt_spec.pyscript144.5 KB
forge/stage3_build/bake_projected_texture.pyscript8.8 KB
forge/stage3_build/decimate.pyscript10.4 KB
forge/stage3_build/generate_threejs_factory.pyscript207.6 KB
forge/stage3_build/module_cache.pyscript5.6 KB
forge/stage3_build/morph_targets.pyscript7.3 KB
forge/stage3_build/orchestrate_passes.pyscript27.6 KB
forge/stage3_build/uv_unwrap.pyscript24.7 KB
forge/stage3_build/visual_hull.pyscript16.4 KB
forge/stage4_review/_fit_divine_eye.pyscript2.6 KB
forge/stage4_review/append_review.pyscript20.4 KB
forge/stage4_review/attachment_anchor.pyscript16.2 KB
forge/stage4_review/calibrate_eye.pyscript5.4 KB
forge/stage4_review/check_part_coverage.pyscript13.1 KB
forge/stage4_review/compare_region_passes.pyscript7.6 KB
forge/stage4_review/correction_loop.pyscript10.2 KB
forge/stage4_review/cs2_review.pyscript8.7 KB
forge/stage4_review/diagnose_render.pyscript15.5 KB
forge/stage4_review/diagnose_render_multi_angle.pyscript5.6 KB
forge/stage4_review/divine_eye.pyscript21.0 KB
forge/stage4_review/fit_params.pyscript16.6 KB
forge/stage4_review/geometry_integrity.pyscript15.1 KB
forge/stage4_review/hair_gate.pyscript9.5 KB
forge/stage4_review/interior_difference.pyscript7.8 KB
forge/stage4_review/joint_loops.pyscript8.2 KB
forge/stage4_review/make_comparison_sheet.pyscript10.9 KB
forge/stage4_review/material_comparator.pyscript7.9 KB
forge/stage4_review/material_feedback.pyscript6.7 KB
forge/stage4_review/material_gate.pyscript5.8 KB
forge/stage4_review/material_views.pyscript7.5 KB
forge/stage4_review/mesh_reference_compare.pyscript16.2 KB
forge/stage4_review/multi_pass.pyscript3.1 KB
forge/stage4_review/objectness.pyscript5.4 KB
forge/stage4_review/pairwise_penetration.pyscript16.2 KB
forge/stage4_review/per_feature.pyscript6.8 KB
forge/stage4_review/render_bridge.pyscript24.1 KB
forge/stage4_review/scalp_exposure.pyscript11.5 KB
forge/stage4_review/self_intersection.pyscript26.3 KB
forge/stage4_review/swept_arc_gate.pyscript14.3 KB
forge/stage4_review/turntable_gate.pyscript17.6 KB
forge/stage4_review/validate_render_profile.pyscript8.9 KB
forge/stage4_review/vertex_region_gate.pyscript20.3 KB
forge/stage4_review/vlm_gate.pyscript8.8 KB
forge/stage5_rig/CONTRACT_1.5.2.mdmarkdown3.6 KB
forge/stage5_rig/NOTES.mdmarkdown8.5 KB
forge/stage5_rig/__init__.pyscript302 B
forge/stage5_rig/action_design.pyscript88.2 KB
forge/stage5_rig/clip_features.pyscript33.2 KB
forge/stage5_rig/emit_animation_runtime.pyscript17.7 KB
forge/stage5_rig/emit_rig.pyscript17.6 KB
forge/stage5_rig/geodesic_skinning.pyscript23.0 KB
forge/stage5_rig/glb_rig_reference.pyscript58.8 KB
forge/stage5_rig/mesh_parity.pyscript36.7 KB
forge/stage5_rig/rig_gates.pyscript78.7 KB
forge/stage5_rig/rig_spec.pyscript6.4 KB
forge/stage5_rig/skin_conditioning.pyscript25.9 KB
forge/stage5_rig/validate_rig_payload.pyscript8.8 KB
forge/state.pyscript3.5 KB
forge/tests/fixtures/implicit_character_torso_limb.jsonconfig1.4 KB
forge/tests/fixtures/knife_review_scene.jsonconfig1.3 KB
forge/tests/fixtures/stand_proud_hair_on_head.jsonconfig3.0 KB
forge/tests/fixtures/subdivision_cage.jsonconfig812 B
forge/tests/fixtures/visual_hull_two_views.jsonconfig2.6 KB
forge/tests/showcase_test_support.pyscript698 B
forge/tests/test_action_design.pyscript37.3 KB
forge/tests/test_albedo_color_space.pyscript4.6 KB
forge/tests/test_analyze_texture.pyscript6.0 KB
forge/tests/test_attachment_anchor.pyscript8.2 KB

docs/HAIR_PIPELINE.md

View on GitHub
# Hair

How img2threejs reconstructs hair, what it measures, and — as precisely as possible — what it does
not know.

## Why hair needed its own subsystem

Before this, hair was one ellipsoid (`forge/stage2_spec/new_sculpt_spec.py`, the `("hair", "Hair",
"ellipsoid", ...)` entry). A grep for `hair` across `forge/` returned 44 lines, all of them tests,
comments or material ids, and none of them logic. Three pieces existed and were unused: a
`faceLandmarks.hairline` slot no generator read, a `fiber-strand` topology class with nothing behind
it, and the `tapered-sweep` primitive with zero specs using it.

The gap that mattered was not geometric. In one session, four separate diagnoses of a single
hairstyle were wrong, and every one was caught only by measurement after the fact. So the gates were
built before the generators.

## The measurement that set the architecture

The reference this pipeline calibrates against is
`public/references/low-poly-humanoid-glb/human_pbr.glb`. Probing it:

| property | value |
| --- | --- |
| vertices | 570,400 |
| triangles | 1,000,000 |
| meshes / materials | 1 / 1, merged |
| textures | diffuse, normal, metallic-roughness (PNG) |
| skins / animations | 0 / 0 |

`forge/stage1_intake/probe_glb.py` reports `"reliableSemanticBoundary": "multipart-glb-required"` —
the hair cannot be separated from the body by metadata.

Surface roughness, measured as the radial step between adjacent azimuth bins at each height:

| height band | radial step | vs control |
| --- | --- | --- |
| crown / hair | 0.00338 | **+8%** |
| upper hair | 0.00405 | +30% |
| hair / brow | 0.00429 | +38% |
| face / cheek | 0.00385 | +23% |
| **torso (no hair, control)** | **0.00312** | — |

The hair surface is as smooth as a torso. At a head radius of ~0.10 that is roughly 3.4 mm of
undulation, where a real lock is 10–30 mm. **The reference contains no lock geometry.** Its entire
strand appearance is in the diffuse and normal textures.

Two consequences follow, and they run in opposite directions to the obvious plan:

1. Since img2threejs emits code and no textures, the strand impression must come from **faceting and
   material response**, not from adding lock geometry.
2. The reference **cannot calibrate lock parameters**, because it has none to measure.

## Representation tiers

| tier | what it is | calibration |
| --- | --- | --- |
| `shell` (default) | a faceted mass hugging the scalp | measurable against the reference |
| `masses` | a shell plus a few named regional masses | envelope measurable |
| `locks` | individual tapered locks | **no ground truth available** |

`locks` is not forbidden. It emits a warning naming exactly why its numbers are derived rather than
observed. Unblocking it needs a multipart GLB with a separated, named hair mesh.

## Primitives

| primitive | verdict |
| --- | --- |
| `tapered-sweep` | preferred — curved spine, parallel transport, reaches a true point |
| `curve-sweep`, `lathe`, `ellipsoid` | allowed |
| `instanced-cluster` | allowed, for distant strand impressions only |
| `plane-card` | **rejected** — needs an alpha texture, which this pipeline cannot emit |
| `tube` | **rejected** — constant radius, reads as a noodle |
| `box` | **rejected** |

Enforced in `forge/stage2_spec/hair_profile.py` and again per-component in
`validate_sculpt_spec.py`.

## The stages

### Stage 1 — `extract_hair_evidence.py`

Measures from reference images: hair/skin split (Otsu, not a percentile — see below), banded dark
coverage across crown/mid/jaw, the hairline (writing the `faceLandmarks.hairline` slot that has
existed unfilled since v1.2), the specular band position, and the root-to-tip luminance delta.

It reports `notObserved` explicitly. A frontal-only set states that the rear of the head was never
seen, so nothing downstream authors a nape as if it were measured.

> **A trap worth recording.** The first implementation thresholded at a fixed percentile. That makes
> the reported hair fraction true by construction: it read 0.380, 0.384 and 0.382 across three
> different views of the same subject, which looks like agreement and is arithmetic. Otsu's
> between-class variance split fixed it, and the same three views now read 0.387 / 0.592 / 0.747 —
> front lowest because the face occupies it, rear highest.

### Stage 2 — `hair_profile.py`

**This stage defines and validates a schema. It does not compile one.** There is no
profile-to-`componentTree` compiler yet; a spec still authors its hair components directly, and the
profile's rules are enforced by the validator plus the `standProud` march the generator emits.
Writing that compiler is the next piece of work, and it is called out here because a schema reads
exactly like a working feature and this one is not one yet.

The schema has four blocks: `scalpComponentId` (the head component whose ring stack the scalp is
derived from, never authored twice), `hairline` (control points in scalp `(u, v)`), `flowField`
(part line, whorls, gravity, sweep — about six numbers, which is what makes a wide range of styles
reachable without authoring a direction per mass), and `masses[]`.

**Roots are `(u, v)` on the scalp, never absolute positions.** An absolute root is a hard validation
error. This is the same binding Blender uses for hair, where a curve root is a
`surface_uv_coordinate` on the emitter mesh, and it makes the recorded failure structurally
impossible rather than a matter of authoring care.

### Stage 3 — `standProud` and the clearance march

A component declares `standProud: {againstComponentId, clearance, maxPush}`. The generator emits
`applyStandProud`, which pushes every vertex outward along its **own radial spoke** until a signed
distance field reads at least `clearance`, capped at `maxPush`.

This is `hug` from the hand-written showcase demo, generalised into the skill. In that demo the
garment held its clearance as a measurement and worked; the hair held the same requirement as a
comment and broke. `maxPush` is required, not optional: an uncapped march walks inner vertices
through the target and out the far side.

Hair material comes from `hair.human.code-only` in the material reference — no maps, higher sheen
and anisotropy than the textured profile, because with no `anisotropyMap` and no `normalMap` those
are the only carriers left. A `rootTipGradient` emits vertex colours along the mass's own axis.

### Stage 4 — the gates

| gate | kind | catches |
| --- | --- | --- |
| `scalp_exposure.py` | **hard** | skull showing through, geometrically, before any render |
| `hair_gate.py` | soft | banded coverage delta, hairline offset, highlight-band offset |

The hard/soft split is the point. A bald patch is always wrong; a coverage shortfall is often the
right compromise. Conflating them is what produced the recorded regression: a shortfall was answered
by widening the masses, which pushed them off the skull.

`scalp_exposure` only counts hair that is **outside** the skull. A nearest-neighbour test would have
passed the failing build, because the vertices were still nearby — they had sunk below the surface.

### Stage 5 — rigging

Hair is **rigidly parented**, never smooth-skinned. `geodesic_skinning.RIGID_ROLES` excludes
`hair`, `detail`, `decal` and `panel`.

Measured on the test fixture: the geodesic distance from the neck joint to a crown vertex is 33.6
voxels against the head bone's 15.0, which at falloff power 3 leaves the **neck holding 8.1% of the
crown**. Turning the neck would shear the hair against the skull it sits on — and because
`standProud` and `scalpExposure` are bind-pose checks, no gate would ever see it.

Long hair that crosses a joint uses a short chain of bones with one mesh segment rigidly parented
per bone. Still no blended vertex weights.

## What this does not know

- **Lock parameters are derived, not measured.** Taper ratios, cross-section aspect, lock counts,
  whorl strengths. Listed in `hair_profile.UNCALIBRATED_FIELDS`, and any mass setting one without
  `uncalibrated: true` gets a warning. Precedent for why: a recovered build had eleven hair locks
  sharing a tip radius of 0.0327 to four decimal places, and nothing objected.
- **Every gate threshold in this subsystem is uncalibrated** and reports itself as such.
- **Dynamics is out of scope.** A single image contains no motion, so any hair simulation would be
  invention rather than reconstruction.
- **Strand-level hair is out of scope permanently**, by architecture. No textures, no alpha.
- **There is no `hairProfile` compiler.** The schema is validated; nothing turns it into components.
- **The `standProud` march can fail silently-ish.** A vertex that exhausts `maxPush` while still
  inside the target is counted and warned about at runtime (`geometry.userData.standProud`), but
  nothing fails the build over it. Measured on the shipped fixture: 2 of 8 sampled hair vertices sat
  0.059 inside the skull against a 0.04 cap and could never have reached clear.
- **`scalp_exposure` measures spec-derived points, while the march displaces vertices at runtime.**
  So the gate does not measure the geometry that ships. Closing that means moving the march into
  Python at build time — the single largest improvement still available here.

## The recorded failure, in full

It is referenced throughout the code, so here it is once, completely.

The hair side masses of the low-poly humanoid demo were widened by hand to close a measured coverage
deficit (profile mid band: reference 41.5%, ours 7.8%).

| view | before | after | delta |
| --- | --- | --- | --- |
| profile | 46.8% | 43.2% | **−3.6** |
| left-profile | 61.4% | 59.0% | −2.5 |
| orbit−35 | 30.7% | 29.6% | −1.2 |
| front | 38.7% | 38.3% | −0.5 |
| orbit+35 | 25.7% | 25.3% | −0.4 |
| rear | 49.9% | 49.8% | −0.0 |
| **mean** | **42.2%** | **40.9%** | **−1.3** |

Worse on all six. Dark coverage went *down*. Crown scalp exposure, measured on the archived captures:

| view | before | after | delta |
| --- | --- | --- | --- |
| orbit+35 | 54.0% | 68.9% | **+14.9** |
| profile | 48.8% | 55.1% | +6.3 |
| front | 53.3% | 57.6% | +4.3 |
| orbit−35 | 43.3% | 44.3% | +1.0 |

The cause: `sectionedLoft` has a straight root-to-tip spine while the skull is convex, so thickening
a section moved the surface sideways rather than outward. The mass slid off the skull, the skull
became proud of the hair, and the render grew a bare strip. The invariant it broke was already
written in the file it broke in:

> EVERY piece must stand proud of the skull at its own height. Where the skull is proud of the hair,
> the head renders bald there.

Every gate in this subsystem exists to make that sentence arithmetic.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall