image-layer-alignment-validator

name

image-layer-alignment-validator

description

Validate whether two raster image layers are suitable for reveal, before/after, morph, mask-compositing, or interactive cursor reveal effects. Use when comparing base/reveal images, checking whether the main subject stayed in the same position, separating primary subject drift from background or secondary-object differences, producing annotated overlays/difference maps, or deciding whether an image layer must be shifted, scaled, cropped, or regenerated before frontend compositing.

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 scripts/compare_layers.py \
     --base /path/to/base.png \
     --reveal /path/to/reveal.png \
     --out /path/to/alignment-output
   

4. Inspect the generated artifacts before giving a verdict. The script is a deterministic foreground/geometry heuristic; semantic judgment still matters.

5. If the main subject is ambiguous, read references/subject-taxonomy.md and state the chosen primary subject explicitly.

6. Score alignment with references/alignment-rubric.md.

7. 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.