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

forge/materials/reference.py

View on GitHub
#!/usr/bin/env python3
"""Load and resolve the canonical Three.js material reference library.

This is the runtime bridge for ``docs/materials/material-reference.json``.  The
registry is intentionally data-driven: profile numbers seed a candidate, while
image evidence and user metadata decide whether that candidate may proceed.
The module is stdlib-only so it can be used by every forge stage and in CI.
"""

from __future__ import annotations

import copy
import json
import re
from pathlib import Path
from typing import Any


ROOT = Path(__file__).resolve().parents[2]
DEFAULT_REFERENCE = ROOT / "docs" / "materials" / "material-reference.json"


class MaterialReferenceError(ValueError):
    """Raised when the canonical registry cannot safely be consumed."""


def _token(value: Any) -> str:
    return re.sub(r"[^a-z0-9]+", " ", str(value or "").strip().lower()).strip()


def _tokens(value: Any) -> set[str]:
    token = _token(value)
    return {token, token.replace(" ", "-")} if token else set()


def validate_reference(payload: dict[str, Any]) -> list[str]:
    """Return structural errors; an empty list means the registry is usable."""
    errors: list[str] = []
    if not isinstance(payload, dict):
        return ["reference must be a JSON object"]
    if payload.get("schemaVersion") != 1:
        errors.append("schemaVersion must be 1")
    renderer = payload.get("renderer")
    if not isinstance(renderer, dict) or renderer.get("engine") != "three.js":
        errors.append("renderer.engine must be three.js")
    sources = payload.get("sources")
    if not isinstance(sources, list) or not sources:
        errors.append("sources must be a non-empty array")
        source_ids: set[str] = set()
    else:
        source_ids = set()
        for index, source in enumerate(sources):
            if not isinstance(source, dict):
                errors.append(f"sources[{index}] must be an object")
                continue
            source_id = source.get("id")
            if not isinstance(source_id, str) or not source_id:
                errors.append(f"sources[{index}].id is required")
            elif source_id in source_ids:
                errors.append(f"duplicate source id {source_id!r}")
            source_ids.add(str(source_id))
            if not isinstance(source.get("url"), str) or not source["url"].startswith("https://"):
                errors.append(f"source {source_id!r} must have an https URL")
    materials = payload.get("materials")
    if not isinstance(materials, list) or not materials:
        errors.append("materials must be a non-empty array")
        materials = []
    ids: set[str] = set()
    legal = payload.get("legalRanges", {})
    if not isinstance(legal, dict):
        errors.append("legalRanges must be an object")
        legal = {}
    for index, material in enumerate(materials):
        if not isinstance(material, dict):
            errors.append(f"materials[{index}] must be an object")
            continue
        material_id = material.get("id")
        if not isinstance(material_id, str) or not material_id:
            errors.append(f"materials[{index}].id is required")
            continue
        if material_id in ids:
            errors.append(f"duplicate material id {material_id!r}")
        ids.add(material_id)
        if material.get("recipeBasis") != "inferred-starting-prior":
            errors.append(f"material {material_id!r} must label its recipeBasis as a prior")
        for source_ref in material.get("sourceRefs", []):
            if source_ref not in source_ids:
                errors.append(f"material {material_id!r} has unresolved sourceRef {source_ref!r}")
        render_prior = material.get("renderPrior", {})
        if not isinstance(render_prior, dict):
            errors.append(f"material {material_id!r}.renderPrior must be an object")
            continue
        for property_name, prior in render_prior.items():
            if property_name not in legal:
                errors.append(f"material {material_id!r} uses undocumented property {property_name!r}")
                continue
            if not isinstance(prior, dict) or not isinstance(prior.get("default"), (int, float)):
                errors.append(f"material {material_id!r}.{property_name} prior is malformed")
                continue
            bounds = prior.get("range")
            allowed = legal[property_name]
            if not isinstance(bounds, list) or len(bounds) != 2 or not isinstance(allowed, list) or len(allowed) != 2:
                errors.append(f"material {material_id!r}.{property_name} prior range is malformed")
                continue
            if bounds[0] > prior["default"] or prior["default"] > bounds[1] or bounds[0] < allowed[0] or bounds[1] > allowed[1]:
                errors.append(f"material {material_id!r}.{property_name} prior escapes legal range")
    return errors


def load_reference(path: Path | str = DEFAULT_REFERENCE) -> dict[str, Any]:
    reference_path = Path(path)
    try:
        payload = json.loads(reference_path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise MaterialReferenceError(f"cannot load material reference {reference_path}: {exc}") from exc
    errors = validate_reference(payload)
    if errors:
        raise MaterialReferenceError("invalid material reference: " + "; ".join(errors))
    return payload


def _material_index(payload: dict[str, Any]) -> list[dict[str, Any]]:
    return [item for item in payload.get("materials", []) if isinstance(item, dict)]


def _candidate(profile: dict[str, Any], method: str, confidence: float, reason: str) -> dict[str, Any]:
    return {
        "materialId": profile.get("id"),
        "profile": profile,
        "method": method,
        "confidence": max(0.0, min(1.0, float(confidence))),
        "reason": reason,
    }


def resolve_material(hypothesis: dict[str, Any], payload: dict[str, Any] | None = None) -> dict[str, Any]:
    """Resolve one hypothesis while retaining alternatives and uncertainty.

    Explicit user/metadata identity wins.  Alias and family matching never
    silently chooses between materially different candidates.
    """
    registry = payload or load_reference()
    materials = _material_index(registry)
    by_id = {str(item.get("id")): item for item in materials}
    explicit = hypothesis.get("materialId")
    if isinstance(explicit, str) and explicit in by_id:
        result = _candidate(by_id[explicit], "explicit-material-id", 1.0, "authoritative material id")
        result["status"] = "proceed"
        result["alternatives"] = []
        return result

    family = _token(hypothesis.get("family"))
    subtype = _token(hypothesis.get("subtype"))
    finish = _token(hypothesis.get("finish"))
    exact = [
        item for item in materials
        if _token(item.get("family")) == family
        and (not subtype or _token(item.get("subtype")) == subtype)
        and (not finish or _token(item.get("finish")) == finish)
    ]
    if len(exact) == 1:
        result = _candidate(exact[0], "family-subtype-finish", float(hypothesis.get("confidence", 0.7)), "exact semantic match")
        result["status"] = "proceed" if result["confidence"] >= 0.7 else "probe"
        result["alternatives"] = []
        return result

    aliases = set()
    for field in ("aliases", "alternatives"):
        value = hypothesis.get(field, [])
        if isinstance(value, list):
            for item in value:
                aliases.update(_tokens(item.get("materialId") if isinstance(item, dict) else item))
    alias_matches = [item for item in materials if aliases & set().union(*(_tokens(alias) for alias in item.get("aliases", [])))]
    if len(alias_matches) == 1:
        result = _candidate(alias_matches[0], "alias", float(hypothesis.get("confidence", 0.5)), "unique alias match")
        result["status"] = "proceed" if result["confidence"] >= 0.7 else "probe"
        result["alternatives"] = []
        return result

    family_matches = [item for item in materials if family and _token(item.get("family")) == family]
    family_matches.sort(key=lambda item: str(item.get("id")))
    alternatives = [
        _candidate(item, "family-fallback", max(0.1, float(hypothesis.get("confidence", 0.3)) * 0.65), "family fallback")
        for item in family_matches
    ]
    if len(family_matches) == 1:
        result = alternatives[0]
        result["status"] = "probe"
        result["alternatives"] = []
        return result
    return {
        "materialId": None,
        "profile": None,
        "method": "unresolved",
        "confidence": 0.0,
        "reason": "ambiguous or unknown material; request more evidence",
        "status": "request-input" if family_matches else "unknown",
        "alternatives": alternatives,
    }


def _prior_values(profile: dict[str, Any]) -> dict[str, float]:
    return {
        name: float(value["default"])
        for name, value in profile.get("renderPrior", {}).items()
        if isinstance(value, dict) and isinstance(value.get("default"), (int, float))
    }


def build_assignment(
    hypothesis: dict[str, Any],
    evidence: dict[str, Any] | None = None,
    payload: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Return the spec-ready assignment without mutating the input hypothesis."""
    result = resolve_material(hypothesis, payload)
    profile = result.get("profile")
    assignment: dict[str, Any] = {
        "materialId": result.get("materialId"),
        "status": result["status"],
        "source": hypothesis.get("source", "vision"),
        "confidence": result["confidence"],
        "method": result["method"],
        "alternatives": [item["materialId"] for item in result.get("alternatives", [])],
        "evidence": copy.deepcopy(evidence or {}),
    }
    if profile:
        assignment.update({
            "profileId": profile["id"],
            "family": profile.get("family"),
            "subtype": profile.get("subtype"),
            "finish": profile.get("finish"),
            "renderPrior": _prior_values(profile),
            "requiredMaps": list(profile.get("requiredMaps", [])),
            "optionalMaps": list(profile.get("optionalMaps", [])),
            "validationViews": list(profile.get("validationViews", [])),
            "sourceRefs": list(profile.get("sourceRefs", [])),
            "visualCues": list(profile.get("visualCues", [])),
        })
    return assignment
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: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated 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: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall