@creator-notes/cnotes 0.35.0 → 0.37.0

package/skills/howto-filmstrips/scripts/soft-spotlight.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Soft radial spotlight post-process for how-to filmstrip frames.
+
+Use when the in-page CSS overlay was weak or missing. Centres are CSS pixels
+from getBoundingClientRect; pass --dpr for retina screenshots (often 2).
+
+Example:
+  python3 soft-spotlight.py --in A3.png --out A3.png --cx 276 --cy 219 --dpr 2 --opacity 0.55
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+
+def soft_spotlight(
+    im: Image.Image,
+    cx: float,
+    cy: float,
+    hole_r: float = 180,
+    max_opacity: float = 0.4,
+    fade_mult: float = 5.5,
+) -> Image.Image:
+    w, h = im.size
+    ys = np.arange(h)[:, None]
+    xs = np.arange(w)[None, :]
+    dist = np.sqrt((xs - cx) ** 2 + (ys - cy) ** 2)
+    ramp_end = hole_r * fade_mult
+    t = np.clip((dist - hole_r) / max(ramp_end - hole_r, 1), 0, 1)
+    t = t * t * (3 - 2 * t)  # smoothstep
+    alpha = (t * max_opacity * 255).astype(np.uint8)
+    overlay = np.zeros((h, w, 4), dtype=np.uint8)
+    overlay[..., 3] = alpha
+    base = im.convert("RGBA")
+    return Image.alpha_composite(base, Image.fromarray(overlay, "RGBA"))
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--in", dest="src", required=True, help="Input PNG")
+    p.add_argument("--out", dest="dst", required=True, help="Output PNG")
+    p.add_argument("--cx", type=float, required=True, help="Centre X in CSS pixels")
+    p.add_argument("--cy", type=float, required=True, help="Centre Y in CSS pixels")
+    p.add_argument("--dpr", type=float, default=1.0, help="Device pixel ratio (default 1)")
+    p.add_argument("--hole", type=float, default=None, help="Clear hole radius in device pixels")
+    p.add_argument("--opacity", type=float, default=0.4, help="Max dim opacity 0–1")
+    p.add_argument("--fade-mult", type=float, default=5.5, help="Fade length as multiple of hole")
+    args = p.parse_args()
+
+    src = Path(args.src)
+    dst = Path(args.dst)
+    im = Image.open(src)
+    cx = args.cx * args.dpr
+    cy = args.cy * args.dpr
+    hole = args.hole if args.hole is not None else max(160.0, 90.0 * args.dpr)
+
+    out = soft_spotlight(
+        im,
+        cx,
+        cy,
+        hole_r=hole,
+        max_opacity=args.opacity,
+        fade_mult=args.fade_mult,
+    )
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    out.convert("RGB").save(dst, quality=92)
+    print(f"wrote {dst} center=({cx:.0f},{cy:.0f}) hole={hole:.0f} opacity={args.opacity}")
+
+
+if __name__ == "__main__":
+    main()