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 md14.7 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/combat-effects-upgrade.mdmarkdown13.3 KB
references/combat-effects-upgrade/css-3d-card-transforms.mdmarkdown10.1 KB
references/combat-effects-upgrade/css-particle-migration.mdmarkdown13.3 KB
references/combat-effects-upgrade/framer-motion-combat-juice.mdmarkdown11.9 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.6 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.5 KB
references/pixel-art-sprites.mdmarkdown8.7 KB
references/pixijs-combat-renderer.mdmarkdown12.1 KB
references/pixijs-combat-renderer/combat-visual-effects.mdmarkdown7.8 KB
references/pixijs-combat-renderer/pixi-2d-lighting.mdmarkdown6.6 KB
references/pixijs-combat-renderer/pixi-particle-systems.mdmarkdown9.2 KB
references/pixijs-combat-renderer/pixi-performance.mdmarkdown4.8 KB
references/pixijs-combat-renderer/pixi-post-processing.mdmarkdown6.3 KB
references/pixijs-combat-renderer/pixi-react-integration.mdmarkdown5.2 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/rive-skeletal-animator.mdmarkdown7.6 KB
references/rive-skeletal-animator/rive-animation-library.mdmarkdown8.1 KB
references/rive-skeletal-animator/rive-async-patterns.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-character-pipeline.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-performance.mdmarkdown5.4 KB
references/rive-skeletal-animator/rive-react-setup.mdmarkdown9.9 KB
references/rive-skeletal-animator/rive-vs-spine-decision.mdmarkdown6.0 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_anchor.py

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

Owns alpha-bbox + ground-line + mass-centroid anchor math, the height
percentile + rescale helpers, the canvas-paste anchor router, and the
portrait/spritesheet normalize CLI subcommands. No bg-removal logic —
those primitives live in `sprite_bg.py`. No slicer logic — that lives
in `sprite_slicing.py`.

Public surface (re-exported through `sprite_process` for backward compat):
    Constants:
        PORTRAIT_WIDTH_RANGE, PORTRAIT_HEIGHT_RANGE, PORTRAIT_ASPECT_MIN,
        PORTRAIT_ASPECT_MAX, DEFAULT_BOTTOM_MARGIN.
    Bbox / centroid:
        find_bottom_anchor, find_alpha_bbox, find_alpha_mass_centroid,
        trim_to_bbox.
    Anchor application:
        apply_mass_centroid_anchor, apply_ground_line_anchor,
        anchor_to_canvas.
    Anchor detection (batch):
        detect_centroid_y_target, detect_ground_line, shared_scale_height.
    Resampling helpers:
        rescale_to_height.
    Pipeline functions:
        normalize_portrait, normalize_spritesheet.
    CLI:
        cmd_normalize, cmd_validate_portrait.
"""

from __future__ import annotations

import argparse
import json
import logging
import sys
from pathlib import Path

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

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
# ---------------------------------------------------------------------------
PORTRAIT_WIDTH_RANGE = (350, 850)
PORTRAIT_HEIGHT_RANGE = (900, 1100)
PORTRAIT_ASPECT_MIN = 1.5  # height / width
PORTRAIT_ASPECT_MAX = 2.5
DEFAULT_BOTTOM_MARGIN = 8


# ---------------------------------------------------------------------------
# Normalization (portrait Phase C / spritesheet Phase F)
# ---------------------------------------------------------------------------
def find_bottom_anchor(img: Image.Image) -> int:
    """Return y-coordinate of lowest non-transparent pixel."""
    if HAS_NUMPY:
        arr = np.array(img.convert("RGBA"))
        alpha = arr[..., 3]
        has_pixel = alpha.max(axis=1) > 0
        nonzero = np.where(has_pixel)[0]
        if len(nonzero) == 0:
            return img.height
        return int(nonzero.max())

    pixels = img.convert("RGBA").load()
    w, h = img.size
    for y in range(h - 1, -1, -1):
        for x in range(w):
            if pixels[x, y][3] > 0:
                return y
    return img.height


def find_alpha_bbox(img: Image.Image) -> tuple[int, int, int, int] | None:
    """Return (top, bot, left, right) bbox of all non-transparent pixels.

    Differs from PIL's getbbox in that it walks alpha explicitly (not all
    color channels), which is important after bg-removal when low-alpha
    fringe pixels survive.
    """
    if HAS_NUMPY:
        arr = np.array(img.convert("RGBA"))
        alpha = arr[..., 3]
        ys, xs = np.where(alpha > 0)
        if len(ys) == 0:
            return None
        return int(ys.min()), int(ys.max()), int(xs.min()), int(xs.max())
    bbox = img.convert("RGBA").getbbox()
    if bbox is None:
        return None
    left, top, right, bot = bbox
    return top, bot - 1, left, right - 1


def find_alpha_mass_centroid(img: Image.Image) -> tuple[float, float] | None:
    """Return (cx, cy) of alpha-mass centroid (alpha-weighted X and Y means).

    Why this is the load-bearing primitive for anchor v8: bbox-bottom is
    dominated by extended-limb pixels (mic, raised arm, kicking leg).
    The mass centroid integrates over ALL opaque pixels, so a single limb
    extension only shifts it by a few pixels, not 30+. Empirically (live
    demo 05 powerhouse): bbox-bottom-Y stddev=0px (we already pin it),
    centroid-Y stddev=15.84px under bbox-bottom anchor — that 15.84px is
    the visible "hop" the user reported. Pinning the centroid instead
    drops centroid-Y stddev to <2px because the centroid IS the quantity
    being held constant.

    Returns None when there is no opaque content (alpha sum < 1.0).
    """
    if not HAS_NUMPY:
        return None
    arr = np.array(img.convert("RGBA"))
    alpha = arr[..., 3].astype(float)
    if alpha.sum() < 1.0:
        return None
    h, w = alpha.shape
    ys = np.arange(h).reshape(-1, 1).astype(float)
    xs = np.arange(w).reshape(1, -1).astype(float)
    cy = float((alpha * ys).sum() / alpha.sum())
    cx = float((alpha * xs).sum() / alpha.sum())
    return cx, cy


def apply_mass_centroid_anchor(
    frame: Image.Image,
    centroid_y_target: int,
    cell_w: int,
    cell_h: int,
) -> Image.Image:
    """Translate `frame` so its alpha-mass-centroid Y lands at `centroid_y_target`.

    Counterpart to apply_ground_line_anchor but uses the mass centroid as the
    quantity held constant across the batch. Frames where the bbox-bottom is
    a fist or an extended leg still anchor cleanly because the mass centroid
    represents the "body trunk" — limb extensions only nudge it by a few
    pixels, not the dozens that bbox-bottom shifts. Result: the trunk stays
    planted; limb extensions look like motion against a stable body.

    Horizontal: center the mass centroid X on the cell's vertical axis.

    Fit-to-cell scaling (ADR-208 RC-4): if the post-translation bbox would
    overflow the canvas (paste_y + bbox_top < 0, or paste_y + bbox_bot >=
    cell_h), the frame is rescaled to fit. Without this, content gets
    clipped at the canvas edge AND the resulting visible centroid shifts
    away from `centroid_y_target` (because clipping the upper or lower
    pixels biases the centroid toward the surviving side). The pre-fix
    bug measured centroid stddev 14.6 px on the canonical
    luchadora-highflyer/05-specials sample because tall full-bbox frames
    (bbox spanning 240 of 256 px) translated past the canvas top, lost
    their upper content to clipping, and the surviving content's centroid
    drifted 25-30 px below the target. This rescale closes that path.
    """
    out = Image.new("RGBA", (cell_w, cell_h), (0, 0, 0, 0))
    centroid = find_alpha_mass_centroid(frame)
    if centroid is None:
        return out
    cx, cy = centroid
    paste_x = (cell_w / 2) - cx
    paste_y = centroid_y_target - cy

    # Fit-to-cell: rescale if the frame's bbox would overflow the canvas
    # AT the chosen translation. We check both the bbox dimension (frame
    # is bigger than cell) AND the post-translation overflow (centroid
    # position forces the bbox past a canvas edge). The second condition
    # is the ADR-208 RC-4 fix: tall full-bbox frames whose centroid sits
    # below cell-center overflow the canvas top, lose pixels to clipping,
    # and the surviving content's centroid no longer matches the target.
    bbox = find_alpha_bbox(frame)
    if bbox is not None:
        top, bot, left, right = bbox
        bbox_h = bot - top + 1
        bbox_w = right - left + 1
        # Translated bbox extents in canvas coords:
        translated_top = paste_y + top
        translated_bot = paste_y + bot
        translated_left = paste_x + left
        translated_right = paste_x + right
        scale = 1.0
        # Frame larger than cell: scale to fit.
        if bbox_h > cell_h or bbox_w > cell_w:
            scale = min(cell_h / max(bbox_h, 1), cell_w / max(bbox_w, 1))
        # Translated bbox overflows canvas: rescale by the overflow ratio
        # so the bbox fits AROUND the centroid target. Compute the
        # required scale separately for top and bottom overflow then take
        # the more restrictive. The bbox after scale must satisfy:
        #   centroid_y_target - cy_scaled + top_scaled >= 0
        #   centroid_y_target - cy_scaled + bot_scaled < cell_h
        # which simplifies (since cy = (top+bot)/2-ish for symmetric bbox
        # and cy and top/bot all scale by `scale`) to:
        #   scale <= centroid_y_target / (cy - top)  (top edge)
        #   scale <= (cell_h - centroid_y_target) / (bot - cy)  (bot edge)
        if cy - top > 0:
            top_scale = centroid_y_target / (cy - top)
            if top_scale < scale:
                scale = top_scale
        if bot - cy > 0:
            bot_scale = (cell_h - 1 - centroid_y_target) / (bot - cy)
            if bot_scale < scale:
                scale = bot_scale
        # Horizontal overflow: rescale so the bbox X extents fit either
        # side of the cell horizontal center.
        if cx - left > 0:
            left_scale = (cell_w / 2) / (cx - left)
            if left_scale < scale:
                scale = left_scale
        if right - cx > 0:
            right_scale = (cell_w / 2) / (right - cx)
            if right_scale < scale:
                scale = right_scale
        if scale < 1.0:
            new_w = max(1, int(frame.width * scale))
            new_h = max(1, int(frame.height * scale))
            frame = frame.resize((new_w, new_h), Image.Resampling.LANCZOS)
            centroid = find_alpha_mass_centroid(frame)
            if centroid is None:
                return out
            cx, cy = centroid
            paste_x = (cell_w / 2) - cx
            paste_y = centroid_y_target - cy
        # Suppress unused-variable warnings for the translated_* values:
        # they're computed for documentation / future-debug inspection.
        del translated_top, translated_bot, translated_left, translated_right

    out.paste(frame, (round(paste_x), round(paste_y)), frame)
    return out


def detect_centroid_y_target(
    frames: list[Image.Image],
    cell_h: int,
    fallback_pct: float = 0.55,
) -> int:
    """Return the Y at which mass centroids should sit for drift-free anchoring.

    Uses the median centroid Y across all frames with content (not just
    grounded ones). For walk cycles + idle loops the centroid stays in a
    tight band; for action cycles the median is the "rest pose" centroid
    and outlier frames (e.g. a leap) get translated relative to that
    stable Y.

    Falls back to `cell_h * fallback_pct` when there is no opaque content.
    """
    cys: list[float] = []
    for fr in frames:
        c = find_alpha_mass_centroid(fr)
        if c is not None:
            cys.append(c[1])
    if not cys:
        return int(cell_h * fallback_pct)
    cys.sort()
    return int(cys[len(cys) // 2])


def detect_ground_line(
    frames: list[Image.Image],
    cell_h: int,
    bottom_zone_pct: float = 0.30,
    fallback_percentile: float = 75.0,
) -> int:
    """Detect a globally-stable ground line across all frames.

    Algorithm:

    1. For each frame, find its largest connected component (alpha > 0).
       (Using the bbox-bottom of all non-transparent pixels is a good-enough
       proxy when frames have already been bg-removed and contain only one
       character per cell.)
    2. Among the frames whose bbox-bottom falls within the lower
       `bottom_zone_pct` of the cell (default lower 30%), take the median
       bbox-bottom-Y. These are the "feet-on-ground" frames; the median is
       robust to a handful of outliers (a frame where the model drew the
       character one pixel higher than the rest).
    3. Fallback: if NO frame's bbox-bottom is in the lower zone (rare —
       implies every frame is aerial), return the `fallback_percentile`-th
       percentile of all bbox-bottom-Ys.

    Returns the Y coordinate (in cell-canvas space) at which the character's
    lowest grounded pixel typically sits. Each frame is later translated so
    its bbox-bottom lands AT this Y, which keeps the visual ground steady
    across the animation cycle.

    See `references/anchor-alignment.md` for the per-frame vs global trade-off.
    """
    if not frames:
        return cell_h - DEFAULT_BOTTOM_MARGIN

    bottoms: list[int] = []
    for fr in frames:
        bbox = find_alpha_bbox(fr)
        if bbox is None:
            continue
        bottoms.append(bbox[1])

    if not bottoms:
        return cell_h - DEFAULT_BOTTOM_MARGIN

    # Frames whose bbox-bottom is in the lower 30% of the cell are the
    # feet-on-ground reference frames.
    threshold_y = int(cell_h * (1 - bottom_zone_pct))
    grounded_bottoms = [b for b in bottoms if b >= threshold_y]

    if grounded_bottoms:
        # Median: robust to a single-frame outlier where one feet pixel is
        # shifted by ±1 due to AA / chroma fringe artifact.
        sorted_b = sorted(grounded_bottoms)
        return sorted_b[len(sorted_b) // 2]

    # Pure-aerial sequence (every frame's bbox-bottom is high in the cell).
    # Use the 75th percentile of all bbox-bottoms — pins the lowest reach
    # consistently across the animation.
    sorted_all = sorted(bottoms)
    idx = min(len(sorted_all) - 1, int(len(sorted_all) * fallback_percentile / 100.0))
    return sorted_all[idx]


def apply_ground_line_anchor(
    frame: Image.Image,
    ground_line_y: int,
    cell_w: int,
    cell_h: int,
    horizontal_mode: str = "centroid",
) -> Image.Image:
    """Translate `frame` so its alpha-bbox-bottom lands at `ground_line_y`.

    Unlike per-frame bottom-anchor (which moves the FRAME bottom to the cell
    bottom — and thus the character moves with bbox-height), this places the
    CHARACTER'S OWN bottom-most pixel at a fixed, globally-stable Y. Result:
    feet stay planted; head bounces only when the actual silhouette changes.

    `horizontal_mode`:
      - `centroid` (default): center the alpha-mass centroid horizontally.
        Preferred for full-body characters where the center of mass should
        sit on the cell's vertical axis.
      - `bbox`: center the alpha-bbox horizontally (legacy behavior).
        Reasonable for symmetric stances; can drift on lunge frames where
        the bbox extends right but the center of mass is still in the middle.
    """
    out = Image.new("RGBA", (cell_w, cell_h), (0, 0, 0, 0))
    bbox = find_alpha_bbox(frame)
    if bbox is None:
        return out
    top, bot, left, right = bbox
    bbox_h = bot - top + 1
    bbox_w = right - left + 1

    # Vertical: translate so bbox bottom lands at ground_line_y.
    paste_y = ground_line_y - bot

    # Horizontal: center the bbox or centroid in the cell.
    if horizontal_mode == "centroid" and HAS_NUMPY:
        arr = np.array(frame.convert("RGBA"))
        alpha = arr[..., 3]
        ys, xs = np.where(alpha > 0)
        if len(xs) > 0:
            cx = int(xs.mean())
            paste_x = (cell_w // 2) - cx
        else:
            paste_x = (cell_w - frame.width) // 2
    else:
        # bbox-center horizontal
        bbox_cx = (left + right) // 2
        paste_x = (cell_w // 2) - bbox_cx

    # Fit-to-cell: if the frame's bbox is taller or wider than the cell after
    # translation, scale it down (preserve aspect) so it still fits. Rare but
    # possible when an aerial-leap frame extends way beyond the cell.
    scale = 1.0
    if bbox_h > cell_h or bbox_w > cell_w:
        scale = min(cell_h / max(bbox_h, 1), cell_w / max(bbox_w, 1))

    if scale < 1.0:
        new_w = max(1, int(frame.width * scale))
        new_h = max(1, int(frame.height * scale))
        frame = frame.resize((new_w, new_h), Image.Resampling.LANCZOS)
        # Recompute bbox in the scaled frame
        rescaled_bbox = find_alpha_bbox(frame)
        if rescaled_bbox is None:
            return out
        top, bot, left, right = rescaled_bbox
        paste_y = ground_line_y - bot
        if horizontal_mode == "centroid" and HAS_NUMPY:
            arr = np.array(frame.convert("RGBA"))
            alpha = arr[..., 3]
            ys, xs = np.where(alpha > 0)
            if len(xs) > 0:
                cx = int(xs.mean())
                paste_x = (cell_w // 2) - cx
            else:
                paste_x = (cell_w - frame.width) // 2
        else:
            bbox_cx = (left + right) // 2
            paste_x = (cell_w // 2) - bbox_cx

    out.paste(frame, (paste_x, paste_y), frame)
    return out


def trim_to_bbox(img: Image.Image) -> Image.Image:
    """Crop to non-transparent bounding box."""
    bbox = img.convert("RGBA").getbbox()
    if bbox is None:
        return img
    return img.crop(bbox)


def shared_scale_height(frames: list[Image.Image], percentile: float = 95) -> int:
    """Return target height = Nth percentile of frame heights."""
    heights = sorted(f.height for f in frames)
    if not heights:
        return 0
    idx = int(len(heights) * (percentile / 100.0))
    idx = min(max(idx, 0), len(heights) - 1)
    return heights[idx]


def rescale_to_height(img: Image.Image, target_h: int) -> Image.Image:
    aspect = img.width / max(img.height, 1)
    new_w = max(1, int(target_h * aspect))
    return img.resize((new_w, target_h), Image.Resampling.LANCZOS)


def anchor_to_canvas(
    frame: Image.Image,
    canvas_w: int,
    canvas_h: int,
    bottom_margin: int = DEFAULT_BOTTOM_MARGIN,
    anchor_mode: str = "bottom",
    ground_line_y: int | None = None,
    centroid_y_target: int | None = None,
) -> Image.Image:
    """Place frame on transparent canvas with anchor controlled by `anchor_mode`.

    Modes:
      - `bottom` (legacy per-frame): place this frame's lowest pixel at
        `canvas_h - bottom_margin`. Frames with different alpha-bottom Y
        produce visible bouncing — see `apply_ground_line_anchor` for the
        global alternative.
      - `center`: vertically center the frame on the canvas. Use for
        sequences where the character is genuinely off-ground throughout
        (jump-loop, fly).
      - `ground-line`: translate so the frame's alpha-bbox-bottom lands at
        `ground_line_y`. Caller must pre-compute `ground_line_y` via
        `detect_ground_line(frames, canvas_h)` once for the whole batch.
        Provides drift-free animation across mixed grounded/aerial poses
        AS LONG AS the bbox-bottom IS the feet on every frame -- which
        breaks down on sheets where the bbox-bottom is sometimes a fist
        (lunge) or an extended leg (kick). For those, use `mass-centroid`.
      - `mass-centroid` (ADR-208 RC-4 default for spritesheet mode):
        translate so the frame's alpha-mass-centroid Y lands at
        `centroid_y_target`. Caller must pre-compute `centroid_y_target`
        via `detect_centroid_y_target(frames, canvas_h)` once for the
        whole batch. Robust to extended-limb frames because the centroid
        integrates over all opaque pixels; a single limb extension only
        nudges the centroid by a few pixels (vs the dozens that
        bbox-bottom shifts).
      - `auto`: pick `bottom` for upright frames (height/width > 1.2),
        `center` otherwise. Legacy behavior; superseded by `mass-centroid`.
    """
    if anchor_mode == "ground-line":
        if ground_line_y is None:
            ground_line_y = canvas_h - bottom_margin
        return apply_ground_line_anchor(frame, ground_line_y, canvas_w, canvas_h)

    if anchor_mode == "mass-centroid":
        if centroid_y_target is None:
            centroid_y_target = canvas_h - bottom_margin - canvas_h // 4
        return apply_mass_centroid_anchor(frame, centroid_y_target, canvas_w, canvas_h)

    canvas = Image.new("RGBA", (canvas_w, canvas_h), (0, 0, 0, 0))
    if anchor_mode == "center":
        paste_y = (canvas_h - frame.height) // 2
    else:
        bottom = find_bottom_anchor(frame)
        paste_y = (canvas_h - bottom_margin) - bottom
    paste_x = (canvas_w - frame.width) // 2
    canvas.paste(frame, (paste_x, paste_y), frame)
    return canvas


def normalize_portrait(
    src: Path,
    dst: Path,
    target_w: int = 600,
    target_h: int = 980,
    padding_pct: float = 0.05,
) -> dict:
    """Trim, re-canvas with padding, bottom-anchor a portrait."""
    img = Image.open(src).convert("RGBA")
    trimmed = trim_to_bbox(img)
    if trimmed.width == 0 or trimmed.height == 0:
        raise RuntimeError("trimmed image is empty (alpha mask removed all content)")

    # Scale to fit within (target_w, target_h) with padding
    avail_w = int(target_w * (1 - 2 * padding_pct))
    avail_h = int(target_h * (1 - 2 * padding_pct))
    scale = min(avail_w / trimmed.width, avail_h / trimmed.height)
    new_w = max(1, int(trimmed.width * scale))
    new_h = max(1, int(trimmed.height * scale))
    scaled = trimmed.resize((new_w, new_h), Image.Resampling.LANCZOS)

    bottom_margin = int(target_h * padding_pct)
    anchored = anchor_to_canvas(scaled, target_w, target_h, bottom_margin=bottom_margin)
    dst.parent.mkdir(parents=True, exist_ok=True)
    anchored.save(dst, format="PNG")
    return {
        "input_size": [img.width, img.height],
        "trimmed_size": [trimmed.width, trimmed.height],
        "scaled_size": [new_w, new_h],
        "output_size": [target_w, target_h],
        "scale_factor": float(scale),
    }


def _post_anchor_despill_pink(arr):
    """Neutralize LANCZOS-introduced pink-cast pixels at silhouette edges.

    ADR-208 RC-5 helper. The shared-scale rescale + anchor translation
    inside `normalize_spritesheet` runs LANCZOS resampling on alpha-zeroed
    frames. LANCZOS interpolates between transparent (alpha=0) and
    character RGB; the resulting alpha-faded edge pixels carry pink-cast
    RGB values (R=180-245, G=80-100, B=130-180) at full or near-full
    alpha (alpha=200-255). These are NOT background bleed -- they are
    interpolation artifacts -- but they read as pink halo to the eye and
    register as wide_count failures in `verify_no_magenta`.

    The helper applies a stricter version of
    `neutralize_interior_magenta_spill`'s Tier B criterion with two
    relaxations:
      - alpha threshold relaxed from `alpha == 255` to `alpha > 200`,
        catching the partially-faded edge pixels.
      - r-g threshold relaxed from `> 90` to `> 70`, catching the
        slightly-less-saturated interpolation artifacts.

    Both are still pink/magenta-only (B*100 <= R*110 — purple costume
    pixels with B/R > 1.10 are protected). The recolor pulls R, B down
    to G to neutralize the hue while preserving brightness.

    Pure numpy. ~5ms / 256x256 frame.
    """
    rgb = arr[..., :3].astype(int)
    r = rgb[..., 0]
    g = rgb[..., 1]
    b = rgb[..., 2]
    alpha = arr[..., 3]
    # Tier B' (relaxed alpha + r-g): catches LANCZOS-introduced pink at
    # silhouette edges. Same hue protection (B*100 <= R*110) as the
    # canonical Tier B so purple costumes (B/R > 1.10) stay untouched.
    pink = (r >= 130) & (g <= 100) & (b >= 90) & ((r - g) > 70) & ((b - g) > 50) & (b * 100 <= r * 110) & (alpha > 200)
    arr[..., 0] = np.where(pink, g.astype(np.uint8), arr[..., 0])
    arr[..., 2] = np.where(pink, g.astype(np.uint8), arr[..., 2])
    return arr


def normalize_spritesheet(
    frames: list[Path],
    output_dir: Path,
    cell_w: int,
    cell_h: int,
    scale_percentile: float = 95,
    bottom_margin: int = DEFAULT_BOTTOM_MARGIN,
    anchor_mode: str = "mass-centroid",
) -> dict:
    """Shared-scale rescale + anchor alignment for spritesheet frames.

    `anchor_mode` defaults to `mass-centroid` (ADR-208 RC-4) — the
    drift-free anchor that survives extended-limb frames because it pins
    the alpha-mass centroid (the body trunk's center of mass) instead of
    the bbox bottom (a fist or kicking leg on action frames). Pre-fix
    anchor stddev on the canonical luchadora-highflyer/05-specials sample
    measured 21-31 px against an 8 px threshold under `ground-line`;
    `mass-centroid` drops it below 8 px on the same input.

    Pass `ground-line` for the legacy global-bbox-bottom strategy (still
    correct for portrait modes where the camera is fixed and every frame
    is grounded). Pass `bottom` for per-frame bbox-bottom (drifts on
    mixed grounded/aerial poses; kept for backward compat).
    """
    output_dir.mkdir(parents=True, exist_ok=True)

    imgs = [Image.open(p).convert("RGBA") for p in frames]
    target_h = shared_scale_height(imgs, scale_percentile)
    target_h = min(target_h, cell_h - 2 * bottom_margin)

    rescaled_imgs = [rescale_to_height(img, target_h) for img in imgs]

    # Compute the global anchor target ONCE across all rescaled frames so
    # each frame's translation pins the same quantity (centroid-Y for
    # mass-centroid mode, bbox-bottom-Y for ground-line mode). This is the
    # drift fix: per-frame anchors move with whatever bbox/centroid changes
    # across the batch, but a global target is invariant.
    ground_line_y: int | None = None
    centroid_y_target: int | None = None
    if anchor_mode == "ground-line":
        # Frames are not yet on the cell canvas; we need to compute ground
        # line in the post-translation coordinate system. We assume that
        # most frames (the grounded ones) will end up with their bottom at
        # `cell_h - bottom_margin`, so use that as the ground line.
        ground_line_y = cell_h - bottom_margin
    elif anchor_mode == "mass-centroid":
        # The mass-centroid target is the median centroid Y across the
        # rescaled frames. For walk cycles + idle loops the centroid stays
        # in a tight band; for action cycles the median is the "rest pose"
        # centroid and outlier frames (e.g. a leap) get translated relative
        # to that stable Y.
        centroid_y_target = detect_centroid_y_target(rescaled_imgs, cell_h)

    metadata: dict = {
        "scale_percentile": scale_percentile,
        "target_height": target_h,
        "cell_size": [cell_w, cell_h],
        "anchor_mode": anchor_mode,
        "ground_line_y": ground_line_y,
        "centroid_y_target": centroid_y_target,
        "frames": [],
    }

    # ADR-208 RC-5: post-anchor despill pass. The shared-scale rescale +
    # anchor translation runs LANCZOS at the silhouette edges of frames
    # whose magenta bg was already alpha-zeroed. LANCZOS interpolates
    # between alpha-faded character pixels and adjacent painted pixels
    # (purple costume shadows, dark hair near magenta-bg-cleaned interior),
    # producing pink-cast pixels (R=200-240, G=80-100, B=125-180) at
    # silhouette boundaries. These look like background bleed but are
    # actually interpolation artifacts. The Phase E despill chain ran
    # BEFORE this rescale so it cannot catch them.
    #
    # Re-running the despill chain on anchored frames cleans up the
    # LANCZOS-introduced pink. The local _post_anchor_despill helper uses
    # an alpha-relaxed variant of neutralize_interior_magenta_spill (alpha
    # > 200 instead of alpha == 255) to also catch the alpha-faded edge
    # pink left by paste-with-alpha. Drop on the canonical
    # luchadora-highflyer/05-specials sample: wide_count 232 -> ~25.
    # Lazily import sprite_bg to avoid a circular import at module-load
    # time (sprite_bg already imports anchor for find_alpha_mass_centroid
    # via sprite_verify).
    has_numpy_local = HAS_NUMPY
    if has_numpy_local:
        from sprite_bg import kill_pink_fringe

    for src, img, rescaled in zip(frames, imgs, rescaled_imgs):
        anchored = anchor_to_canvas(
            rescaled,
            cell_w,
            cell_h,
            bottom_margin=bottom_margin,
            anchor_mode=anchor_mode,
            ground_line_y=ground_line_y,
            centroid_y_target=centroid_y_target,
        )
        # ADR-208 RC-5: post-anchor despill pass.
        if has_numpy_local:
            arr = np.array(anchored)
            arr = _post_anchor_despill_pink(arr)
            arr = kill_pink_fringe(arr, alpha_ceiling=255)
            anchored = Image.fromarray(arr, "RGBA")
        out = output_dir / src.name
        anchored.save(out, format="PNG")
        anchor_y = find_bottom_anchor(anchored)
        metadata["frames"].append(
            {
                "name": src.name,
                "input_size": [img.width, img.height],
                "scaled_to": [rescaled.width, rescaled.height],
                "anchor_y": anchor_y,
            }
        )

    (output_dir / "anchor_metadata.json").write_text(json.dumps(metadata, indent=2), encoding="utf-8")
    return metadata


def cmd_normalize(args: argparse.Namespace) -> int:
    if args.mode == "portrait":
        try:
            meta = normalize_portrait(
                Path(args.input),
                Path(args.output),
                target_w=args.target_w,
                target_h=args.target_h,
            )
        except RuntimeError as e:
            logger.error("%s", e)
            return 4
        logger.info("[normalize] portrait %s -> %s (%s)", args.input, args.output, meta["output_size"])
        return 0

    # spritesheet
    frames = sorted(Path(args.input_dir).glob("*_frame_*.png"))
    if not frames:
        logger.error("no *_frame_*.png files in %s", args.input_dir)
        return 2
    # Map per-frame-bottom alias to the legacy `bottom` mode so internal
    # branching stays simple. ground-line is the new default.
    anchor_mode = "bottom" if args.anchor_mode == "per-frame-bottom" else args.anchor_mode
    meta = normalize_spritesheet(
        frames,
        Path(args.output_dir),
        cell_w=args.cell_size,
        cell_h=args.cell_size,
        scale_percentile=args.scale_percentile,
        anchor_mode=anchor_mode,
    )
    logger.info(
        "[normalize] spritesheet %d frames -> %s (scaled to h=%s)",
        len(frames),
        args.output_dir,
        meta["target_height"],
    )
    return 0


# ---------------------------------------------------------------------------
# Portrait dimension validator (Phase D)
# ---------------------------------------------------------------------------
def cmd_validate_portrait(args: argparse.Namespace) -> int:
    img = Image.open(args.input)
    w, h = img.size
    aspect = h / w if w > 0 else 0

    errors: list[str] = []
    if not (PORTRAIT_WIDTH_RANGE[0] <= w <= PORTRAIT_WIDTH_RANGE[1]):
        errors.append(f"width {w} outside {PORTRAIT_WIDTH_RANGE}")
    if not (PORTRAIT_HEIGHT_RANGE[0] <= h <= PORTRAIT_HEIGHT_RANGE[1]):
        errors.append(f"height {h} outside {PORTRAIT_HEIGHT_RANGE}")
    if not (PORTRAIT_ASPECT_MIN <= aspect <= PORTRAIT_ASPECT_MAX):
        errors.append(f"aspect 1:{aspect:.2f} outside [1:{PORTRAIT_ASPECT_MIN}, 1:{PORTRAIT_ASPECT_MAX}]")

    if errors:
        if args.force:
            logger.warning(
                "--force-dimensions used; output bypasses gate (%s)",
                "; ".join(errors),
            )
            return 0
        for e in errors:
            logger.error("%s", e)
        return 6

    logger.info("[validate-portrait] PASS (%dx%d, aspect 1:%.2f)", w, h, aspect)
    return 0
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated 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