@leejungkiin/awkit 1.7.0 → 1.7.4

package/skills/hatch-pet/scripts/clean_chroma_edges.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Clean leftover chroma-key fringe from transparent PNG assets.
+
+This is intentionally conservative: it only targets low-alpha pixels close to the
+configured key color, then bleeds nearby foreground RGB into fully transparent
+edge pixels so image scaling cannot sample hidden chroma color.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+
+DEFAULT_PATHS = (
+    "assets/ui/icons/v2/final",
+    "assets/mascot/v2/final",
+    "assets/mascot/v3/final",
+    "assets/illustrations/v1/final",
+)
+
+
+def smoothstep(edge0: float, edge1: float, x: np.ndarray) -> np.ndarray:
+    t = np.clip((x - edge0) / (edge1 - edge0), 0.0, 1.0)
+    return t * t * (3.0 - 2.0 * t)
+
+
+def shifted(values: np.ndarray, dy: int, dx: int) -> np.ndarray:
+    out = np.zeros_like(values)
+    src_y0 = max(0, -dy)
+    src_y1 = values.shape[0] - max(0, dy)
+    src_x0 = max(0, -dx)
+    src_x1 = values.shape[1] - max(0, dx)
+    dst_y0 = max(0, dy)
+    dst_y1 = values.shape[0] - max(0, -dy)
+    dst_x0 = max(0, dx)
+    dst_x1 = values.shape[1] - max(0, -dx)
+    out[dst_y0:dst_y1, dst_x0:dst_x1] = values[src_y0:src_y1, src_x0:src_x1]
+    return out
+
+
+def bleed_rgb(
+    rgb: np.ndarray,
+    alpha: np.ndarray,
+    chroma_mask: np.ndarray,
+    target_mask: np.ndarray,
+    iterations: int,
+) -> np.ndarray:
+    result = rgb.copy()
+    valid = (alpha > 8) & ~chroma_mask
+    seed = valid.copy()
+    remaining = target_mask.copy()
+
+    for _ in range(iterations):
+        accum = np.zeros_like(result, dtype=np.float32)
+        counts = np.zeros(alpha.shape, dtype=np.float32)
+
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dy == 0 and dx == 0:
+                    continue
+                neighbor_valid = shifted(seed, dy, dx)
+                fill = remaining & neighbor_valid
+                if not np.any(fill):
+                    continue
+                neighbor_rgb = shifted(result, dy, dx)
+                accum[fill] += neighbor_rgb[fill]
+                counts[fill] += 1.0
+
+        filled = counts > 0
+        if not np.any(filled):
+            break
+        result[filled] = np.clip(accum[filled] / counts[filled, None], 0, 255).astype(np.uint8)
+        seed[filled] = True
+        remaining[filled] = False
+
+    return result
+
+
+def expand_mask(mask: np.ndarray, iterations: int) -> np.ndarray:
+    result = mask.copy()
+    for _ in range(iterations):
+        expanded = result.copy()
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dy == 0 and dx == 0:
+                    continue
+                expanded |= shifted(result, dy, dx)
+        if np.array_equal(expanded, result):
+            break
+        result = expanded
+    return result
+
+
+def clean_array(
+    rgba: np.ndarray,
+    key: tuple[int, int, int],
+    hard_dist: float,
+    soft_dist: float,
+    max_alpha: int,
+    bleed_iterations: int,
+    edge_despill: bool,
+    edge_radius: int,
+    edge_strength: float,
+) -> tuple[np.ndarray, dict[str, int]]:
+    arr = rgba.copy()
+    rgb = arr[..., :3].astype(np.float32)
+    alpha = arr[..., 3].astype(np.float32)
+    key_rgb = np.array(key, dtype=np.float32)
+    dist = np.sqrt(np.sum((rgb - key_rgb) ** 2, axis=2))
+
+    candidate = (alpha > 0) & (alpha <= max_alpha) & (dist < soft_dist)
+    hard = candidate & (dist <= hard_dist)
+    feather = candidate & (dist > hard_dist)
+
+    matte = smoothstep(hard_dist, soft_dist, dist)
+    new_alpha = alpha.copy()
+    new_alpha[hard] = 0.0
+    new_alpha[feather] = np.minimum(new_alpha[feather], alpha[feather] * matte[feather])
+
+    old_a = np.clip(alpha / 255.0, 1.0 / 255.0, 1.0)
+    unmixed = (rgb - key_rgb * (1.0 - old_a[..., None])) / old_a[..., None]
+    spill = candidate & ~hard
+    rgb[spill] = np.clip(unmixed[spill], 0, 255)
+
+    chroma_mask = dist < soft_dist
+    rgb_uint8 = np.clip(rgb, 0, 255).astype(np.uint8)
+    alpha_uint8 = np.clip(np.rint(new_alpha), 0, 255).astype(np.uint8)
+    near_foreground = expand_mask(alpha_uint8 > 8, min(3, bleed_iterations))
+    hidden_chroma = (alpha <= 8) & chroma_mask & near_foreground
+    rgb_uint8 = bleed_rgb(rgb_uint8, alpha_uint8, chroma_mask, hidden_chroma, bleed_iterations)
+
+    arr[..., :3] = rgb_uint8
+    arr[..., 3] = alpha_uint8
+
+    edge_pixels = 0
+    if edge_despill:
+        arr, edge_pixels = despill_opaque_edge(arr, edge_radius, edge_strength, bleed_iterations)
+
+    changed = np.any(arr != rgba, axis=2)
+    stats = {
+        "changed": int(np.count_nonzero(changed)),
+        "keyed": int(np.count_nonzero(hard)),
+        "feathered": int(np.count_nonzero(feather)),
+        "edge": edge_pixels,
+    }
+    return arr, stats
+
+
+def despill_opaque_edge(
+    rgba: np.ndarray,
+    radius: int,
+    strength: float,
+    bleed_iterations: int,
+) -> tuple[np.ndarray, int]:
+    arr = rgba.copy()
+    rgb = arr[..., :3].astype(np.uint8)
+    alpha = arr[..., 3]
+    opaque = alpha > 8
+    edge = expand_mask(~opaque, radius) & opaque
+
+    r = rgb[..., 0].astype(np.int16)
+    g = rgb[..., 1].astype(np.int16)
+    b = rgb[..., 2].astype(np.int16)
+    magenta_score = (np.minimum(r, b) - g) + (b - g)
+    edge_spill = (
+        edge
+        & (r > 130)
+        & (b > 115)
+        & ((np.minimum(r, b) - g) > 22)
+        & ((b - g) > 18)
+    )
+    if not np.any(edge_spill):
+        return arr, 0
+
+    repaired_rgb = bleed_rgb(rgb, alpha, edge_spill, edge_spill, bleed_iterations)
+    matte = smoothstep(55.0, 275.0, magenta_score.astype(np.float32))
+    new_alpha = alpha.astype(np.float32)
+    new_alpha[edge_spill] *= 1.0 - np.clip(strength, 0.0, 1.0) * matte[edge_spill]
+
+    arr[..., :3] = repaired_rgb
+    arr[..., 3] = np.clip(np.rint(new_alpha), 0, 255).astype(np.uint8)
+    return arr, int(np.count_nonzero(edge_spill))
+
+
+def png_paths(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for item in paths:
+        path = Path(item)
+        if path.is_file() and path.suffix.lower() == ".png":
+            files.append(path)
+        elif path.is_dir():
+            files.extend(sorted(path.rglob("*.png")))
+    return sorted(set(files))
+
+
+def parse_key(value: str) -> tuple[int, int, int]:
+    raw = value.strip().lstrip("#")
+    if len(raw) != 6:
+        raise argparse.ArgumentTypeError("key must be a 6-digit hex color")
+    return tuple(int(raw[i : i + 2], 16) for i in (0, 2, 4))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("paths", nargs="*", default=list(DEFAULT_PATHS))
+    parser.add_argument("--key", type=parse_key, default=parse_key("#ff00ff"))
+    parser.add_argument("--hard-dist", type=float, default=42.0)
+    parser.add_argument("--soft-dist", type=float, default=118.0)
+    parser.add_argument("--max-alpha", type=int, default=180)
+    parser.add_argument("--bleed-iterations", type=int, default=10)
+    parser.add_argument("--edge-despill", action="store_true")
+    parser.add_argument("--edge-radius", type=int, default=3)
+    parser.add_argument("--edge-strength", type=float, default=0.75)
+    parser.add_argument("--apply", action="store_true")
+    args = parser.parse_args()
+
+    files = png_paths(args.paths)
+    totals = {"files": 0, "changed": 0, "keyed": 0, "feathered": 0}
+
+    for path in files:
+        original = np.array(Image.open(path).convert("RGBA"))
+        cleaned, stats = clean_array(
+            original,
+            args.key,
+            args.hard_dist,
+            args.soft_dist,
+            args.max_alpha,
+            args.bleed_iterations,
+            args.edge_despill,
+            args.edge_radius,
+            args.edge_strength,
+        )
+        if stats["changed"] == 0:
+            continue
+
+        totals["files"] += 1
+        totals["changed"] += stats["changed"]
+        totals["keyed"] += stats["keyed"]
+        totals["feathered"] += stats["feathered"]
+        totals["edge"] = totals.get("edge", 0) + stats["edge"]
+        action = "cleaned" if args.apply else "would clean"
+        print(
+            f"{action} {path}: changed={stats['changed']} "
+            f"keyed={stats['keyed']} feathered={stats['feathered']} edge={stats['edge']}"
+        )
+        if args.apply:
+            Image.fromarray(cleaned, "RGBA").save(path)
+
+    mode = "APPLIED" if args.apply else "DRY_RUN"
+    print(
+        f"{mode} files={totals['files']} changed={totals['changed']} "
+        f"keyed={totals['keyed']} feathered={totals['feathered']} edge={totals.get('edge', 0)}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/hatch-pet/scripts/compose_atlas.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Compose or normalize a Codex pet spritesheet atlas."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+
+COLUMNS = 8
+ROWS = 9
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ATLAS_WIDTH = COLUMNS * CELL_WIDTH
+ATLAS_HEIGHT = ROWS * CELL_HEIGHT
+ATLAS_ASPECT_RATIO = ATLAS_WIDTH / ATLAS_HEIGHT
+ROW_SPECS = [
+    ("idle", 0, 6),
+    ("running-right", 1, 8),
+    ("running-left", 2, 8),
+    ("waving", 3, 4),
+    ("jumping", 4, 5),
+    ("failed", 5, 8),
+    ("waiting", 6, 6),
+    ("running", 7, 6),
+    ("review", 8, 6),
+]
+IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
+
+
+def image_files(path: Path) -> list[Path]:
+    return sorted(p for p in path.iterdir() if p.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def find_row_frames(root: Path, state: str, row_index: int) -> list[Path]:
+    candidates = [
+        root / state,
+        root / f"row-{row_index}",
+        root / f"row{row_index}",
+        root / f"{row_index}-{state}",
+    ]
+    for candidate in candidates:
+        if candidate.is_dir():
+            files = image_files(candidate)
+            if files:
+                return files
+    globs = [
+        f"{state}_*",
+        f"{state}-*",
+        f"row{row_index}_*",
+        f"row-{row_index}-*",
+    ]
+    files: list[Path] = []
+    for pattern in globs:
+        files.extend(p for p in root.glob(pattern) if p.suffix.lower() in IMAGE_SUFFIXES)
+    return sorted(set(files))
+
+
+def paste_centered(atlas: Image.Image, source: Image.Image, row: int, column: int) -> None:
+    frame = source.convert("RGBA")
+    if frame.size != (CELL_WIDTH, CELL_HEIGHT):
+        frame.thumbnail((CELL_WIDTH, CELL_HEIGHT), Image.Resampling.LANCZOS)
+    left = column * CELL_WIDTH + (CELL_WIDTH - frame.width) // 2
+    top = row * CELL_HEIGHT + (CELL_HEIGHT - frame.height) // 2
+    atlas.alpha_composite(frame, (left, top))
+
+
+def compose_from_source_atlas(path: Path, resize_source: bool) -> Image.Image:
+    with Image.open(path) as opened:
+        source = opened.convert("RGBA")
+    if source.size != (ATLAS_WIDTH, ATLAS_HEIGHT):
+        if not resize_source:
+            raise SystemExit(
+                f"source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {source.width}x{source.height}"
+            )
+        source_ratio = source.width / source.height
+        if abs(source_ratio - ATLAS_ASPECT_RATIO) > 0.02:
+            raise SystemExit(
+                "refusing to resize source atlas because its aspect ratio does not match "
+                f"the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. "
+                "Generate exact atlas dimensions or use --frames-root."
+            )
+        source = source.resize((ATLAS_WIDTH, ATLAS_HEIGHT), Image.Resampling.LANCZOS)
+
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for _state, row, frame_count in ROW_SPECS:
+        for column in range(frame_count):
+            left = column * CELL_WIDTH
+            top = row * CELL_HEIGHT
+            cell = source.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))
+            atlas.alpha_composite(cell, (left, top))
+    return atlas
+
+
+def compose_from_frames(root: Path) -> Image.Image:
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for state, row, frame_count in ROW_SPECS:
+        files = find_row_frames(root, state, row)
+        if len(files) < frame_count:
+            raise SystemExit(
+                f"{state} row needs {frame_count} frames, found {len(files)} under {root}"
+            )
+        for column, frame_path in enumerate(files[:frame_count]):
+            with Image.open(frame_path) as frame:
+                paste_centered(atlas, frame, row, column)
+    return atlas
+
+
+def save_outputs(atlas: Image.Image, output: Path, webp_output: Path | None) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    atlas.save(output)
+    if webp_output is not None:
+        webp_output.parent.mkdir(parents=True, exist_ok=True)
+        atlas.save(webp_output, format="WEBP", lossless=True, quality=100, method=6)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--source-atlas")
+    source.add_argument("--frames-root")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--webp-output")
+    parser.add_argument(
+        "--resize-source",
+        action="store_true",
+        help="Resize a lower-resolution source atlas only when it already has the Codex atlas aspect ratio.",
+    )
+    args = parser.parse_args()
+
+    if args.source_atlas:
+        atlas = compose_from_source_atlas(
+            Path(args.source_atlas).expanduser().resolve(), args.resize_source
+        )
+    else:
+        atlas = compose_from_frames(Path(args.frames_root).expanduser().resolve())
+
+    save_outputs(
+        atlas,
+        Path(args.output).expanduser().resolve(),
+        Path(args.webp_output).expanduser().resolve() if args.webp_output else None,
+    )
+    print(f"wrote {Path(args.output).expanduser().resolve()}")
+    if args.webp_output:
+        print(f"wrote {Path(args.webp_output).expanduser().resolve()}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/hatch-pet/scripts/derive_running_left_from_running_right.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Conditionally derive running-left by mirroring the approved running-right strip."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+
+def load_manifest(run_dir: Path) -> dict[str, object]:
+    path = run_dir / "imagegen-jobs.json"
+    if not path.exists():
+        raise SystemExit(f"job manifest not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def job_list(manifest: dict[str, object]) -> list[dict[str, object]]:
+    jobs = manifest.get("jobs")
+    if not isinstance(jobs, list):
+        raise SystemExit("invalid imagegen-jobs.json: jobs must be a list")
+    return [job for job in jobs if isinstance(job, dict)]
+
+
+def find_job(manifest: dict[str, object], job_id: str) -> dict[str, object]:
+    for job in job_list(manifest):
+        if job.get("id") == job_id:
+            return job
+    raise SystemExit(f"unknown job id: {job_id}")
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def image_metadata(path: Path) -> dict[str, object]:
+    with Image.open(path) as image:
+        image.verify()
+    with Image.open(path) as image:
+        return {
+            "width": image.width,
+            "height": image.height,
+            "mode": image.mode,
+            "format": image.format,
+        }
+
+
+def manifest_relative(path: Path, run_dir: Path) -> str:
+    return str(path.resolve().relative_to(run_dir.resolve()))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument(
+        "--confirm-appropriate-mirror",
+        action="store_true",
+        help="Required after visually confirming the rightward strip can be mirrored without identity/prop issues.",
+    )
+    parser.add_argument(
+        "--decision-note",
+        required=True,
+        help="Short note explaining why mirroring is acceptable for this pet.",
+    )
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    if not args.confirm_appropriate_mirror:
+        raise SystemExit("refusing to mirror without --confirm-appropriate-mirror")
+    if not args.decision_note.strip():
+        raise SystemExit("--decision-note must explain why mirroring is appropriate")
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    manifest_path = run_dir / "imagegen-jobs.json"
+    manifest = load_manifest(run_dir)
+    right_job = find_job(manifest, "running-right")
+    left_job = find_job(manifest, "running-left")
+
+    if right_job.get("status") != "complete":
+        raise SystemExit("running-right must be complete before deriving running-left")
+    mirror_policy = left_job.get("mirror_policy")
+    if not isinstance(mirror_policy, dict) or mirror_policy.get("may_derive_from") != "running-right":
+        raise SystemExit("running-left is not configured for conditional mirroring")
+
+    source = run_dir / "decoded" / "running-right.png"
+    output = run_dir / "decoded" / "running-left.png"
+    if not source.is_file():
+        raise SystemExit(f"running-right decoded strip not found: {source}")
+    if output.exists() and not args.force:
+        raise SystemExit(f"{output} already exists; pass --force to replace it")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with Image.open(source) as image:
+        mirrored = ImageOps.mirror(image.convert("RGBA"))
+        mirrored.save(output)
+
+    left_job["status"] = "complete"
+    left_job["source_path"] = manifest_relative(source, run_dir)
+    left_job["source_provenance"] = "deterministic-mirror"
+    left_job["derived_from"] = "running-right"
+    left_job["source_sha256"] = file_sha256(source)
+    left_job["output_sha256"] = file_sha256(output)
+    left_job["completed_at"] = datetime.now(timezone.utc).isoformat()
+    left_job["metadata"] = image_metadata(output)
+    left_job["mirror_decision"] = {
+        "approved": True,
+        "approved_at": left_job["completed_at"],
+        "note": args.decision_note.strip(),
+    }
+    for key in [
+        "last_error",
+        "secondary_fallback",
+        "synthetic_test_source",
+        "repair_reason",
+        "queued_at",
+    ]:
+        left_job.pop(key, None)
+
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "job_id": "running-left",
+                "derived_from": "running-right",
+                "output": str(output),
+                "decision_note": args.decision_note.strip(),
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()