model-selection.md

skills/topaz-prepress/references/model-selection.md

1. # Model selection reference
3. How the prep engine routes an image to a Topaz Gigapixel model, what each feature means, and
4. when to override the automatic call by eye. Read this when a recommendation looks wrong or the
5. user asks why a model was chosen.
7. ## Features measured (`analyze()`)
9. | Feature | Meaning | Reads as |
10. |---|---|---|
11. | `uniq` | raw unique opaque colors | low (<200) = clean indexed/vector logo |
12. | `uniqq` | colors after quantizing to 32 levels/channel | collapses JPEG/AA near-duplicates; reflects the *real* palette |
13. | `flat` | uniq ÷ opaque-pixel count | high (>0.15) on a small image = jaggy AA = genuinely low-res |
14. | `edge` | mean absolute luminance gradient | high = lots of edges (text, linework, detail) |
15. | `hf` | high-frequency energy (image minus slight blur) | low on a *large* image = soft = possible false resolution |
16. | `blk` | step magnitude on the 8px DCT grid vs everywhere | >1.1 hints at JPEG block artifacts |
17. | `transp` / `semi` | fraction not fully opaque / soft-edged | drives alpha split + defringe |
19. ## Routing table (`classify()`)
21. Rules are evaluated in order; the first match wins.
23. | # | Condition | Category | Model (alt) | Key settings |
24. |---|---|---|---|---|
25. | 1 | `px < 90k` AND `flat > 0.15` | Low-res / degraded | **Wonder 3** (Low Resolution 2) | generative; no Python sharpen |
26. | 2 | JPEG, `edge > 0.03` | Detailed line art (JPEG) | **Art & CG** (Standard) | Fix Compression On |
27. | 3 | JPEG, else | Flat logo (JPEG) | **Art & CG** (Standard) | Fix Compression On |
28. | 4 | `uniq < 200` | Flat vector logo | **Text & Shapes** (Art & CG) | Fix Compression Off |
29. | 5 | `px > 300k` AND `uniqq > 700` | Detailed illustration | **Standard** (Art & CG) | true-to-input |
30. | 6 | else | Gradient / rendered logo | **Art & CG** (Standard) | keeps gradients + clean edges |
32. Independent of category:
33. - **Fix Compression**: On (Medium) for any JPEG source, Off otherwise.
34. - **Denoise / Sharpen**: Off by default. Denoise Low only if grain survives Fix Compression.
35. Never sharpen in the pre-pass; the model owns edges.
36. - **Face Recovery**: Off. Skull marks and mascot figures are stylized, not real faces, and
37. Face Recovery will distort them.
38. - **Pre-downscaling**: flagged Low-Medium when `min_side ≥ 600` and `hf < 0.012` (large but
39. soft). Recommend Topaz's own toggle, or re-run with `--predownscale` to bake it in.
40. - **Color space**: preserve input; export Adobe RGB if the file is going into CMYK prepress.
41. Do not rely on Topaz's single SWOP CMYK profile for dye-sub/large-format, convert in prepress.
43. ## When to override by eye
45. The classifier routes from statistics and can't see *meaning*. Override when the image tells
46. you something the numbers don't:
48. - **Flat vector defaulted to Text & Shapes, but it's emblem/illustration-dominant** (a badge,
49. a mascot, a crest with little lettering): switch to **Art & CG**. Text & Shapes is for pieces
50. that are mostly type and geometry.
51. - **A "gradient/rendered" logo is actually a photograph or photoreal render**: consider
52. **Standard** or **High Fidelity 3** instead of Art & CG.
53. - **A flat JPEG is extremely soft and large** (text edges mushy): pre-downscale first
54. (`--predownscale`) so Fix Compression + Art & CG have concentrated pixels to work from.
55. - **Degraded route (Wonder 3) over-invents detail** on a recognizable mark: fall back to the
56. alternate (Low Resolution 2), which reconstructs less aggressively and stays closer to source.
58. ## Print sizing logic
60. The report's "Print reach" lines come from the source dimensions × Topaz's 6x ceiling, divided
61. by viewing-distance PPI: 150 PPI for close viewing (≤6 ft), 100 PPI standing (~10 ft), 60 PPI
62. distant (≥20 ft). These follow Topaz's own viewing-distance guidance (closer needs more PPI).
63. Use them to tell a client whether a small source can actually reach the banner size they want,
64. before committing to the upscale.