prep.py

skills/topaz-prepress/scripts/prep.py

1. #!/usr/bin/env python3
2. """
3. Topaz pre-pass prepper.
5. Analyzes raster logos/images, does NON-DESTRUCTIVE prep that genuinely helps a
6. Topaz Gigapixel upscale (mode normalization, alpha split + defringe, lossless
7. re-save, optional false-resolution pre-downscale), and writes a per-image
8. recommendation report for which Topaz model + settings to use.
10. Design rule: Topaz wants clean ORIGINAL signal. We do not pre-sharpen or
11. pre-denoise here -- that destroys the detail Topaz relies on and double-stacks
12. with Topaz's own processing. Python's job is structure/format hygiene + routing.
14. Usage:
15. python prep.py INPUT [INPUT ...] --out OUTDIR [--predownscale] [--zip-name NAME]
16. INPUT may be image files or directories (directories are scanned non-recursively).
17. """
18. import argparse, os, sys, glob, json, zipfile, datetime
19. from PIL import Image, ImageFilter
20. import numpy as np
22. Image.MAX_IMAGE_PIXELS = None
23. EXTS = ('.png', '.jpg', '.jpeg', '.webp', '.bmp', '.tif', '.tiff')
25. # ----------------------------------------------------------------------------- analysis
26. def analyze(path):
27. im = Image.open(path)
28. fmt = (im.format or os.path.splitext(path)[1].lstrip('.')).upper()
29. src_mode = im.mode
30. is_jpeg = fmt in ('JPEG', 'JPG')
31. declared_alpha = src_mode in ('RGBA', 'LA', 'PA') or 'transparency' in im.info
33. rgba = im.convert('RGBA')
34. arr = np.asarray(rgba)
35. a = arr[..., 3]
36. w, h = im.size
37. px = w * h
38. min_side = min(w, h)
40. transp = float((a < 250).mean()) # fraction not fully opaque
41. semi = float(((a > 10) & (a < 245)).mean()) # genuine soft/AA edges
42. has_alpha = declared_alpha and transp > 0.01
44. op = arr[a > 200][:, :3]
45. n_op = max(len(op), 1)
46. uniq = int(len(np.unique(op.reshape(-1, 3), axis=0))) if len(op) else 0
47. flat = uniq / n_op # high => few opaque px each unique (small/jaggy)
48. # quantized color count: collapses JPEG/AA near-duplicates so it reflects real palette
49. if len(op):
50. q = (op >> 3) << 3
51. uniqq = int(len(np.unique(q.reshape(-1, 3), axis=0)))
52. else:
53. uniqq = 0
55. g = rgba.convert('L')
56. L = np.asarray(g).astype(np.float32)
57. gx = np.abs(np.diff(L, axis=1)); gy = np.abs(np.diff(L, axis=0))
58. edge = float((gx.mean() + gy.mean()) / 2 / 255)
59. blur = np.asarray(g.filter(ImageFilter.GaussianBlur(1.0))).astype(np.float32)
60. hf = float(np.abs(L - blur).mean() / 255) # high-freq energy; low+big => soft/false-res
62. # jpeg blockiness: step magnitude on the 8px DCT grid vs everywhere
63. if L.shape[1] > 16:
64. d = np.abs(np.diff(L, axis=1))
65. blk = float(d[:, 7::8].mean() / (d.mean() + 1e-6))
66. else:
67. blk = 1.0
69. return dict(file=os.path.basename(path), path=path, fmt=fmt, src_mode=src_mode,
70. w=w, h=h, px=px, min_side=min_side, is_jpeg=is_jpeg,
71. has_alpha=has_alpha, transp=round(transp, 3), semi=round(semi, 4),
72. uniq=uniq, uniqq=uniqq, flat=round(flat, 4), edge=round(edge, 4),
73. hf=round(hf, 4), blk=round(blk, 2))
76. # ----------------------------------------------------------------------------- classify
77. def classify(f):
78. """Return content category, primary + alternate Topaz model, and settings.
80. Routing precedence (each rule guards the next):
81. 1. degraded -> small AND jaggy (real low-res, needs reconstruction)
82. 2. jpeg -> split by edge density: line-art/flat vs detailed
83. 3. flat vector -> very low raw color count (indexed / clean vector)
84. 4. detailed -> large and genuinely many quantized colors
85. 5. gradient -> everything else (mid-size RGBA logos with gloss/bevel)
86. """
87. degraded = f['px'] < 90_000 and f['flat'] > 0.15
88. soft_big = f['min_side'] >= 600 and f['hf'] < 0.012
89. notes = []
91. if degraded:
92. category = 'Low-res / degraded'
93. model, alt = 'Wonder 3', 'Low Resolution 2'
94. notes.append('Genuinely small with heavy anti-aliasing and little true detail. A '
95. 'generative model reconstructs cleaner edges than a core upscale can. '
96. 'Try Wonder 3 first; drop to Low Resolution 2 if it over-invents detail.')
97. elif f['is_jpeg']:
98. if f['edge'] > 0.03:
99. category = 'Detailed line art (JPEG)'
100. model, alt = 'Art & CG', 'Standard'
101. notes.append('Detailed, high-contrast linework saved as JPEG. Art & CG keeps the '
102. 'clean stylized edges; Standard if it reads more photographic.')
103. else:
104. category = 'Flat logo (JPEG)'
105. model, alt = 'Art & CG', 'Standard'
106. notes.append('Flat-color logo softened by JPEG compression. Art & CG rebuilds the '
107. 'clean edges.')
108. elif f['uniq'] < 200:
109. category = 'Flat vector logo'
110. model, alt = 'Text & Shapes', 'Art & CG'
111. notes.append('Few flat colors and hard edges (indexed / vector-style). Text & Shapes '
112. 'holds edge and shape geometry; switch to Art & CG if the piece is emblem/'
113. 'illustration-dominant rather than lettering.')
114. elif f['px'] > 300_000 and f['uniqq'] > 700:
115. category = 'Detailed illustration'
116. model, alt = 'Standard', 'Art & CG'
117. notes.append('Large, many-color illustration. Standard stays true-to-input; Art & CG '
118. 'if you want flatter, more graphic edges.')
119. else:
120. category = 'Gradient / rendered logo'
121. model, alt = 'Art & CG', 'Standard'
122. notes.append('Smooth gradients, bevels or 3D shading. Art & CG keeps clean edges and '
123. 'flat regions without inventing photographic texture.')
125. # ---- settings
126. s = {}
127. s['fix_compression'] = 'On (Medium)' if f['is_jpeg'] else 'Off'
128. if f['is_jpeg']:
129. notes.append('JPEG source: enable Fix Compression in Topaz. The prepped file is a '
130. 'lossless PNG, so no further generational loss occurs.')
131. s['denoise'] = 'Low (1-10), only if grain remains after Fix Compression' if f['is_jpeg'] else 'Off'
132. s['sharpen'] = 'Off (let the model handle edges)'
133. s['face_recovery'] = 'Off (stylized skull/figure marks are not real faces)'
134. if soft_big:
135. s['pre_downscaling'] = 'Low-Medium'
136. notes.append('Large but soft (high-frequency detail low for the pixel size): possible '
137. 'false resolution. Turn on Topaz Pre-downscaling, or re-run with '
138. '--predownscale to feed an already-concentrated file.')
139. else:
140. s['pre_downscaling'] = 'None'
141. s['color_space'] = 'Preserve input (export Adobe RGB if headed to CMYK prepress)'
143. if f['px'] < 60_000:
144. notes.append(f"Small source ({f['w']}x{f['h']}). At Topaz's 6x ceiling that is "
145. f"{f['w']*6}x{f['h']*6}px, so confirm the target print size fits before "
146. "committing (see Print reach below).")
148. return dict(category=category, model=model, alt=alt, settings=s, notes=notes,
149. soft_big=soft_big, jaggy_small=degraded)
152. # ----------------------------------------------------------------------------- prep ops
153. def _box(a, size=5):
154. """Mean filter. Uses scipy if present, else a separable numpy cumulative-sum box."""
155. try:
156. from scipy.ndimage import uniform_filter
157. return uniform_filter(a, size=size, mode='nearest')
158. except Exception:
159. r = size // 2
160. pad = [(r, r)] * 2 + [(0, 0)] * (a.ndim - 2)
161. ap = np.pad(a, pad, mode='edge')
162. c = np.cumsum(np.cumsum(ap, axis=0), axis=1)
163. c = np.pad(c, [(1, 0), (1, 0)] + [(0, 0)] * (a.ndim - 2), mode='constant')
164. H, W = a.shape[:2]
165. s = (c[size:size+H, size:size+W] - c[0:H, size:size+W]
166. - c[size:size+H, 0:W] + c[0:H, 0:W])
167. return s / (size * size)
170. def defringe(arr):
171. """Edge-extend opaque colors into transparent regions so an upscale of the RGB
172. plane doesn't pull background/halo into the logo edge. Returns RGB uint8."""
173. rgb = arr[..., :3].astype(np.float32)
174. a = (arr[..., 3:4].astype(np.float32)) / 255.0
175. mask = a[..., 0] > 0.05
176. if mask.all() or not mask.any():
177. return arr[..., :3].copy()
178. filled = rgb.copy()
179. w = (a[..., 0]).copy()
180. for _ in range(24):
181. if w.min() > 0.5:
182. break
183. num = _box(filled * w[..., None], size=5)
184. den = _box(w, size=5)[..., None] + 1e-6
185. avg = num / den
186. upd = w < 0.5
187. filled[upd] = avg[upd]
188. w = np.maximum(w, (den[..., 0] > 0.02).astype(np.float32) * 0.6)
189. return np.clip(filled, 0, 255).astype(np.uint8)
192. def prep_image(f, rec, outdir, do_predownscale):
193. im = Image.open(f['path'])
194. base = os.path.splitext(f['file'])[0]
195. outputs, recompose = [], None
197. rgba = im.convert('RGBA')
198. arr = np.asarray(rgba)
200. # optional false-resolution pre-downscale (opt-in)
201. scaled_note = ''
202. if do_predownscale and rec['soft_big']:
203. nw, nh = f['w'] // 2, f['h'] // 2
204. rgba = rgba.resize((nw, nh), Image.LANCZOS)
205. arr = np.asarray(rgba)
206. scaled_note = f' (pre-downscaled to {nw}x{nh} to concentrate detail)'
208. if f['has_alpha']:
209. # split: defringed RGB for Topaz + alpha mask for recompositing
210. rgb = defringe(arr)
211. rgb_path = os.path.join(outdir, f'{base}__RGB.png')
212. Image.fromarray(rgb, 'RGB').save(rgb_path, optimize=True)
213. outputs.append(os.path.basename(rgb_path))
214. mask_path = os.path.join(outdir, f'{base}__ALPHA.png')
215. Image.fromarray(arr[..., 3], 'L').save(mask_path, optimize=True)
216. outputs.append(os.path.basename(mask_path))
217. recompose = (f'Upscale {base}__RGB.png in Topaz. Separately upscale '
218. f'{base}__ALPHA.png by the SAME factor (use Standard, Denoise off). '
219. f'In Photoshop, load the upscaled alpha as a layer mask on the '
220. f'upscaled RGB to restore clean transparency without edge halo.')
221. else:
222. # opaque: flatten to clean RGB (handles indexed/JPEG/grayscale), lossless PNG
223. rgb_path = os.path.join(outdir, f'{base}__RGB.png')
224. rgba.convert('RGB').save(rgb_path, optimize=True)
225. outputs.append(os.path.basename(rgb_path))
227. return outputs, recompose, scaled_note
230. # ----------------------------------------------------------------------------- print sizing
231. def print_sizing(w, h, max_scale=6):
232. """Report achievable physical size at standard banner viewing-distance PPIs."""
233. ow, oh = w * max_scale, h * max_scale
234. rows = []
235. for ppi, label in [(150, 'close (≤6 ft)'), (100, 'standing (≈10 ft)'), (60, 'distant (≥20 ft)')]:
236. rows.append(f'{ow}x{oh}px @ {max_scale}x → {ow/ppi:.1f}\" x {oh/ppi:.1f}\" at {ppi} PPI ({label})')
237. return rows
240. # ----------------------------------------------------------------------------- report
241. def render_report(results, predownscale):
242. now = datetime.datetime.now().strftime('%Y-%m-%d')
243. out = []
244. out.append('# Topaz Pre-Pass Report\n')
245. out.append(f'Prepped {len(results)} image(s) on {now}. Each image below lists what was '
246. 'detected, the prepped file(s) to feed Topaz Gigapixel, and the model + settings '
247. 'to use. Files ending `__RGB.png` go into Topaz; `__ALPHA.png` is the transparency '
248. 'mask to recomposite after upscaling.\n')
249. out.append('> Prep was non-destructive: color-mode cleanup, lossless re-save, and (for '
250. 'transparent logos) alpha split with edge defringe. No sharpening or denoising was '
251. 'applied in Python, since Topaz works best on the original signal.\n')
252. if not predownscale:
253. out.append('> Pre-downscale was NOT applied (run with `--predownscale` to act on false-'
254. 'resolution flags). Where flagged, use Topaz\'s own Pre-downscaling toggle instead.\n')
255. out.append('\n---\n')
257. for r in results:
258. f, rec = r['f'], r['rec']
259. out.append(f"\n## {f['file']}\n")
260. out.append(f"**Category:** {rec['category']} ")
261. out.append(f"\n**Source:** {f['fmt']} {f['w']}x{f['h']} ({f['src_mode']}), "
262. f"{'transparent' if f['has_alpha'] else 'opaque'}, "
263. f"{f['uniq']} colors\n")
265. out.append(f"\n**Prepped file(s):** {', '.join('`'+o+'`' for o in r['outputs'])}{r['scaled_note']}\n")
267. out.append('\n**Topaz settings**\n')
268. out.append(f"- Model: **{rec['model']}** (alternate: {rec['alt']})")
269. s = rec['settings']
270. out.append(f"- Fix Compression: {s['fix_compression']}")
271. out.append(f"- Denoise: {s['denoise']}")
272. out.append(f"- Sharpen: {s['sharpen']}")
273. out.append(f"- Pre-downscaling: {s['pre_downscaling']}")
274. out.append(f"- Face Recovery: {s['face_recovery']}")
275. out.append(f"- Color space on export: {s['color_space']}")
277. if r['recompose']:
278. out.append(f"\n**Transparency:** {r['recompose']}\n")
280. out.append('\n**Print reach** (max 6x):')
281. for line in print_sizing(f['w'], f['h']):
282. out.append(f'- {line}')
284. if rec['notes']:
285. out.append('\n**Why:**')
286. for n in rec['notes']:
287. out.append(f'- {n}')
288. out.append('\n---')
290. out.append('\n### Reading the metrics')
291. out.append('Categories are routed from measurable features: color count and flatness '
292. '(vector vs continuous-tone), edge density (text/shape vs photo), high-frequency '
293. 'energy vs size (false resolution), JPEG blockiness (compression), and alpha '
294. 'coverage (transparency handling). See `references/model-selection.md` in the skill '
295. 'for the full routing table.')
296. return '\n'.join(out)
299. # ----------------------------------------------------------------------------- main
300. def collect_inputs(paths):
301. files = []
302. for p in paths:
303. if os.path.isdir(p):
304. for e in EXTS:
305. files += glob.glob(os.path.join(p, f'*{e}'))
306. files += glob.glob(os.path.join(p, f'*{e.upper()}'))
307. elif os.path.isfile(p) and p.lower().endswith(EXTS):
308. files.append(p)
309. return sorted(set(files))
312. def main():
313. ap = argparse.ArgumentParser()
314. ap.add_argument('inputs', nargs='+')
315. ap.add_argument('--out', required=True)
316. ap.add_argument('--predownscale', action='store_true',
317. help='Act on false-resolution flags by downscaling 2x before upscaling.')
318. ap.add_argument('--zip-name', default='topaz-prepped.zip')
319. args = ap.parse_args()
321. files = collect_inputs(args.inputs)
322. if not files:
323. print('No images found.', file=sys.stderr); sys.exit(1)
324. os.makedirs(args.out, exist_ok=True)
326. results, analysis = [], []
327. for path in files:
328. f = analyze(path)
329. rec = classify(f)
330. outputs, recompose, scaled_note = prep_image(f, rec, args.out, args.predownscale)
331. results.append(dict(f=f, rec=rec, outputs=outputs, recompose=recompose,
332. scaled_note=scaled_note))
333. analysis.append(dict(file=f['file'], category=rec['category'], model=rec['model'],
334. alt=rec['alt'], settings=rec['settings'], outputs=outputs,
335. metrics={k: f[k] for k in ('fmt','w','h','uniq','flat','edge','hf','blk','has_alpha','transp')}))
336. print(f"{f['file']:34s} -> {rec['category']:24s} {rec['model']}")
338. report = render_report(results, args.predownscale)
339. report_path = os.path.join(args.out, 'Topaz-Prep-Report.md')
340. with open(report_path, 'w') as fh:
341. fh.write(report)
342. with open(os.path.join(args.out, 'analysis.json'), 'w') as fh:
343. json.dump(analysis, fh, indent=2)
345. # zip prepped images + report
346. zip_path = os.path.join(args.out, args.zip_name)
347. with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as z:
348. for r in results:
349. for o in r['outputs']:
350. z.write(os.path.join(args.out, o), o)
351. z.write(report_path, 'Topaz-Prep-Report.md')
352. print(f'\nReport: {report_path}\nZip: {zip_path}')
355. if __name__ == '__main__':
356. main()