Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(slice-images): warn when flat-background keying did not take

hugohe3ff3b0f99829d
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index 7da75256..77f1efec 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -267,7 +267,7 @@ into an image.
- Choose the sheet `aspect_ratio` and `--grid` from the target element shape. Do not default every sheet to `1:1` + a symmetric grid.
- Lay the elements out in an explicit **R×C grid, evenly spaced with clear gutters**, each element **centered in its own cell** and isolated (no element bleeds into a neighbor).
- State the intended cell shape in the prompt: compact square object, tall portrait element, wide landscape vignette, or wide lettering mark. Do not let the model shrink every subject into a centered square sticker.
-- One **flat single-color background** across the whole sheet, set to the deck's background/secondary HEX — this is what lets the slicer key it out cleanly and lets the cut element sit on the slide without a visible box.
+- One **flat single-color background** across the whole sheet, set to the deck's background/secondary HEX — this is what lets the slicer key it out cleanly and lets the cut element sit on the slide without a visible box. Gutters are part of that same flat ground; keep paper grain, halftone, vignette, and every other texture inside the elements, never over the background.
- Shared `deck_rendering` + `color_scheme` as always.
- **Spot sheet**: apply the §5.3 `none` cue; include no text, labels, or numbers.
- **Lettering sheet**: put exactly one named stable string in each cell as the only text, quote every complete character sequence literally in the prompt, and describe one shared artistic treatment. Keep each mark isolated on the flat key background with no scene, title copy, labels, watermark, mockup surface, or unrequested symbols.
@@ -305,7 +305,7 @@ python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \
**Three constraints that decide whether it looks good**:
-1. **Flat background, matched to the slide.** `image_gen.py` has no transparent-background mode, so the cut element carries whatever was behind it. A flat sheet background (= deck background HEX) is what `--alpha` keys out and what makes non-keyed pieces blend.
+1. **Flat background, matched to the slide.** `image_gen.py` has no transparent-background mode, so the cut element carries whatever was behind it. A flat sheet background (= deck background HEX) is what `--alpha` keys out and what makes non-keyed pieces blend. Texture over the ground defeats the key, so request grain or halftone only inside the elements. `slice_images.py` warns when an element keeps opaque corners after `--alpha` or when `--trim` removed nothing; both mean the key did not take. Regenerate the sheet with a clean ground, or rerun with an explicit `--bg` and a larger `--tolerance`, before placing the element on a non-background surface.
2. **Clean grid, or it cuts ugly.** State the exact row/column structure and cell shape so the model does not invent a square matrix; `--trim` absorbs smaller placement variance. For lettering, a wrong/missing character, extra copy, fused cells, or scene background makes the parent sheet unusable. Do not generate several sheets or read them back merely to choose a favorite; re-roll only when user/live-preview feedback exposes an unusable slice, then slice the replacement sheet again.
3. **Generate only as large as needed.** Each cell is a fraction of the sheet. Pick the smallest sheet size that keeps each sliced cell at least **1.5-2x** the intended display size. `1K` is usually enough for small 80-160px decorative spots; use `2K` for medium 180-320px placements; reserve `4K` for large, cropped, or potentially enlarged elements.
diff --git a/skills/ppt-master/scripts/slice_images.py b/skills/ppt-master/scripts/slice_images.py
index 2bfe79c7..956ae900 100644
--- a/skills/ppt-master/scripts/slice_images.py
+++ b/skills/ppt-master/scripts/slice_images.py
@@ -15,7 +15,10 @@ Two optional cleanups address the realities of cropping a raster sheet:
--alpha knock the (flat) sheet background out to transparency, so an element
can sit on a differently-colored slide without a visible box.
Both need a background color; it is auto-sampled from each cell's border unless
-you pass --bg.
+you pass --bg. Keying only works on a genuinely flat ground, so each element is
+checked afterwards and a warning is printed when the background clearly did not
+key out. See references/image-generator.md section 4.3 for the sheet contract
+that keeps the ground flat.
Usage:
python3 scripts/slice_images.py <sheet_image> --grid RxC [options]
@@ -47,6 +50,7 @@ from PIL import Image, ImageChops, ImageFilter
_GRID_RE = re.compile(r"^\s*(\d+)\s*[xX×]\s*(\d+)\s*$")
_BG_SAMPLE_BORDER = 2
_DEFAULT_FEATHER = 4
+_CORNER_OPAQUE_ALPHA = 32
def _log(msg: str) -> None:
@@ -148,6 +152,51 @@ def _content_masks(
return trim_mask, alpha_mask
+def _keying_findings(
+ label: str,
+ cell_size: tuple[int, int],
+ bbox: tuple[int, int, int, int],
+ alpha_mask: Optional[Image.Image],
+ cell_bg: tuple[int, int, int],
+ *,
+ trim: bool,
+ alpha: bool,
+) -> list[str]:
+ """Report objective signs that the flat-background key did not take.
+
+ Two deterministic symptoms: a cut element whose corners are still opaque,
+ and a ``--trim`` that removed nothing because the mask found content along
+ every edge. Both mean the sampled background did not match the real ground
+ (a textured or multi-color ground is the usual cause).
+ """
+ findings: list[str] = []
+ hex_bg = "#{:02X}{:02X}{:02X}".format(*cell_bg)
+
+ if alpha and alpha_mask is not None:
+ px = alpha_mask.load()
+ width, height = alpha_mask.size
+ corners = (
+ px[0, 0], px[width - 1, 0],
+ px[0, height - 1], px[width - 1, height - 1],
+ )
+ opaque = sum(1 for value in corners if value > _CORNER_OPAQUE_ALPHA)
+ if opaque:
+ findings.append(
+ f"{label}: {opaque}/4 corners stayed opaque after --alpha "
+ f"(sampled background {hex_bg})"
+ )
+
+ if trim:
+ cell_width, cell_height = cell_size
+ if bbox[2] - bbox[0] >= cell_width and bbox[3] - bbox[1] >= cell_height:
+ findings.append(
+ f"{label}: --trim removed nothing, so content reaches every cell edge "
+ f"(sampled background {hex_bg})"
+ )
+
+ return findings
+
+
def slice_sheet(
sheet_path: Path,
rows: int,
@@ -199,6 +248,7 @@ def slice_sheet(
stem = sheet_path.stem
name_prefix = _safe_basename(prefix) if prefix else f"{stem}_"
written: list[Path] = []
+ findings: list[str] = []
idx = 0
for r in range(rows):
@@ -221,6 +271,10 @@ def slice_sheet(
bbox = trim_mask.getbbox()
if bbox is None:
raise ValueError(f"cell ({r},{c}) is all background; no element was sliced")
+ findings.extend(_keying_findings(
+ f"cell ({r},{c})", cell.size, bbox, alpha_mask, cell_bg,
+ trim=trim, alpha=alpha,
+ ))
if trim and trim_mask is not None and alpha_mask is not None and bbox is not None:
cell = cell.crop(bbox)
@@ -243,6 +297,18 @@ def slice_sheet(
if len(written) != total_cells:
raise ValueError(f"sliced {len(written)} elements but expected {total_cells}")
+
+ if findings:
+ _log("\n[WARN] Background keying looks incomplete — the cut element(s) may")
+ _log(" still carry a visible box on a differently-colored slide:")
+ for finding in findings:
+ _log(f" - {finding}")
+ _log(" Fix: regenerate the sheet with one genuinely flat ground "
+ "(no grain, halftone, or")
+ _log(" vignette over the background, gutters included), or rerun with "
+ "an explicit")
+ _log(" --bg <hex> and a larger --tolerance.")
+
return written