image-replicator

name: image-replicator description: The render→score→iterate loop for reference-photo reconstruction. How to invoke kernelcad render, run scoreAgainstReference, interpret per-gate numbers, and decide which gate to chase next.

image-replicator

Purpose

After the blockout is plausible, this sub-skill drives the detail pass. Each iteration produces a render, runs the scorer, and returns a concrete decision: which gate is weakest, what model change closes it, whether to continue or stop.

Inputs

• The .kcad.ts file with a clean blockout.
• The reference photo path.
• Current scorer output (or "not yet run" on the first pass).

The iteration loop

Step 1 — Render

Always render all four canonical views at the correct resolution:

kernelcad render build.kcad.ts \
  --width 1920 --height 1080 \
  --views front,right,top,iso \
  -o /tmp/render.png

Read the PNG back. Filenames are not evidence — you must observe the image.

Step 2 — Score

kernelcad score build.kcad.ts \
  --reference ./reference.jpg \
  --view front \
  --json

The scorer returns a JSON object with per-gate values:

{
  "silhouette": 0.71,
  "ssim": 0.28,
  "phash": 0.62,
  "overall": 0.54
}

Score all views that have a reference. If the task harness provides a harness.ts, run it directly — it wraps scoreAgainstReference with the correct thresholds:

npx ts-node eval/tasks/taskNN/harness.ts

Step 3 — Diagnose which gate to chase next

Read the per-gate numbers and decide:

Chase the lowest gate first. A 0.20 silhouette score means the silhouette is wrong — fixing the SSIM first will not help because the silhouette mismatch dominates overall score.

If silhouette is ≥ 0.45 but SSIM is < 0.25, the outline is correct but the internal structure, depth, or material is wrong. The most common causes:

1. Material is flat color instead of PBR gloss → apply Rule 6.
2. Body depth is too thin (looks like a card) → increase bodyDepth param.
3. Missing internal structure (lens recess, bezel step) → add booleans.

Step 4 — Make one targeted change per iteration

Each iteration makes ONE primary change and re-renders. Do not make multiple changes and then wonder which one moved the score. Candidates in priority order:

1. Correct a failing silhouette gate → fix path outline or primary mass.
2. Apply PBR material if not yet done → Rule 6.
3. Correct body depth from a slab to a real solid → Rule 3.
4. Apply variable fillet where visible corners differ → Rule 1.
5. Apply mirror if one side is authored twice → Rule 2.
6. Add missing sub-component (lens, hinge, crown, etc.).
7. Refine a sub-component position or scale.

Step 5 — Decide: continue or stop

Continue iterating if:

• Any required score gate is below threshold (task-specific; default silhouette ≥ 0.45, SSIM ≥ 0.25).
• A visible defect in the render maps to a fix that has not been applied.

Stop and report when:

• All required gates are at or above threshold.
• Or the hard iteration cap (8 passes) is reached — report which gates remain below threshold and stop; do not restart the counter silently.

Policy: SSIM and silhouette are selectors, not reward targets

SSIM and silhouette IoU are selectors and gates only — use them to pick the better of two candidates and to gate "is this even the right object," never as a quantity to iteratively maximize. They are gameable: a past run inflated body depth into a featureless slab and scored top on silhouette IoU while producing an object with no lens openings at all — geometrically not eyewear. Pixel similarity decoupled from the real goal.

Therefore:

• Fidelity gates AND before any visual score. Before the silhouette/SSIM numbers count, the build must pass boolean fidelity gates (the expected distinctive feature is visible at the pose — e.g. lens openings; the parts count matches; the solid is non-degenerate). If any fidelity gate fails, the visual scored items are forced to fail regardless of how high the pixel similarity is.
• When a reference 3D model (reference.stl) exists, the deterministic 3D geometry oracle is the primary signal (chamfer distance, bbox IoU). SSIM and silhouette are supplementary only.
• When there is no reference 3D model, a VLM rubric judge is the qualitative signal — scored against an explicit per-criterion rubric of the distinctive features, at temperature 0 for repeatability. SSIM/silhouette remain selectors.
• Never iterate to climb SSIM or silhouette for its own sake. If those numbers rise while the distinctive features regress, you are gaming the metric. Chase the feature, not the score.

Iteration discipline

• Never edit a gate to loosen the threshold. If the threshold seems wrong, stop and surface the evidence to the user.
• SSIM/silhouette are selectors, not reward targets (see the policy section above). Fidelity gates AND before any visual score; never iterate to climb a pixel-similarity number while distinctive features regress.
• Commit per score, not per change. Evaluate and score after every geometry change; never accumulate multiple changes and score once.
• Read PNGs back. The render command writes a file; the file is not evidence until you read it. Run the read tool on the output path.
• Do not mark a gate passing based on prose. The number from the scorer is the gate value. "It looks roughly right" is not a passing gate.

Done

The iteration loop is done when all required gates are above threshold AND kernelcad evaluate exits clean AND kernelcad interference reports zero pairs.

Proceed to render-inspect/SKILL.md if any iteration produces diagnostic hints that need interpretation.