gen-truepng

name	gen-truepng
description	Use when converting fake-transparent/checkerboard PNG/JPG/WebP outputs from image generators such as ChatGPT, Gemini, Qwen / Tongyi Qianwen, or similar tools into true transparent PNGs, or when cleaning white/gray halos, jagged alpha edges, sparse edge fragments, and matte residue around product cutouts.
license	MIT
metadata	{"version":"0.1.0","repository":"marshal-zheng/skills","repository_url":"https://github.com/marshal-zheng/skills","skill_path":"skills/gen-truepng","install_command":"npx skills add marshal-zheng/skills --skill gen-truepng"}

Gen TruePNG

Overview

Use the bundled script to turn generated fake-transparent raster assets into real transparent PNGs while preserving product and device details, including dark rack bodies, vents, ports, LEDs, and gray panels. This skill exists for a common generative-image failure mode: the output looks transparent in the chat UI, but the checkerboard or bright matte is baked into RGB pixels.

The workflow is conservative by default: RGB images are processed, but PNGs that already contain alpha are copied without further background/halo removal unless explicitly forced.

When to Use

Use this skill for:

• Fake transparent checkerboard backgrounds that should become alpha.
• Generated image outputs from ChatGPT, Gemini, Qwen / Tongyi Qianwen, or similar tools that visually promise transparency but contain opaque checkerboard pixels.
• White, gray, or bright matte halos around product/device edges.
• Hard 0/255 alpha edges that look jagged on dark backgrounds.
• Sparse one-row or one-column edge fragments, such as dotted bottom-edge residue.
• Rack equipment/product cutouts where dark metal body, vents, ports, LEDs, and gray top panels must be preserved.

Do not use this skill for:

• Redrawing or inventing missing product pixels.
• Complex photo background removal where foreground/background colors overlap heavily.
• Vector/SVG cleanup.
• Existing transparent PNGs unless there is a clear reason to run --process-existing-alpha.

Default Workflow

1. Locate the source image and decide whether it is RGB fake transparency or already has alpha:

   file input.png
   python3 - <<'PY'
   from PIL import Image
   import numpy as np
   img = Image.open("input.png").convert("RGBA")
   alpha = np.array(img)[:, :, 3]
   print("has_existing_alpha:", bool((alpha < 255).any()))
   print("partial_alpha:", int(((alpha > 0) & (alpha < 255)).sum()))
   PY
   

2. Run the bundled converter. Prefer a temporary output first when tuning:

   python3 "<skill-dir>/scripts/gen-truepng.py" input.png -o /tmp/input-transparent.png --overwrite
   

3. Inspect against a dark background before overwriting the deliverable:

   python3 - <<'PY'
   from PIL import Image
   src = "/tmp/input-transparent.png"
   img = Image.open(src).convert("RGBA")
   bg = Image.new("RGBA", img.size, (22, 24, 28, 255))
   bg.alpha_composite(img)
   preview = bg.resize((min(1200, img.width), int(min(1200, img.width) * img.height / img.width)))
   preview.convert("RGB").save("/tmp/transparent-preview.jpg", quality=95)
   print("/tmp/transparent-preview.jpg")
   PY
   

4. If the preview is correct, write the final transparent PNG:

   python3 "<skill-dir>/scripts/gen-truepng.py" input.png -o input_truepng.png --overwrite
   

Script Behavior

The converter combines these steps:

Step	Purpose	Default
Bright checkerboard mask	Removes high-brightness neutral fake background	--min-brightness 230 --max-diff 10
Limited edge growth	Removes near-edge gray matte without swallowing gray device panels	--edge-bg-min 160 --edge-bg-passes 6
Dehalo	Removes bright pixels adjacent to transparency	--halo-min 200 --halo-max-diff 55
Sparse edge trim	Drops very sparse outer rows/columns	--sparse-edge-ratio 0.35
Fragment edge trim	Drops dotted/fragmented outer rows/columns	--fragment-edge-ratio 0.55
Feather	Adds soft alpha transition to avoid jagged 0/255 edges	--feather-radius 0.6

Existing-alpha inputs are protected. If an image already has transparent pixels, background/halo/feather processing is skipped unless --process-existing-alpha is passed.

Tuning Guide

Symptom	First adjustment
White/gray edge still visible	Increase --edge-bg-passes slightly, or lower --halo-min toward 180 after checking it does not erase gray body parts.
Device gray panel/top face is erased	Raise --edge-bg-min, lower --edge-bg-passes, or use --no-edge-bg.
Bottom/top dotted residue remains	Increase --fragment-edge-ratio to 0.6; avoid raising --sparse-edge-ratio first because it can eat continuous sloped edges.
Edge looks too jagged	Increase --feather-radius to 0.8 or 1.0.
Edge looks too soft/thin	Lower --feather-radius to 0.4, or set --feather-radius 0.
Existing transparent PNG changed unexpectedly	Re-run without --process-existing-alpha; default behavior should preserve existing alpha images.

Verification Checks

After processing, verify with both pixels and a visual preview:

python3 - <<'PY'
from PIL import Image
import numpy as np
img = Image.open("input_truepng.png").convert("RGBA")
alpha = np.array(img)[:, :, 3]
ys, xs = np.where(alpha > 0)
print("bbox:", (int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())) if len(xs) else None)
print("transparent:", int((alpha == 0).sum()))
print("partial:", int(((alpha > 0) & (alpha < 255)).sum()))
print("opaque:", int((alpha == 255).sum()))
PY

Look for:

• No checkerboard or white/gray short segments around the outer edge.
• No missing device body areas, especially gray top panels and bottom lips.
• Nonzero partial-alpha count when anti-aliased edges are expected.
• A stable bounding box that matches the real object silhouette.

Common Failure Modes

• Over-aggressive gray cleanup: gray metal panels can resemble background. Use limited edge growth, and do not lower --halo-min casually.
• Double-processing transparent PNGs: already-transparent assets may have carefully painted alpha. Let the script skip them unless the user explicitly wants repair.
• Blind overwrite: always generate a temporary preview when changing thresholds.
• Treating shadows as always wrong: product bottom lips and soft inner shadows can be real details; remove only fragmented outer residue or obvious matte.

Script

Bundled helper:

python3 "<skill-dir>/scripts/gen-truepng.py" --help

The script requires Python with Pillow and numpy available.