threejs-sculpt-dna — A GitHub Copilot Plugin

Turn a reference image into editable Three.js code with GitHub Copilot.

Give Copilot an image and get a plain Three.js factory you can read, diff, refine, animate, and ship. The workflow builds with procedural geometry instead of downloading or hiding an imported mesh.

Try the live model → · See the React Three Fiber runtime → · Star on GitHub →

If image-to-code Three.js work is on your roadmap, star the repository to keep the workflow, examples, and future releases easy to find.

Provenance: the current release combines Sculpt DNA with a reviewed, MIT-licensed upstream modeling kernel. The exact imported scope and commit are recorded in UPSTREAM.md.

Canonical repository: hyeonsangjeon/threejs-sculpt-dna. Use this path for installs, clones, and links.

Install in one command

copilot plugin install hyeonsangjeon/threejs-sculpt-dna

Attach a reference image in a new Copilot session and ask:

Use Three.js Sculpt DNA to rebuild this reference as editable procedural
Three.js code. Keep it action-ready and do not use an imported mesh.

You get: a versioned ObjectSculptSpec, a plain Three.js factory, browser comparison evidence, action-ready runtime maps, and optional deterministic variants. See the complete reconstruction Skill.

Why trust it? Inspect the executable proof and runtime contract

Verified release state

Every release claim below is backed by an executable check, source evidence, or a live runtime. Audit the committed capability-proof.json or run the same proof used by CI.

Verifiable contract	0.6.0 state
Capability contract	11 source-linked claims, including region-aware PBR, self-contained proof, and the optional React Three Fiber runtime
Combined reconstruction surface	modular v4 kernel + adaptive v3.1 + explicit schema-v2 Sculpt DNA compatibility
Python contracts	295 tests, plus 9 React/R3F lifecycle and real-factory contracts
Executable boundary	41 declared scripts, network disabled
Production evidence	3 artifact manifests; Brick 4/4 and Seoul 4/4 family matrices
Reproducible proof	one offline command, 6 fail-closed gates, bounded output plus full-stream/input SHA-256
React runtime	optional peer-only adapter; seed/variant rebuilds, useFrame, nodes, sockets, colliders, destruction groups, stats, exact-once cleanup
Public CI	the same proof command, 6 browser builds, dedicated adapter lifecycle tests, capture/data tests, and dependency audits

Open the live Proof Lab · Read the verified capability matrix · Audit upstream lineage · Use the fair comparison protocol

You provide	The workflow produces
A reference image or URL, intended use, and target project	Suitability verdict, complexity assessment, versioned ObjectSculptSpec, and explicit fidelity limits
Browser feedback during locked sculpt passes	Procedural Three.js factory, generated PBR channels, action-ready runtime maps, comparison evidence, and SHA-bound review history
Optional bounded art-direction controls	Deterministic Sculpt DNA variants, curated family manifest, regression matrix, and host-integration report

5-minute reproducible check

Clone the canonical repository and run the committed public sample through the same tools used by the production flagships:

git clone https://github.com/hyeonsangjeon/threejs-sculpt-dna.git
cd threejs-sculpt-dna

python3 scripts/prove.py

Expected: PROOF PASS: 6/6 checks passed. The runner stays offline and read-only unless --output explicitly names a JSON destination. It checks the executable policy and capability contract, runs the first-clone doctor, compiles every Python surface, executes all contracts, and verifies release evidence. JSON captures are bounded, while SHA-256 digests of the complete streams remain available for integrity checks.

Inspect the committed sample directly

python3 scripts/probe_reference_image.py \
  assets/brick-offroad-reference.jpeg

python3 scripts/validate_sculpt_spec.py \
  examples/repolis-tree/object-sculpt-spec.json \
  --strict-quality

python3 scripts/sculpt_pass_orchestrator.py status \
  examples/repolis-tree/object-sculpt-spec.json

Expected result: the image probe reports "technicalSuitability": "pass", strict validation prints PASS, and the committed flagship reports currentPass: complete.

Then open GitHub Copilot, attach your own reference, and paste:

Use the object-to-threejs-procedural Skill from threejs-sculpt-dna.

Reconstruct this attached reference as a browser-real-time, action-ready
procedural Three.js model. Validate the image, write the assessment and
ObjectSculptSpec, follow the locked sculpt passes, compare browser screenshots,
and keep generated geometry, materials, pivots, sockets, colliders, evidence,
and runtime metadata in the target project. Do not use an imported mesh.

What Makes It Different

• Sculpt DNA controls. Named semantic controls vary proportions, material response, palette, and repetition systems while protecting component identity, attachment roots, sockets, fracture groups, and action-ready topology.
• Coverage Curator. A deterministic centroid-extreme plus greedy max-min heuristic selects a broadly separated representative family from a larger constraint-safe candidate pool.
• Evidence-bound production gates. Every locked sculpt pass requires browser screenshots, full reference/render comparisons, semantic AI-vision review, and local SHA-256 bindings. Stale or overwritten evidence automatically invalidates production readiness.
• Deterministic family regression matrix. Promoted variants and their base are checked in stable asset/viewpoint order with every cell classified as missing, stale, passing, or failing; AI vision remains the final authority.
• Action-ready by construction. Stable pivots, sockets, colliders, constraints, detachable groups, and runtime maps are part of the model contract rather than an animation retrofit.
• Code-native and reproducible. Flagship factories use procedural geometry, generated independent PBR channels, deterministic capture, measured performance budgets, and zero imported meshes.

React Three Fiber Runtime Adapter

Open the live React Three Fiber integration

The optional adapter mounts the same plain Three.js factories as the flagships without replacing or forking their runtime logic. It lives at adapters/react-three-fiber as a workspace/file package. This does not imply an npm registry release.

import { Canvas } from '@react-three/fiber';
import { SculptDNAAsset } from '@threejs-sculpt-dna/react-three-fiber';
import { createBrickOffroad } from './createBrickOffroad.js';

<Canvas>
  <SculptDNAAsset
    factory={createBrickOffroad}
    seed={20260712}
    variant="brick-offroad-v001"
    onReady={(asset) => {
      asset.runtime.nodes['left-door-pivot'].rotation.y = -0.62;
      console.log(asset.runtime.sockets, asset.stats);
    }}
  />
</Canvas>

Committed adapter tests cover React 19 StrictMode, semantic prop changes, frame forwarding, stable runtime identities, and exact-once cleanup. React, R3F, and Three.js remain peer dependencies, so plain Three.js users gain no required runtime dependency.

03 · Flagship: Repolis Living Archive

Open the interactive Repolis Tree demo

_{Built and visually reviewed with GitHub Copilot · GPT-5.6 Sol.}

The flagship is generated entirely in code. The Golden Canopy configuration uses 0 imported meshes, takes approximately 100ms to generate, and contains 17,761 branch vertices, 2,600 instanced leaves, 220 moss instances, and 72 branch-following code glyphs.

The interactive page imports the same reusable output intended for the Repolis application:

• Repolis production factory
• TypeScript declarations
• Runtime profile
• Pass-by-pass visual evidence

How It Was Built

01 Reference → 02 Sculpt DNA variants → 03 Flagship above

01 · Reference	02 · Sculpt DNA variants — intermediate	03 · Flagship — final

The reference establishes the identity contract: monumental Y-shaped trunk, gold energy network, amber/cyan canopy, constellation ornaments, and a luminous night landmark.

The middle contact sheet explores the design space rather than presenting a finished asset. Coverage Curator generated 24 constraint-safe candidates and selected three broadly separated variants while preserving component IDs, parent links, sockets, attachment roots, and review targets. The flagship then received object-specific geometry, PBR, lighting, camera, interaction, optimization, and eight evidence-backed sculpt-pass reviews.

Evidence-backed base spec · Coverage Curator manifest · Variant renderer

Quick Start

1. Install the plugin directly from the canonical repository:

   copilot plugin install hyeonsangjeon/threejs-sculpt-dna

2. Start a new GitHub Copilot session and verify /skills list includes:

   • object-to-threejs-procedural
   • sculpt-dna-variants

3. Attach a reference image and ask Copilot to reconstruct it:

   Use Three.js Sculpt DNA for GitHub Copilot.
   
   Reconstruct this attached reference as a browser-real-time, action-ready
   procedural Three.js model. Follow the locked sculpt passes, review browser
   screenshots, then curate 3 representative variants from 24 safe candidates.
   Do not use an imported mesh.
   

Read the complete user guide for production vs preview variants, prompt templates, updates, uninstalling, and troubleshooting.

Additional Demo Families

Brick and Seoul are now evidence-backed production flagships. Every generated variant resets inherited evidence and must pass a fresh SHA-bound visual review before promotion.

Brick Off-Road Explorer

Open the interactive Brick Off-Road Explorer

Reference → Sculpt DNA variants → Flagship

_{Built and visually reviewed with GitHub Copilot · GPT-5.6 Sol.}

01 · Reference	02 · Sculpt DNA variants — intermediate	03 · Flagship — final

The hard-surface flagship preserves the photographed olive hood, cabin, and rear-body proportions, along with exactly four correctly oriented wheels. The same procedural build includes the light roof, black structure, glazing, arches, suspension, tire treads, studs, fasteners, roof cargo, lamps, and warm recovery hardware. Its three curated configurations pass the base-sculpt and per-variant visual gates while preserving action-ready topology.

The committed installed-Chrome manifest records per-run generation timings. It also records 63,564–68,324 instance-weighted geometry triangles, 126 scene drawables, 387 full-frame WebGL calls including shadow/transmission/output passes, 512px independent PBR channels, and 0 imported meshes.

Evidence-backed base spec · Production variant manifest · Reusable factory · Runtime profile · Pass evidence

Seoul Palace Scene Challenge

Open the interactive Seoul Palace Scene

Reference → Intermediate preview → Flagship

_{Built and visually reviewed with GitHub Copilot · GPT-5.6 Sol.}

01 · Reference crop	02 · Existing intermediate preview	03 · Production flagship

This is intentionally a conditional stylized reconstruction based on one low-resolution aerial image, not photogrammetry or an exact reverse-engineered palace. The production flagship completes all eight locked passes. It reads as an axial campus with outer and inner gates, a main throne hall, curved Korean roof rhythm, broad ceremonial courts, side corridors, tree and city belts, and a custom asymmetric ridge skyline.

The installed-Chrome manifest records 144,472 instance-weighted triangles, 194 scene drawables, 388 full-frame WebGL calls, 2,275 instances, 35 independent 1024px texture fields, one directional shadow map, and 0 imported meshes. The canonical 1200×675 capture is byte-identical across repeated runs. Three fresh evidence-backed variants were curated from 24 candidates with a 0.506961 coverage score while locking the palace axis, gate order, main-hall and roof topology, sockets, pivots, reference camera, and colliders.

Evidence-backed base spec · Production variant manifest · Reusable factory · Runtime profile · Pass evidence

The two camera photos are stored as web-sized JPEGs with GPS, device, and original capture metadata removed.

Run the interactive showcase locally:

cd examples/showcase
npm install
npm run serve

Then open http://127.0.0.1:4173/?scene=tree, replacing tree with brick or seoul.

Open the advanced workflow and technical reference

At A Glance

• Plugin: threejs-sculpt-dna
• Skills: object-to-threejs-procedural and sculpt-dna-variants
• Input: an attached object image, reference screenshot, or local image path
• Output: a procedural Three.js factory, versioned ObjectSculptSpec, deterministic variant family, visual review evidence, and optional host render-integration report
• Best for: real-time props, hard-surface objects, botanical landmarks, product studies, and explicitly layered scene approximations
• Not for: photogrammetry, exact mesh extraction, or guaranteed hidden-side reconstruction from one image

What It Produces

• An image suitability verdict with explicit uncertainty.
• A pre-spec complexity assessment and object-specific quality contract.
• An ObjectSculptSpec describing geometry, materials, evidence, hierarchy, pivots, sockets, colliders, and destruction intent.
• A pass-gated TypeScript Three.js factory with generated PBR maps and look-dev lighting.
• Reference/render comparison sheets and structured AI-vision review history.
• Deterministic Sculpt DNA variant specs with mutation provenance and semantic invariant checks.
• Coverage-curated representative families selected from larger safe candidate pools.
• Versioned standalone/host render snapshots and deterministic integration checks.

It is a code-native reconstruction workflow, not photogrammetry or exact mesh extraction.

Why High-Detail Results Take Multiple Passes

The skill is a disciplined construction workflow rather than a one-click detail filter. High-detail procedural assets combine:

• custom curve-swept geometry with taper, bends, multi-frequency deformation, and enough radial/longitudinal segments for the hero silhouette
• hierarchical macro, secondary, tertiary, and fine components rather than one trunk or shell mesh
• deterministic instancing for leaves, studs, treads, moss, lights, trees, buildings, and other repeated systems
• independent albedo, roughness, height, normal, and AO channels plus object-specific local overrides
• small identity details such as branch collars, end grain, sockets, roof tiers, ground contacts, wear, and ornaments
• browser screenshot review and AI-vision correction after every locked sculpt pass
• batching, instancing, and LOD only after the visual identity has passed

The generated factory is therefore a pass-gated scaffold. Hero quality still requires object-specific form, material, lighting, and optimization work.

Once a detailed base asset defines a safe semantic design space, Coverage Curator greedily broadens parameter-space coverage without changing topology, attachments, action-ready hierarchy, or visual review targets.

Original Sculpt DNA Idea

One reconstructed object can define a reusable asset family. Sculpt DNA exposes carefully selected spec fields as named controls such as:

• body width, height, depth, taper, or bevel radius
• appendage length or radius while preserving the attachment root
• repetition count or density
• material roughness and surface age
• dominant procedural palette choices

Each parameter has a range or choice set, sampling distribution, semantic purpose, and optional coupling group. Constraints reject invalid combinations. Built-in invariants prevent variants from changing the model's semantic topology:

• component IDs and parent links
• material IDs and component material references
• socket IDs and fracture groups
• attachment parent/root sockets and localStart
• build-pass order and feature-review target IDs
• repetition-system IDs

Every generated variant receives a reproducible seed and mutation log. Existing screenshots and pass approvals are cleared because changed geometry or materials must earn fresh visual acceptance.

For a representative family rather than a raw batch:

python3 scripts/sculpt_dna.py curate object-sculpt-spec.json \
  --out-dir curated \
  --count 3 \
  --pool-size 24 \
  --seed 1337

Architecture

reference image
    |
    v
technical probe -> pre-spec assessment -> ObjectSculptSpec
                                          |
                       +------------------+------------------+
                       |                                     |
                       v                                     v
             locked sculpt passes                    Sculpt DNA schema
                       |                                     |
                       v                                     v
             TypeScript factory                     deterministic variants
                       |                                     |
                       +------------------+------------------+
                                          |
                                          v
                         browser render + comparison sheet
                                          |
                                          v
                          AI-vision quality/feature review
                                         |
                                         v
                           optimization + host integration
                                         |
                                         v
                    contract + standalone/host runtime snapshots

Technology Analysis

Layer	Technology	Why it is used
Copilot packaging	Root plugin.json, skill directories, SKILL.md YAML frontmatter	Native GitHub Copilot plugin discovery and task-triggered instructions
Agent workflow	Markdown skills and focused reference documents	Keeps visual reasoning, quality gates, and implementation policy readable and editable
Data contracts	Versioned JSON ObjectSculptSpec plus additive render integration contract/snapshots	Separates observed design intent from generated renderer objects, then verifies that host integration preserves the accepted runtime assumptions
Automation	Python 3.10+ standard library	Portable CLIs with no mandatory package installation
CLI surface	argparse, pathlib, json	Predictable file-oriented commands and machine-readable output
Image probing	Binary header parsing with struct	Reads PNG, JPEG, GIF, WebP, and BMP dimensions without Pillow
PNG/PBR processing	zlib, struct, math, custom RGB/RGBA PNG reader/writer	Generates albedo, roughness, height, normal, and AO evidence without Python image dependencies
Non-PNG fallback	macOS sips, detected with shutil.which	Converts source images when direct PNG decoding is unavailable; other platforms should provide RGB/RGBA PNG input
Three.js generation	Python source generator emitting TypeScript	Produces plain Three.js factories that can be hand-refined in an existing application
Geometry	Shared validation/generation registry for primitives, assemblies, curves, sweeps, lathes, extrusions, lofts, fitted shells, branches, scatter, instancing, modifiers, sculpted surfaces, and specialized regions	Rejects unsupported geometry instead of silently substituting boxes and keeps complex procedural shapes explicit
Materials	MeshPhysicalMaterial, emissive controls, deterministic Canvas textures, independent PBR channels	Keeps bark readable beneath glow, avoids flat-color placeholders, and prevents albedo reuse across unrelated PBR channels
Runtime structure	THREE.Group pivots plus userData.sculptRuntime maps	Keeps nodes, meshes, sockets, collider proxies, and destruction groups addressable for animation and physics
Visual QA	Browser screenshots, custom comparison sheets, semantic feature gates	Makes visual evidence—not code inspection—the acceptance authority
Integration QA	Deterministic renderer/target/layer/view/performance snapshots	Detects host-only rendering regressions without adding a browser runtime dependency or manufacturing an AI pass
Variant engine	copy, SHA-256 seed derivation, random.Random, rejection sampling	Creates reproducible variants and retries samples until constraints pass
Verification	unittest, tempfile, subprocess, compileall, machine-readable proof runs	Tests Python APIs and end-to-end generation, then publishes bounded, hashed evidence without third-party test tools

Dependency Model

The plugin itself has no required PyPI or npm dependencies. Python scripts operate on JSON and images; generated TypeScript expects the target application to already depend on three.

The browser, TypeScript compiler, bundler, and Three.js version belong to the target project. The plugin intentionally does not install Playwright or Chromium solely for screenshots.

Workflow, Script by Script

Script	Responsibility
prove.py	Run the six network-free repository gates and optionally emit a bounded, machine-readable proof result
doctor.py	Run the read-only first-clone health check, including plugin, policy, sample, runtime, duplicate-install, and production-matrix status
audit_script_policy.py	Compare every Python executable with the network-disabled trust inventory in script-policy.json
verify_capability_proof.py	Bind release metadata, upstream provenance, capability claims, evidence files, tests, production matrices, and public CI into one read-only proof
sculpt.py	Provide the unified command surface for the adaptive modular workflow
sculpt_manifest.py / sculpt_modules.py	Manage v4 root manifests and independently authored module specs
sculpt_geometry.py	Share the supported procedural geometry registry between validation and TypeScript generation
sculpt_module_state.py / sculpt_module_review.py	Enforce module reuse, correction batches, multi-view evidence, critical-feature vetoes, and build/runtime receipts
probe_reference_image.py	Detect image format, dimensions, aspect ratio, and basic technical risks
new_pre_spec_assessment.py	Create a complexity assessment and minimum quality contract
new_sculpt_spec.py	Create the versioned ObjectSculptSpec skeleton
validate_sculpt_spec.py	Validate structure, references, quality depth, action readiness, PBR intent, pass state, and Sculpt DNA
sculpt_pass_orchestrator.py	Lock deeper passes until prior visual evidence and reviews succeed
generate_threejs_factory.py	Emit the unlocked TypeScript Three.js factory and look-dev lights
extract_reference_pbr.py	Infer reference-derived PBR evidence from an auto or validated material region and record its source/crop identity
make_visual_comparison_sheet.py	Package reference and render into one AI-reviewable PNG
visual_feature_gate.py	Enforce critical and important semantic feature thresholds
append_sculpt_review.py	Record AI-vision scores, mismatches, evidence, and correction decisions
sculpt_dna.py	Initialize, validate, and generate deterministic constraint-safe variants
sculpt_dna_core.py	Shared DNA schema, target resolver, constraints, invariants, sampling, and provenance
visual_regression_matrix.py	Verify the deterministic base/variant viewpoint matrix against current SHA-bound latest-pass reviews
render_integration_contract.py	Compare a versioned contract with standalone and host runtime snapshots using stable typed checks and explicit exit codes

For a source that contains several materials, select exactly one region in source pixels or normalized coordinates:

python3 scripts/sculpt.py pbr reference.png \
  --out-dir generated/pbr \
  --material-id stone \
  --crop-normalized 0.12 0.18 0.36 0.44 \
  --material-crop-confirmed \
  --url-prefix /textures/stone \
  --report generated/pbr/report.json

Use --crop-pixels X Y WIDTH HEIGHT instead when exact source pixels are known. The extractor rejects conflicting, out-of-bounds, tiny, background-heavy, or high mixed-material-risk regions. Its report and referencePbr patch preserve the requested units, resolved pixel/normalized coordinates, source dimensions, source SHA-256, and deterministic crop identity. Omitting both crop flags keeps the existing automatic foreground path.

Requirements

• GitHub Copilot with plugin support.
• Python 3.10 or newer.
• A Three.js browser project for generated model implementation.
• React 18/19 and React Three Fiber 8/9 only when using the optional adapter.
• A rendered screenshot and AI-vision review for visual acceptance.

For non-PNG source images on platforms without macOS sips, convert the input to an RGB/RGBA PNG before PBR extraction or comparison-sheet generation.

Install

Use exactly one installation source. Current Copilot CLI releases can install directly from the canonical repository:

copilot plugin install hyeonsangjeon/threejs-sculpt-dna
copilot plugin list

Do not also install the same plugin from a marketplace or local path. Duplicate cached copies can shadow one another and make upgrades appear stale. From a cloned checkout, python3 scripts/doctor.py warns when it detects more than one threejs-sculpt-dna installation.

Optional repository marketplace install

The repository also carries a decentralized marketplace manifest for teams that prefer a registered catalog:

copilot plugin marketplace add hyeonsangjeon/threejs-sculpt-dna
copilot plugin install threejs-sculpt-dna@threejs-copilot-plugins
copilot plugin list

Remove a direct or local copy before choosing this source.

Start a new Copilot CLI session, then verify the skills:

/skills list

Copilot caches installed plugins. Contributors using the local-only mode should reinstall that path after modifying the plugin:

copilot plugin install "$(pwd)"

See GitHub's plugin authoring guide and CLI plugin reference.

Base Reconstruction Quick Start

Probe the image:

python3 scripts/probe_reference_image.py ./reference/object.png

Create an assessment and spec:

python3 scripts/new_pre_spec_assessment.py "Reference Object" \
  --image ./reference/object.png \
  --complexity moderate \
  --out assessment.json

python3 scripts/new_sculpt_spec.py "Reference Object" \
  --image ./reference/object.png \
  --assessment assessment.json \
  --out object-sculpt-spec.json

Complete the observed fields and quality contract, then validate:

python3 scripts/validate_sculpt_spec.py object-sculpt-spec.json
python3 scripts/validate_sculpt_spec.py object-sculpt-spec.json --strict-quality

Check the unlocked pass and generate its factory:

python3 scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json
python3 scripts/generate_threejs_factory.py object-sculpt-spec.json \
  --out src/createReferenceObjectModel.ts

Render the model, capture a screenshot, and create the review artifact:

python3 scripts/make_visual_comparison_sheet.py \
  --reference ./reference/object.png \
  --render ./screenshots/object-render.png \
  --out ./screenshots/object-comparison.png \
  --json

After AI-vision review, record the pass:

python3 scripts/append_sculpt_review.py object-sculpt-spec.json \
  --pass-id blockout \
  --fidelity 0.82 \
  --action continue \
  --summary "Silhouette and primary proportions meet the blockout gate." \
  --render-screenshot ./screenshots/object-render.png \
  --comparison-image ./screenshots/object-comparison.png \
  --ai-vision-score 0.82 \
  --layer-scores-json '{"silhouetteProportion":0.84,"componentStructure":0.81,"formDetail":0.76,"materialSurface":0.72,"lightingCamera":0.8}' \
  --feature-reviews-json ./reviews/blockout-features.json \
  --ai-vision-notes "Primary shape passes; meso detail remains deferred." \
  --in-place

Repeat the locked render, comparison, review, and pipeline-sync loop for structural-pass, form-refinement, material-pass, and surface-pass. Production Sculpt DNA generation remains blocked until the evidence-backed reviewHistory completes that sequence.

append_sculpt_review.py SHA-256-binds every local reference, render, and comparison file. Pipeline sync, strict validation, and production variant generation recompute those hashes, so overwriting a reviewed capture invalidates the pass. URL, data, blob, and session-artifact evidence is retained as remote-unverified record-only evidence. It cannot complete a production pass.

Sculpt DNA Quick Start

Initialize conservative starter controls:

python3 scripts/sculpt_dna.py init object-sculpt-spec.json --in-place

Edit sculptDNA.parameters into object-specific controls, then validate both layers:

python3 scripts/sculpt_dna.py validate object-sculpt-spec.json
python3 scripts/validate_sculpt_spec.py object-sculpt-spec.json

After the base sculpt has completed through surface-pass, generate eight production variants:

python3 scripts/sculpt_dna.py generate object-sculpt-spec.json \
  --out-dir ./variants \
  --count 8 \
  --seed 1337

For an early, explicitly non-promotable design-space contact sheet, add --preview. Preview provenance records the missing base passes. Every result remains blocked pending its own visual review:

python3 scripts/sculpt_dna.py curate object-sculpt-spec.json \
  --out-dir ./preview-variants \
  --count 3 \
  --pool-size 24 \
  --seed 1337 \
  --preview

The output directory contains:

variants/
├── <target-id>-v001.json
├── <target-id>-v002.json
├── ...
└── sculpt-dna-manifest.json

Each variant can enter the normal pass-gated factory and screenshot workflow:

python3 scripts/validate_sculpt_spec.py variants/<target-id>-v001.json
python3 scripts/generate_threejs_factory.py variants/<target-id>-v001.json \
  --out src/createSelectedVariantModel.ts

Deterministic visual regression matrix

Add the optional visualRegressionMatrix v1 block to the curated manifest to name required viewpoints, bind each one to an authoritative pass, record expected render/comparison path templates, and select semantic feature reviews. Then verify the base plus every promoted variant:

python3 scripts/visual_regression_matrix.py \
  object-sculpt-spec.json \
  variants/sculpt-dna-manifest.json \
  --out variants/visual-regression-report.json \
  --summary

For a one-off run without manifest configuration, repeat --viewpoint VIEWPOINT_ID=PASS_ID. The report is deterministic: base first, variant IDs and viewpoint IDs sorted, and summary keys ordered as missing, stale, passing, failing. Exit status is 0 only when every cell passes, 1 for a complete but non-passing matrix, and 2 for invalid input.

The matrix reuses strict local SHA-256 evidence checks, latest-per-pass review selection, sculpt-pass completion, layer thresholds, and semantic feature gates. It never converts pixel metrics into visual approval. See the manifest, report, and additive migration schema.

Verify a model inside a host app

A standalone turntable can look correct because rotation eventually reveals every emissive branch. A host app can still hide that branch from a fixed camera, exclude it from a selective bloom layer, place an oversized occlusion proxy in front of it, add a second output transform, or let hero lights spill into the town. Verify the exact standalone and host configurations after optimization and before production acceptance.

Create three JSON files:

1. render-integration-contract.json — stable IDs, renderer policy, required targets/layers/lights/views/semantics, and budgets.
2. standalone-snapshot.json — telemetry captured from the accepted standalone scene.
3. host-snapshot.json — the same telemetry captured inside the host app.

This complete minimal v1 contract is ready to copy and paste for the committed Repolis bindings. Replace its IDs, paths, hashes, and thresholds for your asset:

{
  "schemaVersion": "1.0",
  "kind": "render-integration-contract",
  "contractId": "repolis-host-minimal",
  "asset": {
    "assetId": "repolis-tree",
    "profileId": "repolis-living-archive",
    "source": {
      "path": "examples/repolis-tree/object-sculpt-spec.json",
      "sha256": "9556e708ace61dbd2a4128700e41ec8dac3d0c930f0e85e09cc2915013aa40d8"
    },
    "factory": {
      "path": "examples/repolis-hero/repolis-output/createRepolisHero.js",
      "sha256": "65bd7fc76013ee0f11898174095556d581be64ea8f15e76e090fb8955a17d0e3"
    }
  },
  "renderer": {
    "toneMapping": "ACESFilmicToneMapping",
    "outputColorSpace": "SRGBColorSpace",
    "standaloneExposure": 1.0,
    "maxHostExposureDelta": 0.05,
    "outputPassCount": 1,
    "maxPixelRatio": 2.0
  },
  "renderTargets": [
    {
      "id": "hero-bloom",
      "type": "HalfFloatType",
      "colorSpace": "LinearSRGBColorSpace",
      "depthBuffer": false,
      "minScale": 0.5,
      "maxScale": 1.0,
      "maxPixels": 2073600
    }
  ],
  "selectiveRendering": {
    "layers": [
      {
        "id": "hero-bloom",
        "index": 1,
        "owner": "repolis-hero",
        "requiredMembers": ["hero-emissive"],
        "forbiddenMembers": ["town"]
      }
    ],
    "lights": [
      {
        "id": "hero-energy-light",
        "owner": "repolis-hero",
        "requiredLayers": ["hero"],
        "forbiddenLayers": ["town"],
        "maxTownSpill": 0.01
      }
    ]
  },
  "views": [
    {
      "id": "front",
      "cameraId": "repolis-front",
      "minCoverage": 0.35,
      "maxCoverage": 0.65,
      "minP50Luminance": 0.2,
      "maxP90Luminance": 0.9,
      "requiredSystems": [
        {
          "id": "hero-emissive",
          "mustBeVisible": true,
          "minCoverage": 0.03,
          "minP50Luminance": 0.2
        },
        {
          "id": "hero-occlusion-proxy",
          "mustBeVisible": false,
          "maxCoverage": 0.12
        },
        {
          "id": "town",
          "mustBeVisible": true,
          "minCoverage": 0.18,
          "minP50Luminance": 0.12
        }
      ]
    }
  ],
  "angleConsistency": {
    "viewIds": ["front"],
    "minCoverageToMedian": 0.88,
    "maxP90LuminanceSpread": 0.1,
    "forbidBlackFrames": true,
    "forbidClipping": true
  },
  "townExposure": {
    "semanticSystemId": "town",
    "viewIds": ["front"],
    "maxP50LuminanceDelta": 0.03
  },
  "performance": {
    "maxCalls": 180,
    "maxTriangles": 900000,
    "minFps": 50.0,
    "maxFrameTimeP50Ms": 18.0,
    "maxFrameTimeP95Ms": 25.0,
    "maxDirectionCallsSpread": 20,
    "maxDirectionTrianglesSpread": 100000,
    "maxDirectionFrameTimeP95SpreadMs": 4.0
  },
  "errors": {
    "maxConsoleErrors": 0,
    "maxNetworkErrors": 0
  }
}

Run the three-angle deterministic demonstration directly from the repository root. Its values are illustrative only, not claimed live measurements:

python3 scripts/render_integration_contract.py \
  examples/render-integration-contract/render-integration-contract.json \
  examples/render-integration-contract/standalone-snapshot.json \
  examples/render-integration-contract/host-snapshot.json \
  --out /tmp/integration-report.json \
  --summary

The sample exits 0 and prints this summary to stderr; the full JSON is written to /tmp/integration-report.json:

PASS
checks: total=211 missing=0 stale=0 passing=211 failing=0

Exit 1 means the inputs were valid but at least one check is missing, stale, or failing. Exit 2 means malformed, unsafe, non-finite, unsupported-schema, or identity-inconsistent input. Without --out, the JSON report is printed to stdout.

• tone-mapping-count: the host usually added a second OutputPass or nested composer; keep exactly one output transform.
• town-light-spill: a declared hero light targets the town layer or its measured town contribution exceeds the contract; fix light ownership/layers.
• view-coverage: a fixed host camera, layer mask, clipping plane, or occlusion proxy pushed the hero/view coverage outside its declared range.

Coverage and luminance are diagnostic gates. A passing integration report does not approve visual quality; AI vision remains the final visual authority. See the full v1 schema and browser probe guide and the committed browser-snapshot-helper.js.

Quality Gates

The workflow blocks progress when:

• the reference does not expose enough silhouette or depth information
• the quality contract is too generic for the object
• component hierarchy or attachment contracts are too shallow
• material response is flat, aliased across PBR channels, or unsupported by source evidence
• a future build pass is requested before the current pass receives visual approval
• the global visual score is acceptable but a critical semantic feature fails
• Sculpt DNA targets protected semantic fields
• a variant violates declared constraints or invariants
• a promoted base/variant viewpoint cell is missing, stale, or rejected by AI-vision layer or semantic gates
• a host integration contract reports stale bindings, missing runtime telemetry, renderer/layer/view drift, performance regressions, or runtime errors

Project Layout

plugin.json
skills/
├── object-to-threejs-procedural/
│   ├── SKILL.md
│   └── references/
└── sculpt-dna-variants/
    ├── SKILL.md
    └── references/
scripts/
├── prove.py
├── render_integration_contract.py
├── sculpt_dna.py
├── sculpt_dna_core.py
├── visual_regression_matrix.py
└── ...
examples/
├── proof-lab/
│   └── ...
├── render-integration-contract/
│   ├── render-integration-contract.json
│   ├── standalone-snapshot.json
│   ├── host-snapshot.json
│   └── expected-integration-report.json
└── repolis-tree/
    └── ...
tests/
├── test_render_integration_contract.py
├── test_sculpt_dna.py
└── test_visual_regression_matrix.py

Test

python3 scripts/prove.py --output proof-run.json

The six-gate proof includes compilation and the full test suite. Contracts cover DNA derivation, schema validation, deterministic region-aware PBR extraction, bounded proof output, immutable-target rejection, deterministic generation, evidence reset, manifest output, matrix ordering/classification/latest-review precedence, render-integration safety/classification/cwd determinism, generated TypeScript metadata, release-image dimensions, file-size budgets, EXIF removal, and inherited-asset exclusion.

Limitations

• One image cannot reveal exact hidden geometry or manufacturing dimensions.
• PBR extraction is evidence-driven inference, not exact inverse rendering.
• Transparent glass, smoke, liquids, fur, and fine cloth may require more references or a reduced target.
• Complex generated primitives such as lathe, tube, curve sweep, extrude, and instanced clusters still require object-specific hand refinement.
• Variant constraints protect declared semantics, but visual acceptance still requires fresh browser evidence.

Reference

• Vinh Hiển's MIT-licensed Three.js Object Sculptor

License

MIT