layered-holo-card

---
name: layered-holo-card
description: Turn an existing photo or artwork into a layered 2.5D holographic collectible card while preserving its composition and subject pixels. Use for floating subjects, layered photo cards, or 把照片做成主体浮起的全息闪卡; not for redesigning the image or flat whole-card tilt alone.
---

# Layered Holo Card

Preserve the image first. Movement should reveal subtle physical depth; at rest it remains the user's picture. Use this package's pipeline and renderer, not an improvised card frame or another shader.

## Capability check

Required: local filesystem and shell, Python 3.10+ with `requirements.txt`, an image-editing tool that accepts the original image and returns usable files, and a WebGL2 browser for interactive verification. An Agent's support for SKILL.md alone does not supply these capabilities. If one is absent, name it and stop at that stage. Never silently substitute a remote provider, buy credits, or request secrets in chat. No hosted service or provider-specific MCP is required.

Read [pipeline](references/pipeline.md) and [validation](references/validation.md) before processing. Read [layering](references/layering.md) to decide whether an accent is reliable. Use [materials](references/materials.md) and [motion](references/motion.md) when assembling. Resolve all paths relative to this skill's directory, not a developer's machine.

This is v0.1.0 Beta. Read [known limitations](references/known-limitations.md): small silhouette details and translucent boundaries still require visual review. Release readiness does not guarantee successful extraction on every input.

## Fixed workflow

1. Inspect the supplied image with `python scripts/inspect_image.py IMAGE`, then view it. Preserve original bytes, dimensions, EXIF-aware composition, crop, identity, pose, camera, coordinates and RGB. **Never generate a replacement card face, force a ratio, outpaint, beautify, change a face, or complete cropped anatomy.**
2. Identify one main subject. Distinguish real foreground occluders (a phone, bouquet or instrument covering the subject) from accents (decorative/glowing elements). Create extra layers only when depth order and segmentation boundaries are reliable; never split every limb. For occluders read [occlusion-aware parallax](references/occlusion.md). Preserve identity before motion: do not invent hidden facial features, lettering, logos or finger anatomy. A zero extra-motion budget retains a separately inspectable layer, not a fabricated completed face.
3. Using the original as the edit target, request a clean background plate with ALL chosen foreground elements removed and occluded background reconstructed. Independently request one flat chroma extraction source per foreground layer. Use the exact prompt constraints in pipeline.md. Preserve canvas ratio and every subject coordinate. These are auxiliary images, never replacements for original subject colors.
4. Save the returned real files. Use one generation per required asset; do not retry a failed edit without discussing the failure. Do not invent paths. A generated resolution difference may be normalized only with identical aspect ratio, explicitly recorded; never crop or warp an auxiliary to force alignment.
5. Write `request.json` using the documented contract. Run `python scripts/prepare_layers.py request.json --out output`. This invokes our extraction code, verifies alignment and alpha, rejects duplicate/overlapping layers, preserves foreground RGB from the original, and assembles `presentation.json` plus a self-contained `preview/`. Outputs must go into a new directory; never overwrite a previous result.
6. Run `python scripts/validate_layers.py output`. Inspect background, each RGBA layer on light/dark backgrounds, and zero-offset recomposition at full resolution. Reject halos, missing parts, background remnants, changed subject placement or inpainting spill. A green numerical report does not replace visual inspection.
7. Serve the output root with `python -m http.server 4173 --bind 127.0.0.1 --directory output`; open `/preview/`. Test pointer motion, fixed-card mode (internal parallax alone), layer separation, neutral shadows, material below subjects, touch, reduced motion and explicit WebGL errors. The generated preview is the same renderer used by the React adapter. Do not substitute a screenshot for interactive validation.
8. Report files, exact generation prompts, extraction/validation reports, and which live checks were actually run. Declare completion only after a real input-to-preview run. If the browser cannot be inspected, say visual verification is pending. Do not call a failed image a successful flat-card fallback.

## Non-negotiable rendering boundaries

Natural subject contact with edges/corners and high foreground coverage are valid. Never require transparent/background corners or shrink/crop the image to satisfy a mask check. Treat near-full alpha as a diagnostic and judge useful relative motion visually. Structural failures (unreadable assets, wrong canvas/coordinates, empty alpha) remain explicit; numerical validation is not a visual-quality verdict.

All foil/glare/microtexture stays in the background canvas, below every cutout. Observed foreground pixels retain original RGB; never add colored rim light or rainbow skin overlays. Layers are ordered background → optional midground → main → optional foreground_occluder → optional accent. Accent strength is only modestly higher. Occluder motion is constrained by actual unknown-underlay coverage, never a fixed multiplier. Limited, reviewed safe-region fill is permitted with separate provenance; it must never be presented as observed source pixels. Use neutral, low-opacity shadows that change with relative layer height and pointer position, not a heavy fixed drop shadow. Keep whole-card tilt optional so internal depth is independently inspectable.

## Optional tuning without redesign

Read [parameters](references/parameters.md) when a user requests stronger depth, more shimmer, lighter shadows, presets or fine tuning. Omitted parameters preserve the approved default renderer. Use the shared request/presentation contract and existing preview controls, never a replacement shader or regenerated subject. Four effect presets are `default`, `restrained`, `shimmer`, `depth`; reset restores the baseline. Accent controls apply only to actual accent layers. Occluder motion always remains inside measured safety bounds. Adjustment alone requires no image generation.

## Output files

Always emit `original.*`, `background.png`, `subject.png`, optional `foreground-accent.png` / other layer PNGs, `presentation.json`, `validation.json`, `recomposition.png`, `prompts.json` and `preview/`. The browser can export a neutral, flat static `final.png` including foil through the same engine. Original image metadata is preserved in the private output; warn before publishing personal photos.

Only modify an application when explicitly requested. React consumers can use `assets/react-template/HolographicCard.tsx`; it wraps the same dependency-free renderer rather than implementing a second effect. Do not upload to GitHub, change an installed skill, or publish user pictures merely because a card was requested.