Skip to content
Back to search

holo-card

A Codex skill for layered holographic cards with parallax, contour glow, and an optional API workflow

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lersent001--holo-card/badge.svg)](/listings/lersent001--holo-card)

HTML

<a href="/listings/lersent001--holo-card"><img src="/api/listings/lersent001--holo-card/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

After installing, start a new Codex task, **attach your card image**, and send:

$holo-card Turn this image into an interactive holographic card.

Chinese prompt (also supported):

$holo-card 把这张图做成光栅卡

`$holo-card` invokes the installed skill. Attach the actual image in the same task. If it is not found, check `~/.codex/skills/holo-card/SKILL.md` and start a fresh task. Installation instructions follow.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Holo Card
  2. A Codex skill and optional local API service for turning supplied artwork into interactive holographic cards with foreground parallax, a moving background, and adjustable contour glow.
  3. **Creative inspiration: @乌托邦的香蕉 — the same handle on Xiaohongshu (小红书) and Bilibili (B站).** This project is an independent implementation; attribution does not imply endorsement.
  4. ## Demo
  5. [![Watch the holographic card demo](docs/demo-preview.jpg)](https://github.com/LerSent001/holo-card/blob/main/docs/demo.mp4)
  6. [Watch or download the demo recording](https://github.com/LerSent001/holo-card/raw/refs/heads/main/docs/demo.mp4). The recording is a user-provided demonstration; artwork belongs to its respective owners.
  7. ## Quick start: trigger the skill
  8. After installing, start a new Codex task, **attach your card image**, and send:
  9. ```text
  10. $holo-card Turn this image into an interactive holographic card.
  11. ```
  12. Chinese prompt (also supported):
  13. ```text
  14. $holo-card 把这张图做成光栅卡
  15. ```
  16. `$holo-card` invokes the installed skill. Attach the actual image in the same task. If it is not found, check `~/.codex/skills/holo-card/SKILL.md` and start a fresh task. Installation instructions follow.
  17. ## Install the skill
  18. Use the [current installation package](https://github.com/LerSent001/holo-card/releases/latest/download/holo-card.zip), or clone the current main branch (update an existing clone with `git pull --ff-only`):
  19. ```sh
  20. git clone https://github.com/LerSent001/holo-card.git
  21. python3 holo-card/scripts/install-skill.py
  22. python3 -m pip install Pillow
  23. ```
  24. The installer replaces the existing `holo-card` package, removes obsolete packaged files, and verifies every installed file. It does not create nested skill directories or retain discoverable backup versions. Treat the installation as managed files; keep your own card outputs elsewhere. Run the same installer after pulling updates. Start a fresh Codex task after installation so already-loaded instructions are refreshed. Attach your image and ask:
  25. ```text
  26. $holo-card Turn this image into an interactive holographic card.
  27. ```
  28. Codex uses its built-in image tool; no Gemini key or API server is required. The runtime must provide image generation, Python/Pillow, filesystem access and a browser preview. Availability depends on your Codex environment.
  29. ## What happens
  30. 1. Save the original and normalize orientation without cropping.
  31. 2. Generate a continuous colored foreground, repairing artwork hidden by lettering.
  32. 3. Reconstruct a complete opaque background, including areas hidden by the foreground and border.
  33. 4. Extract text, symbols and the decorative frame together as one colored UI layer.
  34. 5. Expect colored checkerboard-matte outputs, prepare their local alpha masks, and repair only confirmed matte regions; do not mask every element or erase white artwork globally.
  35. 6. Generate aligned structural contours, assemble an offline HTML card and ZIP, and inspect the result in a local browser.
  36. The local helper does not generate or segment images by itself. It saves jobs, validates/imports layers, optionally applies a supplied alpha correction and assembles them. Source pixels hidden by overlays cannot be recovered exactly; inpainting is an approximation. Generated lettering, shape alignment and alpha edges still need visual review.
  37. ## Controls
  38. - Drag to rotate; click or press Enter/Space to flip.
  39. - Arrow keys adjust the card angle.
  40. - **Depth:** -3 to +3, default 0 at the center. Negative/positive changes foreground parallax direction. Text and frame always remain above the foreground.
  41. - **Contour glow:** 0 to 3, default 0.15. Zero disables contour light. Emission and bloom are restricted to structural contour coverage; glow does not spill into the background.
  42. - Background texture moves independently of the card's CSS rotation.
  43. ## Local commands
  44. ```sh
  45. python3 skills/holo-card/scripts/native.py prepare --source /path/card.png --output /path/new-job --name 'My Card'
  46. # Use the native image tool, inspect its outputs, then import each layer:
  47. python3 skills/holo-card/scripts/native.py add --job /path/new-job --kind character --image /path/character.png
  48. # Repeat for background, ui and structure.
  49. python3 skills/holo-card/scripts/native.py assemble --job /path/new-job
  50. python3 -m http.server 8795 --bind 127.0.0.1 --directory /path/new-job
  51. ```
  52. Open the loopback URL printed by your server. `index.html` is also self-contained for offline use. `card.zip` contains the HTML, layers and provenance. Use `status --job ...` before reading a saved job’s prompts: it refreshes them from the current helper. Old mask-only native jobs are rejected instead of silently using legacy extraction. Successful assembly is not proof of visual fidelity.
  53. ## Edge cases
  54. | Situation | Handling |
  55. | --- | --- |
  56. | Native image safety refusal | Stop the refused generation and record the error. Do not rephrase or switch providers to bypass it. Contact provider support for an apparent false positive, or use different permitted material. |
  57. | No native image capability | An independently selected API workflow is available; see below. This is not a safety-refusal bypass. |
  58. | Baked checkerboard instead of Alpha | Inspect alpha values, then clean only confirmed contaminated background regions. Protect white clothing, highlights and glyphs. Local code does not automatically solve this. |
  59. | Existing valid transparency | Preserve it; no additional full-element mask is needed. |
  60. | Text overlaps foreground | Remove it from the foreground and repair underlying artwork. Keep typography only in the combined UI layer. |
  61. | Frame and text overlap | Keep both in one UI layer, above the foreground at every depth. |
  62. | Missing background | Inpaint the full opaque plate before parallax. No holes or retained glyphs. |
  63. | Layer moved or changed scale | Align explicitly or reject it. Do not silently crop/stretch or claim an exact extraction. |
  64. | Glow obscures details | Reduce glow and inspect without emission; fix alignment rather than hiding defects. |
  65. | Paid API timeout or uncertain submission | Reuse the existing idempotency key and inspect status. Never automatically start another paid job. |
  66. ## Optional API service
  67. [API setup](packages/holo-card-api/README.md) · [Agent/client workflow](skills/holo-card/references/api.md) · [OpenAPI](packages/holo-card-api/openapi.json)
  68. The service requires Node.js 24+, pnpm, a provider key and explicit paid-call authorization. Keep keys in private local files, not chat or generated artifacts. Configuration and upload do not start generation. It binds to loopback by default; no hosted endpoint is supplied.
  69. **Current limitation:** the API uses legacy four-mask extraction and does not implement the native colored-layer inpainting workflow. Its tests use a mock provider; they do not prove live provider availability, billing, or visual quality. Do not treat it as an automatic fallback for a native refusal.
  70. ## Verification
  71. ```sh
  72. python3 -m unittest discover -s skills/holo-card/tests
  73. cd packages/holo-card-api
  74. pnpm install --frozen-lockfile
  75. node --test test/*.test.mjs
  76. ```
  77. ## Scope and rights
  78. The package contains code and a navy-and-gold card back generated from a user-supplied visual reference. See the bundled artwork notice for provenance and rights. Source card images, credentials, caches and job histories are excluded; the user-provided demo recording is included. Use artwork you are entitled to process and share. This is a layered 2D parallax renderer, not reconstructed 3D geometry. The project is provided under the MIT license; third-party dependencies retain their own licenses.
  79. ## Mobile preview and immersive mode
  80. Generated cards support touch dragging, tap-to-flip, optional motion controls, and recentering. Enable motion requests browser permission on supported phones; device orientation is preferred, with gravity-based tilt as a fallback. Depth and contour glow remain independent on each device. The eye icon at the top right hides the controls and enlarges the centered card; tap it again or press Escape to exit.
  81. Motion requires a secure browser context. Host the generated HTML at an HTTPS URL, or use an account-free temporary HTTPS tunnel to your local preview server. No OpenAI login is required by the viewer itself; authentication depends on the chosen host. Temporary tunnels require the local computer and preview server to remain online.
  82. For a phone-preview QR entry, install the optional Python `qrcode` dependency and assemble with the actual destination URL:
  83. ```sh
  84. python3 -m pip install qrcode
  85. python3 skills/holo-card/scripts/native.py assemble --job /path/to/card-job --preview-url https://your-preview.example/card
  86. ```
  87. Upload the resulting HTML to that same URL. This command embeds the link and QR code; it does not provision hosting. Phone/browser permission behavior still needs real-device validation.
  88. ### Native matte handling
  89. Native image generation is not required to return an alpha channel. Character/UI images on a checkerboard matte enter a local mask-preparation stage. The importer saves opaque inputs as `needs_alpha_mask` with a next action, rather than treating missing alpha as a terminal failure. Prepare a spatially verified grayscale mask and use `apply-alpha` to continue. The helper does not infer the mask automatically. Inspect color layers with glow disabled; reject duplicated subjects in the background and text/scenery in the structural contour layer.
  90. ## Matte region repair
  91. The skill includes a [matte selection procedure](skills/holo-card/references/layer-repair.md) and a Pillow-only seeded-region helper. It removes only explicitly selected candidate components, respects protected artwork, preserves detached foreground details and existing alpha, and uses no example-card coordinates. Candidate identification and soft-edge refinement still require visual inspection. This update does not resolve generated geometry drift, fine-text fidelity, contour alignment or the missing all-effects-off inspection control.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.