image-layer-alignment-validator

Image Layer Alignment Validator

Use this skill to check whether two image layers can be composited as the same scene or subject. The goal is not generic image critique; the goal is to decide whether a base layer and reveal layer are spatially compatible.

Modes

• compare: analyze two local image files and produce visual/report artifacts.
• diagnose: inspect an existing report or screenshots and explain why a reveal/morph looks misaligned.
• advise: convert measured drift into concrete fixes: shift, scale, crop, regenerate, or accept.
• threshold: tune acceptance thresholds for strict product/portrait work versus looser creative reveal effects.

Workflow

1. Confirm there are exactly two intended layers: base and reveal/after.
2. Keep all analysis local by default. Do not upload private images to external services unless the user explicitly requests that.
3. Run scripts/compare_layers.py when local image paths are available:

   python3 $CODEX_SKILLS_DIR/image-layer-alignment-validator/scripts/compare_layers.py \
     --base /path/to/base.png \
     --reveal /path/to/reveal.png \
     --out /path/to/alignment-output

1. Inspect the generated artifacts before giving a verdict. The script is a deterministic foreground/geometry heuristic; semantic judgment still matters.
2. If the main subject is ambiguous, read references/subject-taxonomy.md and state the chosen primary subject explicitly.
3. Score alignment with references/alignment-rubric.md.
4. Report measured drift and a concrete next action.

Evidence Artifacts

The comparison script writes:

• alignment-report.md: human-readable metrics, verdict, and suggested fixes.
• alignment-metrics.json: machine-readable dimensions, boxes, drift, IoU, and verdict.
• annotated-base.png: detected primary and secondary boxes on the base layer.
• annotated-reveal.png: detected primary and secondary boxes on the reveal layer.
• side-by-side.png: visual comparison with boxes.
• overlay.png: reveal blended over base for quick inspection.
• difference.png: amplified pixel difference map.

Decision Rules

• Treat the measured primary subject box as evidence, not truth. Override it when visual inspection clearly finds a different main object.
• Prefer normalized measurements for verdicts so different canvas sizes are comparable.
• For cursor reveal or mask reveal, the main subject should usually be stricter than the background. Background, lighting, texture, and small accessory differences can change without failing the pair.
• If the subject center drift is visible in the intended reveal area, recommend image correction before frontend work.
• If the reveal image is a genuinely different subject, do not try to hide it with CSS/canvas tuning.

Safety And Privacy

• Process local images locally by default.
• Do not upload private, client, face, identity, or unpublished creative images to external services unless the user explicitly requests that route.
• Do not overwrite source images. Write reports and derived artifacts to a separate output directory.
• When recommending regeneration, describe the intended geometry constraints instead of embedding private image details into reusable skill files.

Validation And Eval

• Validate the script with representative pairs before trusting new thresholds.
• Check alignment-report.md and at least one visual artifact before returning a verdict.
• Treat inconclusive as a valid outcome when foreground detection fails.
• For strict effects, re-run the script after any shift, crop, scale, or regeneration step.
• Forward-test the skill with examples that include aligned pairs, small subject drift, different canvas sizes, and unrelated reveal subjects.

Output Format

Return:

Verdict: aligned | minor drift | misaligned | different subject | inconclusive

Evidence:
- Primary subject: ...
- Center drift: ... px (... normalized)
- BBox IoU: ...
- Scale delta: ...
- Secondary-object notes: ...

Action:
- ...

Artifacts:
- /absolute/path/alignment-report.md
- /absolute/path/side-by-side.png
- /absolute/path/overlay.png

Resources

• Read references/subject-taxonomy.md when deciding what counts as the primary subject versus secondary objects.
• Read references/alignment-rubric.md when grading output or tuning thresholds.
• Use scripts/compare_layers.py for local deterministic evidence.