SKILL.md

skills/topaz-prepress/SKILL.md

1. ---
2. name: topaz-prepress
3. description: >
4. Analyze low-resolution or undersized raster images (logos, graphics, scans, photos) and
5. prep them for a Topaz Gigapixel upscale, then return the prepped files in a zip plus a
6. markdown report recommending the optimal Topaz model and settings for each image. Use this
7. skill whenever the user hands over one or more images that need upscaling, enlarging,
8. "cleaning up for print," "prepping for Topaz," "making bigger," or fixing low resolution
9. for banners, signage, or large-format output, even if they don't say "Topaz" by name. Also
10. trigger on phrases like "this logo is too small," "client sent a tiny file," "get this
11. ready to upscale," "prep these for Gigapixel," "what Topaz settings for this," or any batch
12. of logos/artwork dropped in with the goal of enlarging them. Handles PNG, JPEG, WebP, BMP,
13. and TIFF, including transparent logos (splits and defringes the alpha so edges don't halo).
14. ---
16. # Topaz Pre-Pass
18. Takes raster images that are headed for a Topaz Gigapixel upscale and does two jobs: it
19. **preps** each file so Topaz starts from a clean signal, and it **recommends** the right
20. Topaz model and settings per image. Output is a zip of prepped files plus a markdown report.
22. ## The core principle (do not violate it)
24. Topaz works best on the **original signal**. Do not pre-sharpen, pre-denoise, or "enhance"
25. in Python before Topaz, that destroys the detail Topaz reconstructs from and double-stacks
26. with Topaz's own denoise/sharpen. Python's only legitimate pre-pass jobs are **structure and
27. format hygiene** and **routing**:
29. - Normalize color mode (indexed/palette, grayscale, CMYK, JPEG) to a clean RGB/RGBA working file.
30. - Re-save lossless PNG so no further generational loss happens (critical for JPEG sources).
31. - For transparent logos: split the alpha into a separate mask and **defringe** the RGB
32. (extend edge color into transparent areas) so the upscale doesn't pull a halo into the edges.
33. - Optionally pre-downscale a *false-resolution* image (inflated size, no real detail) so Topaz
34. upscales from concentrated pixels. This is opt-in, never automatic, because misjudging it
35. throws away real detail.
37. If you find yourself wanting to sharpen or denoise the pixels, stop. That is Topaz's job.
39. ## Workflow
41. 1. **Locate the inputs.** Images the user uploaded live in `/mnt/user-data/uploads`. You can
42. pass that directory directly, or individual file paths.
43. 2. **Install deps if needed:** `pip install pillow numpy scipy --break-system-packages -q`
44. (scipy is only used for the alpha defringe; the script degrades gracefully without it).
45. 3. **Run the engine:**
46. ```bash
47. python scripts/prep.py /mnt/user-data/uploads --out /mnt/user-data/outputs/topaz-prep
48. ```
49. Add `--predownscale` only if the user wants false-resolution images downscaled before
50. upscaling (the report flags which images qualify). Use `--zip-name NAME.zip` to rename
51. the archive.
52. 4. **The script writes**, into the `--out` directory:
53. - `*__RGB.png`: the file(s) to load into Topaz.
54. - `*__ALPHA.png`: the transparency mask, only for images that had real transparency.
55. - `Topaz-Prep-Report.md`: the per-image model + settings report.
56. - `analysis.json`: machine-readable metrics and recommendations.
57. - the zip (prepped images + report).
58. 5. **Deliver:** call `present_files` on the **zip** and the **report**. Present the report as
59. the markdown artifact the user reads; the zip is what they download. Keep your chat summary
60. short, the report carries the detail. Flag any image where you'd override the script's
61. automatic call (e.g. you can see it's an emblem, so Art & CG beats the defaulted Text &
62. Shapes). The script routes from measurable features and is right most of the time, but your
63. eyes on the actual image are the tiebreaker, say so when you disagree with it.
65. ## How routing works
67. The script classifies each image from features it measures (color count and flatness, edge
68. density, high-frequency energy vs pixel size, JPEG blockiness, alpha coverage) into one of:
69. flat vector logo, gradient/rendered logo, detailed illustration, low-res/degraded, or a JPEG
70. variant. Each maps to a primary Topaz model, an alternate, and a settings block. The full
71. routing table, with the reasoning and the override cases, is in
72. `references/model-selection.md`. Read it when a recommendation looks off or the user asks why.
74. ## Recompositing transparent logos
76. When the script splits a logo into `__RGB` and `__ALPHA`, the user upscales **both** by the
77. **same** factor in Topaz (RGB with its recommended model, ALPHA with Standard and denoise off),
78. then loads the upscaled alpha as a layer mask on the upscaled RGB in Photoshop. The report
79. spells this out per image. This is what keeps a transparent logo's edges clean at banner size
80. instead of fringed.
82. ## Scope
84. This skill preps and recommends; it does not run Topaz (Topaz is a desktop GUI app). It will
85. not invent detail or fake an upscale in Python. If asked to actually upscale, explain that the
86. upscale happens in Topaz with the prepped files and supplied settings.