@howaboua/pi-pet 0.1.1

package/authoring/hatch/scripts/extract_strip_frames.py

@@ -0,0 +1,409 @@
+#!/usr/bin/env python3
+"""Extract generated horizontal row strips into 192x208 sprite frames."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for the Pi Pet authoring package.
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+from pathlib import Path
+
+from PIL import Image
+
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ROW_FRAME_COUNTS = {
+    "idle": 6,
+    "running-right": 8,
+    "running-left": 8,
+    "waving": 4,
+    "jumping": 5,
+    "failed": 8,
+    "waiting": 6,
+    "running": 6,
+    "review": 6,
+}
+
+
+def parse_states(raw: str) -> list[str]:
+    if raw.strip().lower() == "all":
+        return list(ROW_FRAME_COUNTS)
+    states = [item.strip() for item in raw.split(",") if item.strip()]
+    unknown = sorted(set(states) - set(ROW_FRAME_COUNTS))
+    if unknown:
+        raise SystemExit(f"unknown state(s): {', '.join(unknown)}")
+    return states
+
+
+def parse_hex_color(value: str) -> tuple[int, int, int]:
+    if not re.fullmatch(r"#[0-9a-fA-F]{6}", value):
+        raise SystemExit(f"invalid chroma key color: {value}; expected #RRGGBB")
+    return tuple(int(value[index : index + 2], 16) for index in (1, 3, 5))
+
+
+def load_chroma_key(decoded_dir: Path, override: str | None) -> tuple[int, int, int]:
+    if override:
+        return parse_hex_color(override)
+    request_path = decoded_dir.parent / "pet_request.json"
+    if request_path.is_file():
+        request = json.loads(request_path.read_text(encoding="utf-8"))
+        chroma_key = request.get("chroma_key")
+        if isinstance(chroma_key, dict) and isinstance(chroma_key.get("hex"), str):
+            return parse_hex_color(chroma_key["hex"])
+    return parse_hex_color("#00FF00")
+
+
+def color_distance(
+    red: int,
+    green: int,
+    blue: int,
+    key: tuple[int, int, int],
+) -> float:
+    return math.sqrt((red - key[0]) ** 2 + (green - key[1]) ** 2 + (blue - key[2]) ** 2)
+
+
+def remove_chroma_background(
+    image: Image.Image,
+    chroma_key: tuple[int, int, int],
+    threshold: float,
+) -> Image.Image:
+    rgba = image.convert("RGBA")
+    pixels = rgba.load()
+    for y in range(rgba.height):
+        for x in range(rgba.width):
+            red, green, blue, alpha = pixels[x, y]
+            if color_distance(red, green, blue, chroma_key) <= threshold:
+                pixels[x, y] = (0, 0, 0, 0)
+    return rgba
+
+
+def fit_to_cell(image: Image.Image) -> Image.Image:
+    bbox = image.getbbox()
+    target = Image.new("RGBA", (CELL_WIDTH, CELL_HEIGHT), (0, 0, 0, 0))
+    if bbox is None:
+        return target
+
+    sprite = image.crop(bbox)
+    max_width = CELL_WIDTH - 10
+    max_height = CELL_HEIGHT - 10
+    scale = min(max_width / sprite.width, max_height / sprite.height, 1.0)
+    if scale != 1.0:
+        sprite = sprite.resize(
+            (max(1, round(sprite.width * scale)), max(1, round(sprite.height * scale))),
+            Image.Resampling.LANCZOS,
+        )
+    left = (CELL_WIDTH - sprite.width) // 2
+    top = (CELL_HEIGHT - sprite.height) // 2
+    target.alpha_composite(sprite, (left, top))
+    return target
+
+
+def fit_viewport_to_cell(image: Image.Image) -> Image.Image:
+    target = Image.new("RGBA", (CELL_WIDTH, CELL_HEIGHT), (0, 0, 0, 0))
+    if image.getbbox() is None:
+        return target
+
+    viewport = image.copy()
+    max_width = CELL_WIDTH - 10
+    max_height = CELL_HEIGHT - 10
+    scale = min(max_width / viewport.width, max_height / viewport.height, 1.0)
+    if scale != 1.0:
+        viewport = viewport.resize(
+            (max(1, round(viewport.width * scale)), max(1, round(viewport.height * scale))),
+            Image.Resampling.LANCZOS,
+        )
+    left = (CELL_WIDTH - viewport.width) // 2
+    top = (CELL_HEIGHT - viewport.height) // 2
+    target.alpha_composite(viewport, (left, top))
+    return target
+
+
+def connected_components(image: Image.Image) -> list[dict[str, object]]:
+    alpha = image.getchannel("A")
+    width, height = image.size
+    data = alpha.tobytes()
+    visited = bytearray(width * height)
+    components: list[dict[str, object]] = []
+
+    for start, alpha_value in enumerate(data):
+        if alpha_value <= 16 or visited[start]:
+            continue
+
+        stack = [start]
+        visited[start] = 1
+        pixels: list[int] = []
+        min_x = width
+        min_y = height
+        max_x = 0
+        max_y = 0
+
+        while stack:
+            current = stack.pop()
+            pixels.append(current)
+            x = current % width
+            y = current // width
+            min_x = min(min_x, x)
+            min_y = min(min_y, y)
+            max_x = max(max_x, x)
+            max_y = max(max_y, y)
+
+            if x > 0:
+                neighbor = current - 1
+                if not visited[neighbor] and data[neighbor] > 16:
+                    visited[neighbor] = 1
+                    stack.append(neighbor)
+            if x + 1 < width:
+                neighbor = current + 1
+                if not visited[neighbor] and data[neighbor] > 16:
+                    visited[neighbor] = 1
+                    stack.append(neighbor)
+            if y > 0:
+                neighbor = current - width
+                if not visited[neighbor] and data[neighbor] > 16:
+                    visited[neighbor] = 1
+                    stack.append(neighbor)
+            if y + 1 < height:
+                neighbor = current + width
+                if not visited[neighbor] and data[neighbor] > 16:
+                    visited[neighbor] = 1
+                    stack.append(neighbor)
+
+        components.append(
+            {
+                "pixels": pixels,
+                "area": len(pixels),
+                "bbox": (min_x, min_y, max_x + 1, max_y + 1),
+                "center_x": (min_x + max_x + 1) / 2,
+            }
+        )
+
+    return components
+
+
+def component_group_image(
+    source: Image.Image,
+    components: list[dict[str, object]],
+    padding: int = 4,
+) -> Image.Image:
+    width, height = source.size
+    min_x = max(0, min(component["bbox"][0] for component in components) - padding)
+    min_y = max(0, min(component["bbox"][1] for component in components) - padding)
+    max_x = min(width, max(component["bbox"][2] for component in components) + padding)
+    max_y = min(height, max(component["bbox"][3] for component in components) + padding)
+
+    output = Image.new("RGBA", (max_x - min_x, max_y - min_y), (0, 0, 0, 0))
+    source_pixels = source.load()
+    output_pixels = output.load()
+    for component in components:
+        for pixel_index in component["pixels"]:
+            x = pixel_index % width
+            y = pixel_index // width
+            output_pixels[x - min_x, y - min_y] = source_pixels[x, y]
+    return output
+
+
+def component_frame_groups(
+    strip: Image.Image,
+    frame_count: int,
+) -> list[list[dict[str, object]]] | None:
+    components = connected_components(strip)
+    if not components:
+        return None
+
+    largest_area = max(component["area"] for component in components)
+    seed_threshold = max(120, largest_area * 0.20)
+    seeds = [component for component in components if component["area"] >= seed_threshold]
+    if len(seeds) < frame_count:
+        seeds = sorted(components, key=lambda component: component["area"], reverse=True)[
+            :frame_count
+        ]
+    if len(seeds) < frame_count:
+        return None
+
+    seeds = sorted(
+        sorted(seeds, key=lambda component: component["area"], reverse=True)[:frame_count],
+        key=lambda component: component["center_x"],
+    )
+    seed_ids = {id(seed) for seed in seeds}
+    groups: list[list[dict[str, object]]] = [[seed] for seed in seeds]
+    noise_threshold = max(12, largest_area * 0.002)
+
+    for component in components:
+        if id(component) in seed_ids or component["area"] < noise_threshold:
+            continue
+        nearest_index = min(
+            range(len(seeds)),
+            key=lambda index: abs(seeds[index]["center_x"] - component["center_x"]),
+        )
+        groups[nearest_index].append(component)
+
+    return groups
+
+
+def extract_component_frames(strip: Image.Image, frame_count: int) -> list[Image.Image] | None:
+    groups = component_frame_groups(strip, frame_count)
+    if groups is None:
+        return None
+    return [fit_to_cell(component_group_image(strip, group)) for group in groups]
+
+
+def component_bounds(components: list[dict[str, object]]) -> tuple[int, int, int, int]:
+    return (
+        min(component["bbox"][0] for component in components),
+        min(component["bbox"][1] for component in components),
+        max(component["bbox"][2] for component in components),
+        max(component["bbox"][3] for component in components),
+    )
+
+
+def extract_slot_frames(strip: Image.Image, frame_count: int) -> list[Image.Image]:
+    slot_width = strip.width / frame_count
+    frames = []
+    for index in range(frame_count):
+        left = round(index * slot_width)
+        right = round((index + 1) * slot_width)
+        crop = strip.crop((left, 0, right, strip.height))
+        frames.append(fit_to_cell(crop))
+    return frames
+
+
+def extract_stable_slot_frames(strip: Image.Image, frame_count: int) -> list[Image.Image]:
+    groups = component_frame_groups(strip, frame_count)
+    padding = 4
+    if groups is not None:
+        bboxes = [component_bounds(group) for group in groups]
+        shared_top = max(0, min(bbox[1] for bbox in bboxes) - padding)
+        shared_bottom = min(strip.height, max(bbox[3] for bbox in bboxes) + padding)
+        viewport_width = max(bbox[2] - bbox[0] for bbox in bboxes) + padding * 2
+        viewport_height = max(1, shared_bottom - shared_top)
+        frames = []
+        for group, bbox in zip(groups, bboxes):
+            grouped = component_group_image(strip, group, padding=padding)
+            grouped_top = max(0, bbox[1] - padding)
+            viewport = Image.new(
+                "RGBA",
+                (viewport_width, viewport_height),
+                (0, 0, 0, 0),
+            )
+            left = (viewport_width - grouped.width) // 2
+            viewport.alpha_composite(grouped, (left, grouped_top - shared_top))
+            frames.append(fit_viewport_to_cell(viewport))
+        return frames
+
+    bbox = strip.getbbox()
+    if bbox is None:
+        return [
+            Image.new("RGBA", (CELL_WIDTH, CELL_HEIGHT), (0, 0, 0, 0)) for _ in range(frame_count)
+        ]
+
+    shared_top = max(0, bbox[1] - padding)
+    shared_bottom = min(strip.height, bbox[3] + padding)
+    slot_width = strip.width / frame_count
+    frames = []
+    for index in range(frame_count):
+        left = round(index * slot_width)
+        right = round((index + 1) * slot_width)
+        crop = strip.crop((left, shared_top, right, shared_bottom))
+        frames.append(fit_viewport_to_cell(crop))
+    return frames
+
+
+def extract_state(
+    strip_path: Path,
+    state: str,
+    output_root: Path,
+    chroma_key: tuple[int, int, int],
+    threshold: float,
+    method: str,
+) -> dict[str, object]:
+    frame_count = ROW_FRAME_COUNTS[state]
+    with Image.open(strip_path) as opened:
+        strip = remove_chroma_background(opened, chroma_key, threshold)
+
+    state_dir = output_root / state
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    frames = None
+    used_method = method
+    if method in {"auto", "components"}:
+        frames = extract_component_frames(strip, frame_count)
+        if frames is None and method == "components":
+            raise SystemExit(f"could not find {frame_count} sprite components in {strip_path}")
+        if frames is not None:
+            used_method = "components"
+
+    if frames is None:
+        if method == "stable-slots":
+            frames = extract_stable_slot_frames(strip, frame_count)
+            used_method = "stable-slots"
+        else:
+            frames = extract_slot_frames(strip, frame_count)
+            used_method = "slots"
+
+    outputs = []
+    for index, frame in enumerate(frames):
+        output = state_dir / f"{index:02d}.png"
+        frame.save(output)
+        outputs.append(str(output))
+    return {"state": state, "frames": outputs, "method": used_method}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--decoded-dir", required=True)
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--states", default="all")
+    parser.add_argument("--chroma-key", help="Override chroma key as #RRGGBB.")
+    parser.add_argument("--key-threshold", type=float, default=96.0)
+    parser.add_argument(
+        "--method",
+        choices=("auto", "components", "slots", "stable-slots"),
+        default="auto",
+        help="Use connected sprite components when possible, raw equal slots, or row-stable slot viewports.",
+    )
+    args = parser.parse_args()
+
+    decoded_dir = Path(args.decoded_dir).expanduser().resolve()
+    output_dir = Path(args.output_dir).expanduser().resolve()
+    chroma_key = load_chroma_key(decoded_dir, args.chroma_key)
+    states = parse_states(args.states)
+    manifest = []
+    for state in states:
+        strip_path = decoded_dir / f"{state}.png"
+        if not strip_path.is_file():
+            raise SystemExit(f"missing generated strip for {state}: {strip_path}")
+        manifest.append(
+            extract_state(
+                strip_path,
+                state,
+                output_dir,
+                chroma_key,
+                args.key_threshold,
+                args.method,
+            )
+        )
+
+    (output_dir / "frames-manifest.json").write_text(
+        json.dumps(
+            {
+                "ok": True,
+                "chroma_key": {
+                    "hex": f"#{chroma_key[0]:02X}{chroma_key[1]:02X}{chroma_key[2]:02X}",
+                    "rgb": list(chroma_key),
+                    "threshold": args.key_threshold,
+                },
+                "rows": manifest,
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps({"ok": True, "frames_root": str(output_dir), "states": states}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/authoring/hatch/scripts/inspect_frames.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Inspect extracted Codex pet frames before atlas composition."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for the Pi Pet authoring package.
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from pathlib import Path
+from statistics import median
+
+from PIL import Image
+
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ROW_FRAME_COUNTS = {
+    "idle": 6,
+    "running-right": 8,
+    "running-left": 8,
+    "waving": 4,
+    "jumping": 5,
+    "failed": 8,
+    "waiting": 6,
+    "running": 6,
+    "review": 6,
+}
+IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
+
+
+def parse_states(raw: str) -> list[str]:
+    if raw.strip().lower() == "all":
+        return list(ROW_FRAME_COUNTS)
+    states = [item.strip() for item in raw.split(",") if item.strip()]
+    unknown = sorted(set(states) - set(ROW_FRAME_COUNTS))
+    if unknown:
+        raise SystemExit(f"unknown state(s): {', '.join(unknown)}")
+    return states
+
+
+def alpha_nonzero_count(image: Image.Image) -> int:
+    alpha = image if image.mode == "L" else image.getchannel("A")
+    return sum(alpha.histogram()[1:])
+
+
+def edge_alpha_count(image: Image.Image, margin: int) -> int:
+    alpha = image.getchannel("A")
+    width, height = alpha.size
+    total = 0
+    for box in (
+        (0, 0, width, margin),
+        (0, height - margin, width, height),
+        (0, 0, margin, height),
+        (width - margin, 0, width, height),
+    ):
+        total += alpha_nonzero_count(alpha.crop(box))
+    return total
+
+
+def color_distance(left: tuple[int, int, int], right: tuple[int, int, int]) -> float:
+    return math.sqrt(sum((left[index] - right[index]) ** 2 for index in range(3)))
+
+
+def chroma_adjacent_count(
+    image: Image.Image,
+    chroma_key: tuple[int, int, int] | None,
+    threshold: float,
+) -> int:
+    if chroma_key is None:
+        return 0
+    rgba = image.convert("RGBA")
+    data = rgba.tobytes()
+    count = 0
+    for index in range(0, len(data), 4):
+        red, green, blue, alpha = data[index : index + 4]
+        if alpha > 16 and color_distance((red, green, blue), chroma_key) <= threshold:
+            count += 1
+    return count
+
+
+def frame_files(state_dir: Path) -> list[Path]:
+    if not state_dir.is_dir():
+        return []
+    return sorted(path for path in state_dir.iterdir() if path.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def load_manifest(frames_root: Path) -> dict[str, dict[str, object]]:
+    manifest_path = frames_root / "frames-manifest.json"
+    if not manifest_path.is_file():
+        return {}
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    rows = manifest.get("rows", [])
+    if not isinstance(rows, list):
+        return {}
+    return {
+        row["state"]: row
+        for row in rows
+        if isinstance(row, dict) and isinstance(row.get("state"), str)
+    }
+
+
+def load_chroma_key(frames_root: Path) -> tuple[int, int, int] | None:
+    manifest_path = frames_root / "frames-manifest.json"
+    if not manifest_path.is_file():
+        return None
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    chroma_key = manifest.get("chroma_key")
+    if not isinstance(chroma_key, dict):
+        return None
+    rgb = chroma_key.get("rgb")
+    if (
+        not isinstance(rgb, list)
+        or len(rgb) != 3
+        or not all(isinstance(value, int) for value in rgb)
+    ):
+        return None
+    return (rgb[0], rgb[1], rgb[2])
+
+
+def inspect_state(
+    frames_root: Path,
+    state: str,
+    expected_count: int,
+    manifest_rows: dict[str, dict[str, object]],
+    chroma_key: tuple[int, int, int] | None,
+    args: argparse.Namespace,
+) -> dict[str, object]:
+    state_dir = frames_root / state
+    files = frame_files(state_dir)
+    row_errors: list[str] = []
+    row_warnings: list[str] = []
+    frames: list[dict[str, object]] = []
+    areas: list[int] = []
+    manifest_row = manifest_rows.get(state, {})
+    method = manifest_row.get("method")
+
+    if len(files) != expected_count:
+        row_errors.append(f"expected {expected_count} frame files for {state}, found {len(files)}")
+
+    if args.require_components:
+        if method == "components":
+            pass
+        elif method == "stable-slots" and args.allow_stable_slots:
+            row_warnings.append(
+                f"{state} used extraction method stable-slots; confirm motion playback remains stable and unclipped"
+            )
+        elif method is None:
+            row_errors.append(
+                f"{state} is missing extraction provenance; regenerate the row before requiring components"
+            )
+        else:
+            row_errors.append(
+                f"{state} used extraction method {method}; regenerate the row or inspect slot slicing"
+            )
+    elif method and method != "components":
+        row_warnings.append(
+            f"{state} used extraction method {method}; component extraction is preferred"
+        )
+
+    for index, frame_path in enumerate(files[:expected_count]):
+        with Image.open(frame_path) as opened:
+            frame = opened.convert("RGBA")
+        nontransparent = alpha_nonzero_count(frame)
+        bbox = frame.getbbox()
+        edge_pixels = edge_alpha_count(frame, args.edge_margin)
+        chroma_adjacent_pixels = chroma_adjacent_count(
+            frame,
+            chroma_key,
+            args.chroma_adjacent_threshold,
+        )
+        info = {
+            "index": index,
+            "file": str(frame_path),
+            "width": frame.width,
+            "height": frame.height,
+            "nontransparent_pixels": nontransparent,
+            "bbox": list(bbox) if bbox else None,
+            "edge_pixels": edge_pixels,
+            "chroma_adjacent_pixels": chroma_adjacent_pixels,
+        }
+        frames.append(info)
+        areas.append(nontransparent)
+
+        if frame.size != (CELL_WIDTH, CELL_HEIGHT):
+            row_errors.append(
+                f"{state} frame {index:02d} is {frame.width}x{frame.height}; expected {CELL_WIDTH}x{CELL_HEIGHT}"
+            )
+        if nontransparent < args.min_used_pixels:
+            row_errors.append(
+                f"{state} frame {index:02d} is empty or too sparse ({nontransparent} pixels)"
+            )
+        if edge_pixels > args.edge_pixel_threshold:
+            row_warnings.append(
+                f"{state} frame {index:02d} has {edge_pixels} non-transparent pixels near the cell edge"
+            )
+        if chroma_adjacent_pixels > args.chroma_adjacent_pixel_threshold:
+            row_errors.append(
+                f"{state} frame {index:02d} has {chroma_adjacent_pixels} non-transparent pixels close to the chroma key"
+            )
+
+    if areas:
+        row_median = median(areas)
+        for index, area in enumerate(areas[:expected_count]):
+            if row_median > 0 and area < row_median * args.small_outlier_ratio:
+                row_warnings.append(
+                    f"{state} frame {index:02d} is much smaller than the row median ({area} vs {row_median:.0f})"
+                )
+            if row_median > 0 and area > row_median * args.large_outlier_ratio:
+                row_warnings.append(
+                    f"{state} frame {index:02d} is much larger than the row median ({area} vs {row_median:.0f})"
+                )
+
+    return {
+        "state": state,
+        "expected_frames": expected_count,
+        "actual_frames": len(files),
+        "extraction_method": method,
+        "ok": not row_errors,
+        "errors": row_errors,
+        "warnings": row_warnings,
+        "frames": frames,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--frames-root", required=True)
+    parser.add_argument("--json-out", required=True)
+    parser.add_argument("--states", default="all")
+    parser.add_argument("--min-used-pixels", type=int, default=400)
+    parser.add_argument("--edge-margin", type=int, default=2)
+    parser.add_argument("--edge-pixel-threshold", type=int, default=24)
+    parser.add_argument("--chroma-adjacent-threshold", type=float, default=150.0)
+    parser.add_argument("--chroma-adjacent-pixel-threshold", type=int, default=800)
+    parser.add_argument("--small-outlier-ratio", type=float, default=0.35)
+    parser.add_argument("--large-outlier-ratio", type=float, default=2.75)
+    parser.add_argument(
+        "--require-components",
+        action="store_true",
+        help="Fail rows that fell back to equal-slot extraction.",
+    )
+    parser.add_argument(
+        "--allow-stable-slots",
+        action="store_true",
+        help="Permit explicitly chosen stable-slots extraction while still warning for visual review.",
+    )
+    args = parser.parse_args()
+
+    frames_root = Path(args.frames_root).expanduser().resolve()
+    manifest_rows = load_manifest(frames_root)
+    chroma_key = load_chroma_key(frames_root)
+    states = parse_states(args.states)
+    rows = [
+        inspect_state(frames_root, state, count, manifest_rows, chroma_key, args)
+        for state, count in ROW_FRAME_COUNTS.items()
+        if state in states
+    ]
+    errors = [error for row in rows for error in row["errors"]]
+    warnings = [warning for row in rows for warning in row["warnings"]]
+    result = {
+        "ok": not errors,
+        "frames_root": str(frames_root),
+        "states": states,
+        "errors": errors,
+        "warnings": warnings,
+        "rows": rows,
+    }
+
+    json_out = Path(args.json_out).expanduser().resolve()
+    json_out.parent.mkdir(parents=True, exist_ok=True)
+    json_out.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({k: v for k, v in result.items() if k != "rows"}, indent=2))
+    raise SystemExit(0 if result["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()