Skip to content

notque/vexjoy-agent / skills/game/game-dev

game-dev

Flagged

Game development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.

FileKindSize
SKILL.mdskill md13.2 KB
references/anchor-alignment.mdmarkdown16.0 KB
references/animate-scaffolds.mdmarkdown2.0 KB
references/arcade-physics.mdmarkdown7.4 KB
references/artifacts-and-prototyping.mdmarkdown1.5 KB
references/asset-sources.mdmarkdown7.9 KB
references/audit-and-red-team.mdmarkdown795 B
references/autonomous-improvement.mdmarkdown10.3 KB
references/backend-chain.mdmarkdown10.4 KB
references/bg-removal-local.mdmarkdown22.7 KB
references/build-scaffolds.mdmarkdown2.0 KB
references/capabilities/01-design-red-team-audit.mdmarkdown3.9 KB
references/capabilities/02-emotional-canvas-moodboard.mdmarkdown3.7 KB
references/capabilities/03-game-design-attribution-audit.mdmarkdown3.6 KB
references/capabilities/04-game-design-bartle-archetype-audit.mdmarkdown3.7 KB
references/capabilities/05-game-design-big-five-personality-audit.mdmarkdown3.6 KB
references/capabilities/06-game-design-brainstorm-methods.mdmarkdown3.9 KB
references/capabilities/07-game-design-core-loop-extractor.mdmarkdown3.7 KB
references/capabilities/08-game-design-craft-critique.mdmarkdown3.5 KB
references/capabilities/09-game-design-creative-unblocker.mdmarkdown3.5 KB
references/capabilities/10-game-design-design-pillars-extractor.mdmarkdown3.5 KB
references/capabilities/11-game-design-emotional-canvas.mdmarkdown3.6 KB
references/capabilities/12-game-design-failure-loop-audit.mdmarkdown3.8 KB
references/capabilities/13-game-design-fairness-frustration-audit.mdmarkdown3.6 KB
references/capabilities/14-game-design-fantasy-extractor.mdmarkdown3.6 KB
references/capabilities/15-game-design-feature-prioritization.mdmarkdown3.6 KB
references/capabilities/16-game-design-five-options.mdmarkdown3.5 KB
references/capabilities/17-game-design-flow-audit.mdmarkdown3.6 KB
references/capabilities/18-game-design-fogg-behavior-audit.mdmarkdown3.6 KB
references/capabilities/19-game-design-friction-journey-audit.mdmarkdown3.8 KB
references/capabilities/20-game-design-ftue-hero-journey-audit.mdmarkdown3.7 KB
references/capabilities/21-game-design-goal-density-and-immediacy-audit.mdmarkdown3.5 KB
references/capabilities/22-game-design-goal-framing.mdmarkdown3.5 KB
references/capabilities/23-game-design-granular-player-motivation-audit.mdmarkdown4.0 KB
references/capabilities/24-game-design-grow-design.mdmarkdown3.5 KB
references/capabilities/25-game-design-ideal-outcome-backcasting.mdmarkdown3.4 KB
references/capabilities/26-game-design-kpi-coverage-audit.mdmarkdown3.8 KB
references/capabilities/27-game-design-leaderboard-audit.mdmarkdown3.9 KB
references/capabilities/28-game-design-leaderboard-builder.mdmarkdown3.8 KB
references/capabilities/29-game-design-molyneux-lens.mdmarkdown3.5 KB
references/capabilities/30-game-design-multiplayer-feature-audit.mdmarkdown3.8 KB
references/capabilities/31-game-design-novelty-spectrum-audit.mdmarkdown3.6 KB
references/capabilities/32-game-design-one-page-design-doc.mdmarkdown3.8 KB
references/capabilities/33-game-design-one-thing-to-remove.mdmarkdown3.6 KB
references/capabilities/34-game-design-option-generation.mdmarkdown3.5 KB
references/capabilities/35-game-design-peak-end-audit.mdmarkdown3.6 KB
references/capabilities/36-game-design-perceived-randomness-audit.mdmarkdown3.7 KB
references/capabilities/37-game-design-pitch-deck-audit.mdmarkdown3.8 KB
references/capabilities/38-game-design-player-motivation-audit.mdmarkdown3.5 KB
references/capabilities/39-game-design-player-need-satisfaction-audit.mdmarkdown3.6 KB
references/capabilities/40-game-design-player-persona-extractor.mdmarkdown4.2 KB
references/capabilities/41-game-design-player-perspective-reframe.mdmarkdown3.7 KB
references/capabilities/42-game-design-player-segment-perception-audit.mdmarkdown3.6 KB
references/capabilities/43-game-design-player-values-mapper.mdmarkdown3.8 KB
references/capabilities/44-game-design-premium-pass-audit.mdmarkdown3.8 KB
references/capabilities/45-game-design-prosocial-session-chapters.mdmarkdown3.7 KB
references/capabilities/46-game-design-prototype-intent-audit.mdmarkdown3.7 KB
references/capabilities/47-game-design-prototyping-companion.mdmarkdown3.6 KB
references/capabilities/48-game-design-roadblock-reframing.mdmarkdown3.5 KB
references/capabilities/49-game-design-smart-goal-audit.mdmarkdown3.6 KB
references/capabilities/50-game-design-social-satisfaction-matrix.mdmarkdown3.7 KB
references/capabilities/51-game-design-systematizing-empathizing-audit.mdmarkdown3.6 KB
references/capabilities/52-game-design-thinking-fast-and-slow-audit.mdmarkdown3.6 KB
references/capabilities/53-game-design-transformative-reuse.mdmarkdown3.6 KB
references/capabilities/54-game-design-unknown-unknowns-prototyping.mdmarkdown3.6 KB
references/capabilities/55-game-design-zeigarnik-effect-audit.mdmarkdown3.6 KB
references/capabilities/56-game-dev-budget-estimator.mdmarkdown3.8 KB
references/capabilities/57-game-dev-first-steps.mdmarkdown3.6 KB
references/capabilities/58-game-dev-team-gap.mdmarkdown3.6 KB
references/capabilities/59-game-dev-time-estimator.mdmarkdown3.8 KB
references/capabilities/60-moodboard-generator.mdmarkdown4.0 KB
references/capabilities/61-software-team-conflict-patterns.mdmarkdown3.8 KB
references/capability-catalog.mdmarkdown18.4 KB
references/capability-map.mdmarkdown1.7 KB
references/capability-matrix.mdmarkdown12.5 KB
references/capacitor-ios.mdmarkdown7.3 KB
references/cognition-and-choice.mdmarkdown1.2 KB
references/cognitive-and-behavioral-lenses.mdmarkdown1.2 KB
references/concept-and-loop.mdmarkdown1.5 KB
references/core-loop-and-pillars.mdmarkdown835 B
references/core-patterns.mdmarkdown8.2 KB
references/cpu-systems-harmony.mdmarkdown3.4 KB
references/creative-and-options.mdmarkdown2.0 KB
references/creative-direction.mdmarkdown1.3 KB
references/deploy.mdmarkdown5.3 KB
references/design-artifacts.mdmarkdown1.0 KB
references/emotion-and-presentation.mdmarkdown1.1 KB
references/error-catalog.mdmarkdown22.6 KB
references/fairness-and-failure.mdmarkdown1.2 KB
references/fairness-and-learning.mdmarkdown1.3 KB
references/fal-ai-image.mdmarkdown7.1 KB
references/frame-detection.mdmarkdown20.0 KB
references/full-diagnostic.mdmarkdown4.2 KB
references/game-asset-generator.mdmarkdown9.5 KB
references/game-audio.mdmarkdown7.5 KB
references/game-feel-patterns.mdmarkdown12.2 KB
references/game-pipeline.mdmarkdown11.5 KB
references/game-qa.mdmarkdown6.7 KB
references/game-sprite-pipeline.mdmarkdown33.4 KB
references/gm-brilliant-implementation.mdmarkdown13.4 KB
references/grid-shapes.mdmarkdown8.0 KB
references/meshyai.mdmarkdown7.3 KB
references/motion-pipeline.mdmarkdown7.5 KB
references/output-formats.mdmarkdown9.4 KB
references/pacing-and-return.mdmarkdown1.6 KB
references/performance.mdmarkdown7.8 KB
references/phaser-gamedev.mdmarkdown7.5 KB
references/pipeline-spec.jsonconfig23.0 KB
references/pixel-art-sprites.mdmarkdown8.7 KB
references/planning-and-communication.mdmarkdown1.6 KB
references/planning-and-production.mdmarkdown1.8 KB
references/player-and-social.mdmarkdown2.3 KB
references/polish-scaffolds.mdmarkdown1.9 KB
references/progression-and-economy.mdmarkdown1.0 KB
references/promo-video.mdmarkdown6.6 KB
references/prompt-rules.mdmarkdown15.2 KB
references/quality-gates.mdmarkdown6.4 KB
references/road-to-aew-integration.mdmarkdown7.8 KB
references/social-and-competitive-design.mdmarkdown1.1 KB
references/social-and-competitive.mdmarkdown1.5 KB
references/spritesheets.mdmarkdown6.2 KB
references/stage-contracts.mdmarkdown11.1 KB
references/style-presets.mdmarkdown5.1 KB
references/subagent-delegation.mdmarkdown2.2 KB
references/tilemaps-and-physics.mdmarkdown13.6 KB
references/tilemaps.mdmarkdown7.0 KB
references/unity-batchmode-builds.mdmarkdown9.2 KB
references/unity-cli.mdmarkdown10.9 KB
references/unity-licensing.mdmarkdown5.0 KB
references/vfx-containment.mdmarkdown3.1 KB
references/workflow-dag.mdmarkdown4.1 KB
references/worldlabs.mdmarkdown7.9 KB
references/wrestler-archetypes.mdmarkdown7.2 KB
scripts/deterministic_idle.pyscript7.8 KB
scripts/fal_queue_image_run.pyscript9.4 KB
scripts/imgdiff.pyscript5.0 KB
scripts/meshy-generate.mjsscript11.1 KB
scripts/optimize-glb.mjsscript3.8 KB
scripts/portrait_pipeline.pyscript31.2 KB
scripts/qa_artifacts.pyscript14.4 KB
scripts/road_to_aew_integration.pyscript6.6 KB
scripts/row_job_status.pyscript8.6 KB
scripts/sprite_anchor.pyscript30.1 KB
scripts/sprite_assemble.pyscript16.0 KB
scripts/sprite_bg.pyscript28.5 KB
scripts/sprite_canvas.pyscript11.9 KB
scripts/sprite_generate.pyscript13.9 KB
scripts/sprite_pipeline.pyscript54.9 KB
scripts/sprite_process.pyscript13.5 KB
scripts/sprite_prompt.pyscript41.8 KB
scripts/sprite_slicing.pyscript38.7 KB
scripts/sprite_verify.pyscript58.5 KB
scripts/test_content_aware_extraction.pyscript13.4 KB
scripts/test_no_status_laundering.pyscript6.9 KB
scripts/test_phases_4_5_7_8.pyscript16.4 KB
scripts/test_pipeline_glue.pyscript20.9 KB
scripts/test_pipeline_patterns.pyscript10.9 KB
scripts/test_rc3_frames_distinct_threshold.pyscript14.2 KB
scripts/test_rc4_mass_centroid_default.pyscript8.3 KB
scripts/test_rc5_despill_pre_upscale.pyscript7.9 KB
scripts/test_slice_grid_cells.pyscript6.4 KB
scripts/test_slicer_strict_pitch_default.pyscript11.6 KB
scripts/test_verifier_cell_parity.pyscript9.0 KB
scripts/test_verify_gates.pyscript23.2 KB
scripts/tests/test_fal_queue_image_run.pyscript908 B
scripts/video_extract_frames.pyscript4.3 KB
scripts/video_process_frames.pyscript7.6 KB
scripts/video_select_frames.pyscript6.4 KB
scripts/with_server.pyscript5.8 KB

scripts/sprite_bg.py

View on GitHub
#!/usr/bin/env python3
"""Background-removal primitives for the game-sprite-pipeline skill.

Owns the chroma-key + despill chain, the gray-tolerance road-to-aew
algorithm, the rembg fallback, and the `remove-bg` CLI subcommand. All
operations are local + deterministic (apart from rembg, which is opt-in).

Public surface (re-exported through `sprite_process` for backward compat):
    Constants:
        MAGENTA, DEFAULT_CHROMA_THRESHOLD, DEFAULT_PASS2_THRESHOLD,
        DEFAULT_DESPILL_STRENGTH, DEFAULT_ALPHA_DILATE_RADIUS,
        DEFAULT_MIN_COMPONENT_PIXELS, GRAY_BG_DEFAULT,
        GRAY_BG_TOLERANCE_DEFAULT, WATERMARK_MARGIN_DEFAULT,
        WATERMARK_BRIGHTNESS_THRESHOLD, BG_MODE_CHOICES.
    Pixel helpers:
        chroma_pass1, chroma_pass2_edge_flood, dilate_alpha_zero,
        color_despill_magenta, kill_pink_fringe,
        neutralize_interior_magenta_spill, matte_composite,
        alpha_fade_magenta_fringe.
    File-level helpers:
        remove_bg_chroma, remove_watermark_corners,
        gray_tolerance_to_alpha, remove_bg_gray_tolerance,
        remove_bg_rembg.
    CLI:
        cmd_remove_bg, _alpha_coverage_too_low.
"""

from __future__ import annotations

import argparse
import logging
import sys
from collections import deque
from pathlib import Path

logger = logging.getLogger("sprite-pipeline.sprite_bg")

try:
    from PIL import Image
except ImportError as e:
    logger.error("Pillow not installed: %s", e)
    logger.error("Install with: pip install pillow")
    sys.exit(1)

try:
    import numpy as np

    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------
MAGENTA = (255, 0, 255)
DEFAULT_CHROMA_THRESHOLD = 30
# Pass-2 default loosened from 60 (= 2 * pass1) to 90 because despill now
# protects character pixels at the fringe. See bg-removal-local.md.
DEFAULT_PASS2_THRESHOLD = 90
DEFAULT_DESPILL_STRENGTH = 0.5
DEFAULT_ALPHA_DILATE_RADIUS = 1
DEFAULT_MIN_COMPONENT_PIXELS = 200
DEFAULT_BOTTOM_MARGIN = 8
DEFAULT_GIF_FPS = 10

# Adapted from ~/road-to-aew/scripts/generate_enemy_sprite.py (lines 1048-1128).
# road-to-aew uses Gemini Nano Banana which paints a #3a3a3a background;
# this skill exposes the same algorithm under --bg-mode gray-tolerance for
# any backend that does not honor the magenta-bg prompt.
GRAY_BG_DEFAULT = (58, 58, 58)
GRAY_BG_TOLERANCE_DEFAULT = 30
WATERMARK_MARGIN_DEFAULT = 40
WATERMARK_BRIGHTNESS_THRESHOLD = 180

# Canonical --bg-mode CLI choices. Owned here because every bg-removal
# command-line surface (sprite_process.py, sprite_pipeline.py,
# portrait_pipeline.py) should advertise the same set.
#
# `chroma`: two-pass chroma key (default magenta #FF00FF matte). Default.
# `gray-tolerance`: tolerance-banded gray-to-alpha (road-to-aew #3a3a3a algorithm).
# `rembg`: ONNX-model-based bg removal (opt-in dep).
# `auto`: try chroma; fall back if mask coverage looks suspicious.
#
# See ADR-204 for the unified vocabulary across pipelines. The legacy
# `magenta` alias was dropped — it was always a misnomer for the chroma
# algorithm with the default magenta matte.
BG_MODE_CHOICES = ("chroma", "gray-tolerance", "rembg", "auto")


# ---------------------------------------------------------------------------
# Chroma key (portrait Phase B + spritesheet Phase E)
# ---------------------------------------------------------------------------
def chroma_pass1(img: Image.Image, chroma: tuple[int, int, int], threshold: int) -> Image.Image:
    """Mask pixels within sum-of-abs-diff threshold of chroma."""
    img = img.convert("RGBA")
    if HAS_NUMPY:
        arr = np.array(img)
        rgb = arr[..., :3].astype(int)
        diff = np.abs(rgb - np.array(chroma)).sum(axis=-1)
        mask = diff <= threshold
        arr[mask, 3] = 0
        return Image.fromarray(arr, "RGBA")

    # Pure-Python fallback
    pixels = img.load()
    w, h = img.size
    for y in range(h):
        for x in range(w):
            r, g, b, a = pixels[x, y]
            if abs(r - chroma[0]) + abs(g - chroma[1]) + abs(b - chroma[2]) <= threshold:
                pixels[x, y] = (r, g, b, 0)
    return img


def chroma_pass2_edge_flood(
    img: Image.Image,
    chroma: tuple[int, int, int],
    threshold: int,
    despill_strength: float = DEFAULT_DESPILL_STRENGTH,
) -> Image.Image:
    """Despill-aware flood-fill from canvas edges with looser threshold.

    Pass 2 walks inward from canvas edges and zeros alpha for any pixel that
    is "close enough" to the chroma color (`threshold`). The despill check
    protects pixels whose RGB is off-color relative to the chroma — this is
    the character's anti-aliased fringe where lighting/spill has shifted the
    pixel away from pure magenta. Without despill, threshold=90 bites into
    character silhouettes; with despill it cleans the halo while preserving
    art.

    A pixel is preserved (not zeroed) when:
      diff <= threshold (i.e. nominally background) AND
      color_balance(max-min RGB) > 20 * despill_strength

    `color_balance` is large for "saturated, distinct" colors and small for
    pure magenta-ish pixels. Set `despill_strength=0` to disable.
    """
    img = img.convert("RGBA")
    if not HAS_NUMPY:
        # Without numpy this would be very slow; skip pass 2 in pure-Python mode
        return img

    arr = np.array(img)
    h, w = arr.shape[:2]
    visited = np.zeros((h, w), dtype=bool)
    chroma_arr = np.array(chroma)

    queue: deque[tuple[int, int]] = deque()
    for y in (0, h - 1):
        for x in range(w):
            queue.append((y, x))
    for x in (0, w - 1):
        for y in range(h):
            queue.append((y, x))

    # Despill: a pixel is "off the magenta axis" when its chroma-orthogonal
    # channel (green for magenta) is closer to the off-axis channels (R, B)
    # than expected for true magenta. For magenta=(255,0,255), the off-axis
    # channel is green; pure-magenta pixels have G near 0 and R, B near 255.
    # Spill pixels (character art tinted by magenta) have G high relative to
    # the on-axis channels: a TRUE character pixel has G close to or higher
    # than R+B/2; a halo pixel has G << R+B/2.
    despill_lift_cutoff = int(80 * despill_strength)

    def is_off_axis(rgb_arr: np.ndarray) -> bool:
        """Return True if this pixel is off the chroma axis (preserve as character).

        For magenta=(255,0,255): a character pixel has its OFF-AXIS channel (G)
        lifted toward the ON-AXIS channels (R, B). The "off-axis lift ratio" is
        G compared to (R+B)/2; if G is at least `despill_lift_cutoff` of (R+B)/2,
        the pixel is sufficiently de-magenta to count as character.

        At cutoff=40 (default 0.5 strength * 80): G must be at least 40 less
        than (R+B)/2 to be classified as halo. Halo pixels like (252,33,219)
        have (R+B)/2=235, gap=235-33=202 → not preserved (halo).
        Character pixels like skin (220,130,100) have (R+B)/2=160, gap=30 →
        preserved (character).
        """
        r_, g_, b_ = int(rgb_arr[0]), int(rgb_arr[1]), int(rgb_arr[2])
        if chroma == (255, 0, 255):
            on_axis_avg = (r_ + b_) / 2
            gap = on_axis_avg - g_
            # Pixel is off-axis (character) if gap from on-axis avg to G is small.
            return gap < despill_lift_cutoff
        # Generic fallback: deviations from chroma color.
        deviations = [abs(p - c) for p, c in zip((r_, g_, b_), chroma)]
        return max(deviations) >= despill_lift_cutoff

    while queue:
        y, x = queue.popleft()
        if not (0 <= y < h and 0 <= x < w):
            continue
        if visited[y, x]:
            continue
        if arr[y, x, 3] == 0:
            visited[y, x] = True
            for dy, dx in ((-1, 0), (1, 0), (0, -1), (0, 1)):
                queue.append((y + dy, x + dx))
            continue
        rgb = arr[y, x, :3].astype(int)
        diff = int(np.abs(rgb - chroma_arr).sum())
        if diff > threshold:
            continue
        # Despill: a pixel that nominally matches the bg threshold but has
        # significant off-axis lift (e.g. green channel for magenta-bg) is
        # character spill. Preserve it.
        if despill_strength > 0 and arr[y, x, 3] > 128 and is_off_axis(rgb):
            visited[y, x] = True
            continue
        visited[y, x] = True
        arr[y, x, 3] = 0
        for dy, dx in ((-1, 0), (1, 0), (0, -1), (0, 1)):
            queue.append((y + dy, x + dx))

    return Image.fromarray(arr, "RGBA")


def dilate_alpha_zero(arr: np.ndarray, radius: int = DEFAULT_ALPHA_DILATE_RADIUS) -> np.ndarray:
    """Expand the alpha=0 region by `radius` pixels (4-connected dilation).

    Kills the 1-pixel halo that survives even pass-2 flood-fill on
    anti-aliased generator output. Pure numpy, no scipy. The 4-connected
    shifted-OR is correct for radius=1; iterate for larger radii.
    """
    if radius <= 0:
        return arr
    alpha = arr[..., 3]
    mask = alpha == 0
    for _ in range(radius):
        shifted = np.zeros_like(mask)
        shifted[1:, :] |= mask[:-1, :]
        shifted[:-1, :] |= mask[1:, :]
        shifted[:, 1:] |= mask[:, :-1]
        shifted[:, :-1] |= mask[:, 1:]
        mask = mask | shifted
    arr[..., 3] = np.where(mask, 0, alpha)
    return arr


def color_despill_magenta(arr: np.ndarray) -> np.ndarray:
    """VFX-style despill: bleach magenta tint from semi-transparent silhouette.

    For magenta=(255,0,255), a pixel at the silhouette has high R, low G,
    high B (pink). Despill clamps R and B to max(G, R, B) when G < min(R, B):
    in practice, set R = min(R, max(G, B-margin)) so the pink fringe gets
    pulled toward neutral.

    This runs AFTER pass-2 alpha masking so it only touches non-zero alpha
    pixels (the surviving fringe).
    """
    rgb = arr[..., :3].astype(int)
    r = rgb[..., 0]
    g = rgb[..., 1]
    b = rgb[..., 2]
    # A pixel "leans magenta" when both R and B are higher than G by a margin.
    # We pull R and B down toward G (kills the pink/magenta tint).
    leans_magenta = (r > g + 10) & (b > g + 10) & (arr[..., 3] > 0) & (arr[..., 3] < 255)
    # Cap R and B at a value that keeps the pixel hue-balanced
    cap = np.maximum(g, np.minimum(r, b))
    new_r = np.where(leans_magenta, np.minimum(r, cap + 30), r)
    new_b = np.where(leans_magenta, np.minimum(b, cap + 30), b)
    arr[..., 0] = np.clip(new_r, 0, 255).astype(np.uint8)
    arr[..., 2] = np.clip(new_b, 0, 255).astype(np.uint8)
    return arr


def kill_pink_fringe(arr: np.ndarray, alpha_ceiling: int = 220) -> np.ndarray:
    """Zero alpha on semi-transparent pink-cast pixels at the silhouette edge.

    The despill chain (chroma_pass2_edge_flood + color_despill_magenta +
    alpha_fade_magenta_fringe + dilate_alpha_zero) leaves a residual class of
    fringe pixels that survive because their per-pixel color spread is high
    enough to look like saturated character art (despill protects them) yet
    they sit exactly at the anti-aliased silhouette boundary with non-full
    alpha. Visually, these read as a pink halo or wisp.

    The wide pink criterion catches them: R > 130 AND B > 120 AND G < 80
    AND R - G > 50 AND B - G > 40. Restricting the kill to alpha < 220
    ensures we only touch edge pixels — full-opacity character art (e.g. a
    purple costume center, alpha 255) is preserved.

    Tuning:
      alpha_ceiling=220 (default): only edge pixels with anti-aliased alpha.
      alpha_ceiling=255: also kill fully-opaque pink — DANGEROUS; can erase
        intentional pink/magenta costume art. Don't raise without verifying.
      alpha_ceiling=180: more conservative; preserves more fringe.

    Pure numpy. ~5ms / 1024px image.
    """
    rgb = arr[..., :3].astype(int)
    r = rgb[..., 0]
    g = rgb[..., 1]
    b = rgb[..., 2]
    alpha = arr[..., 3]
    pink_cast = (
        (r > 130) & (b > 120) & (g < 80) & ((r - g) > 50) & ((b - g) > 40) & (alpha > 0) & (alpha < alpha_ceiling)
    )
    arr[pink_cast, 3] = 0
    return arr


def neutralize_interior_magenta_spill(arr: np.ndarray) -> np.ndarray:
    """Recolor full-opacity pink-cast pixels INSIDE the silhouette toward neutral.

    Distinct from `kill_pink_fringe` (edge alpha-kill) and from
    `color_despill_magenta` (semi-transparent fringe color clamp). This
    targets the case where the generator painted PINK-CAST pixels INSIDE
    the character silhouette (typically inside dark hair or shadow
    regions), where R is high, G is low, B is moderate-high. Visually a
    pink streak or wisp inside dark hair.

    Two-tier criterion (tightened to protect intentional costume color):

    Tier A — pure magenta cast:
      R >= 200 AND B >= 200 AND G <= 80 AND R-G > 120 AND B-G > 120
      Catches near-pure (255,0,255)-cast pixels.

    Tier B — moderate pink cast WITH B > R*0.6 (so it's not just orange/red):
      R >= 150 AND G <= 80 AND B >= 90 AND R-G > 90 AND B-G > 50
      AND B*1.4 >= R   (pink/magenta hue, not red)
      Catches the (233, 56, 165) class of "diluted spill into hair" that
      Tier A misses because B=165 < 200.

    Both tiers require alpha == 255 to skip edge anti-aliased pixels.

    Costume protection examples (all preserved):
    - Magenta showman shorts (190, 20, 190): R=190 < 200 (fails A), B=190 OK
      (B*1.4=266 >= R=190) — but R<150? No, R=190. So Tier B catches it!
      That's a problem — magenta costumes ARE pink. Mitigation: the criterion
      catches pixels that look "like background bleed", not "like a magenta
      costume". A magenta costume painting has SHADING and varied saturation;
      a few pixels recolored is invisible. The skill prompts for non-magenta
      costumes anyway, and where magenta IS used (showman archetype), users
      should accept this as a known limitation logged in
      `references/bg-removal-local.md`.
    - Purple suit highlights (180, 80, 200): G=80 fails (G<=80, so passes B).
      B*1.4=280 >= R=180. R-G=100>90. B-G=120>50. → Tier B fires.
      Recolor to (80, 80, 80) which DESTROYS the purple suit. So we need a
      tighter B-vs-R relationship: PURE pink has B ≈ R, purple has B > R*1.1.
      Add: AND B <= R*1.05  (pink: B ≈ R; reject purple: B much higher).
      Re-check examples:
        - (233, 56, 165): B/R = 0.71 → passes (it's pink/red, not purple)
        - (180, 80, 200): B/R = 1.11 → REJECTED (it's purple, leave alone)
        - magenta (255, 0, 255): B/R = 1.0 → passes
        - showman pink (250, 50, 230): B/R = 0.92 → passes
        - manager suit (150, 30, 180): B/R = 1.20 → REJECTED (purple)

    Recoloring strategy: pull R and B down to G — neutralizes hue while
    preserving brightness of G (hair stays dark, highlights stay brighter).

    Pure numpy. ~10ms / 1024px image.
    """
    rgb = arr[..., :3].astype(int)
    r = rgb[..., 0]
    g = rgb[..., 1]
    b = rgb[..., 2]
    alpha = arr[..., 3]
    # Tier A: near-pure magenta cast inside silhouette (G strict <=80).
    # Loosened r-g and b-g from >120 to >100 so pixels like (209,90,217)
    # at r-g=119 still get neutralized.
    tier_a = (r >= 200) & (b >= 200) & (g <= 100) & ((r - g) > 100) & ((b - g) > 100) & (alpha == 255)
    # Tier B: moderate pink cast (catches diluted spill that GIF dithered).
    # Loosened from r>=150,g<=80 to r>=130,g<=100 so darker pinks like
    # (149,6,123) and shaded magentas like (234,93,208) on full-opacity
    # interior pixels are recolored. Critical: B <= R*1.10 distinguishes
    # pink/magenta (B near R) from purple (B much higher). Costume protect:
    # purple suit (180,80,200) has B/R=1.11 → still rejected.
    tier_b = (
        (r >= 130)
        & (g <= 100)
        & (b >= 90)
        & ((r - g) > 90)
        & ((b - g) > 50)
        & (b * 100 <= r * 110)  # pink hue, not purple (B near or below R)
        & (alpha == 255)
    )
    pink_inside = tier_a | tier_b
    # Pull R and B down to G — neutralizes hue while preserving brightness
    arr[..., 0] = np.where(pink_inside, g.astype(np.uint8), arr[..., 0])
    arr[..., 2] = np.where(pink_inside, g.astype(np.uint8), arr[..., 2])
    return arr


def matte_composite(img: Image.Image, matte: tuple[int, int, int] = (40, 40, 40)) -> Image.Image:
    """Blend an RGBA image over a neutral matte color and return RGB.

    Used BEFORE GIF palette quantization. The 1-bit-alpha + adaptive 256-
    color GIF format reintroduces magenta-tinted edges at the silhouette
    even when the RGBA source is clean — the adaptive palette allocates
    indices for pink fringe pixels and the quantizer rounds nearby
    anti-aliased pixels to those entries. Pre-mattering over a neutral
    middle-gray (default 40,40,40) gives the quantizer no pink reference
    to lock onto: anti-aliased pixels blend to neutral gray instead of
    pink/plum, the palette stays neutral, and surviving GIF edges look
    like dark gray (visually neutral) instead of pink.

    The matte color choice matters. Brighter mattes (e.g. 128,128,128) wash
    out the silhouette against a dark page bg. Pure black (0,0,0) shows up
    as a hard edge against any non-black page. Middle-gray (40,40,40)
    matches typical dark-theme page bgs (~#181a21 to #2a2a2e) closely
    enough to disappear, while still desaturating the fringe.
    """
    img = img.convert("RGBA")
    bg = Image.new("RGB", img.size, matte)
    bg.paste(img, (0, 0), img)
    return bg


def alpha_fade_magenta_fringe(arr: np.ndarray, threshold: int = 130) -> np.ndarray:
    """Flood-zero pink/magenta-leaning regions connected to alpha=0.

    Strategy: classify each opaque pixel as "pink-leaning" or not. Then flood
    from the alpha=0 boundary INTO connected pink-leaning regions, zeroing
    them. This kills entire halo blobs (any thickness) without eroding into
    non-pink character pixels — the flood stops as soon as it hits
    non-pink-leaning pixels.

    Pink-leaning rule:
      (a) "Saturated pink/magenta": R > 180, B > 100, R+B-2G > 180
      (b) "Near-magenta": weighted distance (R + 2G + B)-space < threshold
    """
    rgb = arr[..., :3].astype(int)
    r = rgb[..., 0]
    g = rgb[..., 1]
    b = rgb[..., 2]
    alpha = arr[..., 3]
    chroma = np.array((255, 0, 255), dtype=int)
    weighted = np.abs(r - chroma[0]) + 2 * np.abs(g - chroma[1]) + np.abs(b - chroma[2])
    pink_leaning = ((r > 180) & (b > 100) & ((r + b - 2 * g) > 180)) | (weighted < threshold)

    # Iterative dilation flood: at each step, mark as fringe any opaque-pink
    # pixel adjacent to a fringe pixel (or alpha=0). Stop when no new pixels
    # are marked (or after a sane upper bound).
    cur_alpha = alpha.copy()
    for _ in range(20):
        zero_mask = cur_alpha == 0
        # 4-connected expansion of zero_mask
        adj = np.zeros_like(zero_mask)
        adj[1:, :] |= zero_mask[:-1, :]
        adj[:-1, :] |= zero_mask[1:, :]
        adj[:, 1:] |= zero_mask[:, :-1]
        adj[:, :-1] |= zero_mask[:, 1:]
        new_zero = (cur_alpha > 0) & adj & pink_leaning
        if not new_zero.any():
            break
        cur_alpha = np.where(new_zero, 0, cur_alpha)
    arr[..., 3] = cur_alpha
    return arr


def remove_bg_chroma(
    input_path: Path,
    output_path: Path,
    threshold: int,
    pass2_threshold: int | None = None,
    despill_strength: float = DEFAULT_DESPILL_STRENGTH,
    alpha_dilate_radius: int = DEFAULT_ALPHA_DILATE_RADIUS,
) -> None:
    """Two-pass despill-aware chroma key + alpha-fade + dilation.

    pass1: tight match to chroma color (default threshold=30) — catches the
        bulk solid magenta.
    pass2: edge flood with looser threshold (default 90) and despill — catches
        feathered fringe without biting into character interior.
    fringe-fade: any remaining pixels close to magenta in weighted-RGB space
        get their alpha attenuated proportionally (kills the visible pink halo).
    color-despill: bleach magenta tint out of remaining semi-opaque pixels.
    dilate: expand alpha=0 by 1 px so the 1-pixel residual halo at the
        silhouette is removed.
    """
    if pass2_threshold is None:
        pass2_threshold = DEFAULT_PASS2_THRESHOLD
    img = Image.open(input_path)
    pass1 = chroma_pass1(img, MAGENTA, threshold)
    pass2 = chroma_pass2_edge_flood(
        pass1,
        MAGENTA,
        pass2_threshold,
        despill_strength=despill_strength,
    )
    if HAS_NUMPY:
        arr = np.array(pass2.convert("RGBA"))
        # Fringe alpha-fade: kill remaining pink halo by attenuating alpha
        # in proportion to magenta-distance.
        arr = alpha_fade_magenta_fringe(arr, threshold=130)
        # Color despill: bleach the magenta tint out of surviving fringe pixels.
        arr = color_despill_magenta(arr)
        # Interior spill: neutralize full-opacity PURE-magenta pixels the
        # generator painted INSIDE the silhouette (e.g. pink streaks in
        # dark hair). Must run BEFORE kill_pink_fringe so the recolored
        # pixels don't get re-classified as fringe.
        arr = neutralize_interior_magenta_spill(arr)
        # Alpha dilation: expand alpha=0 region to kill 1-px residual halo.
        if alpha_dilate_radius > 0:
            arr = dilate_alpha_zero(arr, alpha_dilate_radius)
        # Final pink-fringe kill: zero alpha on semi-transparent pink-cast
        # pixels that despill protected as "saturated". See bg-removal-local.md
        # "GIF format bleed at silhouette edges" for the full rationale.
        arr = kill_pink_fringe(arr)
        pass2 = Image.fromarray(arr, "RGBA")
    output_path.parent.mkdir(parents=True, exist_ok=True)
    pass2.save(output_path, format="PNG")


# Adapted from ~/road-to-aew/scripts/generate_enemy_sprite.py lines 1048-1128
# (`remove_watermark` + `make_background_transparent`). road-to-aew has produced
# 87 clean transparent PNGs in production with this algorithm. Used here as
# the secondary backend for image generators that paint a gray background
# (Gemini Nano Banana) instead of honoring our magenta-bg prompt.
def remove_watermark_corners(
    img: Image.Image,
    bg_color: tuple[int, int, int],
    margin: int,
    brightness_threshold: int = WATERMARK_BRIGHTNESS_THRESHOLD,
) -> Image.Image:
    """Replace bright corner pixels with bg_color so they get masked later."""
    img = img.convert("RGBA")
    if not HAS_NUMPY:
        # Slow path: per-pixel
        pixels = img.load()
        w, h = img.size
        corner_boxes = [
            (0, 0, margin, margin),
            (w - margin, 0, w, margin),
            (0, h - margin, margin, h),
            (w - margin, h - margin, w, h),
        ]
        for x1, y1, x2, y2 in corner_boxes:
            for y in range(max(0, y1), min(h, y2)):
                for x in range(max(0, x1), min(w, x2)):
                    r, g, b, _ = pixels[x, y]
                    if (r + g + b) / 3 > brightness_threshold:
                        pixels[x, y] = (bg_color[0], bg_color[1], bg_color[2], 255)
        return img
    arr = np.array(img)
    h, w = arr.shape[:2]
    brightness = arr[..., :3].mean(axis=-1)
    corner_mask = np.zeros((h, w), dtype=bool)
    m = min(margin, h, w)
    corner_mask[:m, :m] = True
    corner_mask[:m, w - m :] = True
    corner_mask[h - m :, :m] = True
    corner_mask[h - m :, w - m :] = True
    bright_corners = corner_mask & (brightness > brightness_threshold)
    arr[bright_corners, 0] = bg_color[0]
    arr[bright_corners, 1] = bg_color[1]
    arr[bright_corners, 2] = bg_color[2]
    arr[bright_corners, 3] = 255
    return Image.fromarray(arr, "RGBA")


def gray_tolerance_to_alpha(
    img: Image.Image,
    bg_color: tuple[int, int, int],
    tolerance: int,
) -> Image.Image:
    """Set alpha=0 for any pixel within `tolerance` of `bg_color` (per channel)."""
    img = img.convert("RGBA")
    if not HAS_NUMPY:
        pixels = img.load()
        w, h = img.size
        for y in range(h):
            for x in range(w):
                r, g, b, a = pixels[x, y]
                if (
                    abs(r - bg_color[0]) <= tolerance
                    and abs(g - bg_color[1]) <= tolerance
                    and abs(b - bg_color[2]) <= tolerance
                ):
                    pixels[x, y] = (r, g, b, 0)
        return img
    arr = np.array(img)
    rgb = arr[..., :3].astype(int)
    bg_arr = np.array(bg_color, dtype=int)
    within = np.all(np.abs(rgb - bg_arr) <= tolerance, axis=-1)
    arr[within, 3] = 0
    return Image.fromarray(arr, "RGBA")


def remove_bg_gray_tolerance(
    input_path: Path,
    output_path: Path,
    bg_color: tuple[int, int, int] = GRAY_BG_DEFAULT,
    tolerance: int = GRAY_BG_TOLERANCE_DEFAULT,
    watermark_margin: int = WATERMARK_MARGIN_DEFAULT,
    alpha_dilate_radius: int = DEFAULT_ALPHA_DILATE_RADIUS,
) -> None:
    """road-to-aew's algorithm: watermark-corner clean + gray-tolerance alpha.

    Step 1: bright pixels in the four corner boxes get repainted to bg_color
        (kills Gemini's watermark before the mask sees it).
    Step 2: any pixel within `tolerance` of bg_color (per-channel abs-diff)
        gets alpha=0.
    Step 3: alpha dilation by 1 px (kills 1-pixel halo).
    """
    img = Image.open(input_path)
    cleaned = remove_watermark_corners(img, bg_color, watermark_margin)
    transparent = gray_tolerance_to_alpha(cleaned, bg_color, tolerance)
    if HAS_NUMPY and alpha_dilate_radius > 0:
        arr = np.array(transparent.convert("RGBA"))
        arr = dilate_alpha_zero(arr, alpha_dilate_radius)
        transparent = Image.fromarray(arr, "RGBA")
    output_path.parent.mkdir(parents=True, exist_ok=True)
    transparent.save(output_path, format="PNG")


def remove_bg_rembg(input_path: Path, output_path: Path) -> None:
    """rembg fallback for non-magenta backgrounds. Opt-in dep."""
    try:
        from rembg import remove
    except ImportError as e:
        raise RuntimeError(
            "rembg not installed. Run `pip install rembg onnxruntime`, or use --bg-mode chroma (default)."
        ) from e

    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_bytes(remove(input_path.read_bytes()))


def cmd_remove_bg(args: argparse.Namespace) -> int:
    inputs = [Path(p) for p in args.input]
    output_dir = Path(args.output_dir) if args.output_dir else None
    if len(inputs) > 1 and output_dir is None:
        logger.error("--output-dir required when processing multiple inputs")
        return 2

    bg_mode = args.bg_mode

    for src in inputs:
        if output_dir:
            dst = output_dir / src.name
        else:
            dst = Path(args.output) if args.output else src.with_suffix(".nobg.png")

        try:
            # Dispatch on bg_mode against the unified ADR-204 vocabulary:
            # chroma | gray-tolerance | rembg | auto. The legacy `magenta`
            # alias was dropped — `chroma` (with the default magenta matte)
            # is the only spelling.
            if bg_mode == "chroma":
                remove_bg_chroma(
                    src,
                    dst,
                    args.chroma_threshold,
                    pass2_threshold=args.pass2_threshold,
                    despill_strength=args.despill_strength,
                    alpha_dilate_radius=args.alpha_dilate,
                )
            elif bg_mode == "gray-tolerance":
                remove_bg_gray_tolerance(
                    src,
                    dst,
                    bg_color=tuple(args.gray_bg),
                    tolerance=args.gray_tolerance,
                    watermark_margin=args.watermark_margin,
                    alpha_dilate_radius=args.alpha_dilate,
                )
            elif bg_mode == "rembg":
                remove_bg_rembg(src, dst)
            elif bg_mode == "auto":
                # try chroma; if alpha mask is suspiciously small, fall through to rembg
                remove_bg_chroma(
                    src,
                    dst,
                    args.chroma_threshold,
                    pass2_threshold=args.pass2_threshold,
                    despill_strength=args.despill_strength,
                    alpha_dilate_radius=args.alpha_dilate,
                )
                if _alpha_coverage_too_low(dst):
                    logger.warning("[remove-bg] auto: chroma low-coverage; falling back to rembg for %s", src.name)
                    remove_bg_rembg(src, dst)
            else:
                logger.error("unknown bg-mode %r", bg_mode)
                return 2
        except RuntimeError as e:
            logger.error("%s", e)
            return 4
        logger.info("[remove-bg] %s -> %s (bg-mode=%s)", src, dst, bg_mode)
    return 0


def _alpha_coverage_too_low(path: Path) -> bool:
    """Return True if the alpha-mask coverage is below 30% of canvas."""
    img = Image.open(path).convert("RGBA")
    if HAS_NUMPY:
        arr = np.array(img)
        opaque = (arr[..., 3] > 0).sum()
        total = arr.shape[0] * arr.shape[1]
        return (opaque / total) < 0.3
    return False  # without numpy we don't run auto mode anyway
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall