@leejungkiin/awkit 1.7.1 → 1.7.4

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

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""Extract generated horizontal row strips into 192x208 sprite frames."""
+
+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] = (red, green, blue, 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 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 extract_component_frames(strip: Image.Image, frame_count: int) -> list[Image.Image] | 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 [fit_to_cell(component_group_image(strip, group)) for group in groups]
+
+
+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_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:
+        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"),
+        default="auto",
+        help="Use connected sprite components when possible, or fixed equal slots.",
+    )
+    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/skills/hatch-pet/scripts/finalize_pet_run.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""Finalize a Codex pet run after all imagegen jobs are complete."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+
+def run(command: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    print("+ " + " ".join(command))
+    return subprocess.run(command, check=check, text=True)
+
+
+def load_json(path: Path) -> dict[str, object]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+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 is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def default_generated_images_root() -> Path:
+    return default_codex_home() / "generated_images"
+
+
+def default_codex_home() -> Path:
+    return Path(os.environ.get("CODEX_HOME") or "~/.codex").expanduser().resolve()
+
+
+def manifest_path(raw: object, *, run_dir: Path, field: str, job_id: str) -> Path:
+    if not isinstance(raw, str) or not raw:
+        raise SystemExit(f"job {job_id} has no {field}")
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        path = run_dir / path
+    return path.resolve()
+
+
+def validate_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
+    expected_hash = job.get("source_sha256")
+    if not isinstance(expected_hash, str) or not expected_hash:
+        raise SystemExit(
+            f"job {job_id} is missing source_sha256; ingest visual outputs with "
+            "record_imagegen_result.py instead of editing imagegen-jobs.json"
+        )
+    if not source.is_file():
+        raise SystemExit(f"job {job_id} source image no longer exists: {source}")
+    if not output.is_file():
+        raise SystemExit(f"job {job_id} decoded output is missing: {output}")
+    source_hash = file_sha256(source)
+    output_hash = file_sha256(output)
+    if source_hash != expected_hash:
+        raise SystemExit(f"job {job_id} source image hash does not match imagegen-jobs.json")
+    if output_hash != expected_hash:
+        raise SystemExit(
+            f"job {job_id} decoded output does not match its recorded source image; "
+            "do not rewrite decoded visual outputs locally"
+        )
+
+
+def validate_mirror_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
+    if job_id != "running-left":
+        raise SystemExit(f"job {job_id} may not use deterministic mirror provenance")
+    if job.get("derived_from") != "running-right":
+        raise SystemExit("running-left mirror job must derive from running-right")
+    decision = job.get("mirror_decision")
+    if not isinstance(decision, dict) or decision.get("approved") is not True:
+        raise SystemExit(
+            "running-left mirror job is missing an approved mirror_decision; "
+            "use derive_running_left_from_running_right.py after visual review"
+        )
+
+    expected_source_hash = job.get("source_sha256")
+    expected_output_hash = job.get("output_sha256")
+    if not isinstance(expected_source_hash, str) or not expected_source_hash:
+        raise SystemExit("running-left mirror job is missing source_sha256")
+    if not isinstance(expected_output_hash, str) or not expected_output_hash:
+        raise SystemExit("running-left mirror job is missing output_sha256")
+    if not source.is_file():
+        raise SystemExit(f"running-left mirror source image no longer exists: {source}")
+    if not output.is_file():
+        raise SystemExit(f"running-left mirrored output is missing: {output}")
+    if source.name != "running-right.png" or source.parent.name != "decoded":
+        raise SystemExit("running-left mirror source must be decoded/running-right.png")
+    if output.name != "running-left.png" or output.parent.name != "decoded":
+        raise SystemExit("running-left mirror output must be decoded/running-left.png")
+    if file_sha256(source) != expected_source_hash:
+        raise SystemExit("running-left mirror source hash does not match imagegen-jobs.json")
+    if file_sha256(output) != expected_output_hash:
+        raise SystemExit(
+            "running-left mirrored output hash does not match imagegen-jobs.json; "
+            "rerun derive_running_left_from_running_right.py"
+        )
+    with Image.open(source) as source_image, Image.open(output) as output_image:
+        expected = ImageOps.mirror(source_image.convert("RGBA"))
+        actual = output_image.convert("RGBA")
+        if expected.size != actual.size or expected.tobytes() != actual.tobytes():
+            raise SystemExit(
+                "running-left mirrored output is not an exact horizontal mirror of running-right"
+            )
+
+
+def validate_completed_job_source(
+    job: dict[str, object],
+    *,
+    run_dir: Path,
+    allow_synthetic_test_sources: bool,
+) -> None:
+    job_id = str(job.get("id") or "")
+    source = manifest_path(job.get("source_path"), run_dir=run_dir, field="source_path", job_id=job_id)
+    output = manifest_path(job.get("output_path"), run_dir=run_dir, field="output_path", job_id=job_id)
+
+    blocked_flags = [
+        flag
+        for flag in ("deterministic_pet_row", "cute_raster_row", "local_raster_row")
+        if job.get(flag)
+    ]
+    if blocked_flags:
+        raise SystemExit(
+            f"job {job_id} was marked as a local/synthetic row ({', '.join(blocked_flags)}); "
+            "regenerate it with $imagegen"
+        )
+
+    if job.get("synthetic_test_source"):
+        if not allow_synthetic_test_sources:
+            raise SystemExit(
+                f"job {job_id} uses a synthetic test source; rerun with real $imagegen output"
+            )
+        validate_hash(job, source=source, output=output, job_id=job_id)
+        return
+
+    if job.get("secondary_fallback"):
+        if job.get("source_provenance") != "secondary-fallback-image-api":
+            raise SystemExit(f"job {job_id} has invalid secondary fallback provenance")
+        validate_hash(job, source=source, output=output, job_id=job_id)
+        return
+
+    if job.get("source_provenance") == "deterministic-mirror":
+        validate_mirror_hash(job, source=source, output=output, job_id=job_id)
+        return
+
+    if job.get("source_provenance") != "built-in-imagegen":
+        raise SystemExit(
+            f"job {job_id} was not recorded as a built-in $imagegen output; "
+            "use record_imagegen_result.py with the selected $CODEX_HOME/generated_images/.../ig_*.png file"
+        )
+    if is_relative_to(source, run_dir):
+        raise SystemExit(
+            f"job {job_id} source image is inside the pet run directory; "
+            "do not use locally generated row artifacts as visual sources"
+        )
+    generated_root = default_generated_images_root()
+    if not is_relative_to(source, generated_root) or not source.name.startswith("ig_"):
+        raise SystemExit(
+            f"job {job_id} source image is not a built-in $imagegen output under "
+            f"{generated_root}/.../ig_*.png"
+        )
+    validate_hash(job, source=source, output=output, job_id=job_id)
+
+
+def require_complete_jobs(run_dir: Path, *, allow_synthetic_test_sources: bool) -> None:
+    manifest_path = run_dir / "imagegen-jobs.json"
+    manifest = load_json(manifest_path)
+    jobs = manifest.get("jobs")
+    if not isinstance(jobs, list):
+        raise SystemExit("invalid imagegen-jobs.json: jobs must be a list")
+    incomplete = [
+        str(job.get("id"))
+        for job in jobs
+        if isinstance(job, dict) and job.get("status", "pending") != "complete"
+    ]
+    if incomplete:
+        raise SystemExit(
+            "imagegen jobs are not complete; run pet_job_status.py and finish: "
+            + ", ".join(incomplete)
+        )
+    for job in jobs:
+        if isinstance(job, dict):
+            validate_completed_job_source(
+                job,
+                run_dir=run_dir,
+                allow_synthetic_test_sources=allow_synthetic_test_sources,
+            )
+
+
+def review_failures(review: dict[str, object]) -> list[str]:
+    rows = review.get("rows")
+    if not isinstance(rows, list):
+        return ["review did not contain row-level results"]
+    failures = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        errors = row.get("errors")
+        if isinstance(errors, list) and errors:
+            failures.append(f"{row.get('state')}: {'; '.join(str(error) for error in errors)}")
+    return failures
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--allow-slot-extraction", action="store_true")
+    parser.add_argument("--skip-videos", action="store_true")
+    parser.add_argument("--skip-package", action="store_true")
+    parser.add_argument(
+        "--package-dir",
+        default="",
+        help="Exact pet package directory. Defaults to ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>.",
+    )
+    parser.add_argument("--ffmpeg", default="")
+    parser.add_argument("--allow-synthetic-test-sources", action="store_true", help=argparse.SUPPRESS)
+    args = parser.parse_args()
+
+    scripts_dir = Path(__file__).resolve().parent
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    request = load_json(run_dir / "pet_request.json")
+    pet_id = str(request.get("pet_id") or "")
+    display_name = str(request.get("display_name") or "")
+    description = str(request.get("description") or "")
+    if not pet_id or not display_name or not description:
+        raise SystemExit("pet_request.json is missing pet_id, display_name, or description")
+
+    require_complete_jobs(
+        run_dir,
+        allow_synthetic_test_sources=args.allow_synthetic_test_sources,
+    )
+
+    final_dir = run_dir / "final"
+    qa_dir = run_dir / "qa"
+    final_dir.mkdir(parents=True, exist_ok=True)
+    qa_dir.mkdir(parents=True, exist_ok=True)
+
+    run(
+        [
+            sys.executable,
+            str(scripts_dir / "extract_strip_frames.py"),
+            "--decoded-dir",
+            str(run_dir / "decoded"),
+            "--output-dir",
+            str(run_dir / "frames"),
+            "--states",
+            "all",
+            "--method",
+            "auto",
+        ]
+    )
+
+    review_path = qa_dir / "review.json"
+    inspect_command = [
+        sys.executable,
+        str(scripts_dir / "inspect_frames.py"),
+        "--frames-root",
+        str(run_dir / "frames"),
+        "--json-out",
+        str(review_path),
+    ]
+    if not args.allow_slot_extraction:
+        inspect_command.append("--require-components")
+    run(inspect_command, check=False)
+    review = load_json(review_path)
+    if not review.get("ok"):
+        failures = review_failures(review)
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "review": str(review_path),
+                    "repair_hint": "Run queue_pet_repairs.py, regenerate the reopened row jobs with $imagegen, then finalize again.",
+                    "failures": failures,
+                },
+                indent=2,
+            )
+        )
+        raise SystemExit(1)
+
+    run(
+        [
+            sys.executable,
+            str(scripts_dir / "compose_atlas.py"),
+            "--frames-root",
+            str(run_dir / "frames"),
+            "--output",
+            str(final_dir / "spritesheet.png"),
+            "--webp-output",
+            str(final_dir / "spritesheet.webp"),
+        ]
+    )
+    run(
+        [
+            sys.executable,
+            str(scripts_dir / "validate_atlas.py"),
+            str(final_dir / "spritesheet.webp"),
+            "--json-out",
+            str(final_dir / "validation.json"),
+        ]
+    )
+    run(
+        [
+            sys.executable,
+            str(scripts_dir / "make_contact_sheet.py"),
+            str(final_dir / "spritesheet.webp"),
+            "--output",
+            str(qa_dir / "contact-sheet.png"),
+        ]
+    )
+
+    if not args.skip_videos:
+        video_command = [
+            sys.executable,
+            str(scripts_dir / "render_animation_videos.py"),
+            str(final_dir / "spritesheet.webp"),
+            "--output-dir",
+            str(qa_dir / "videos"),
+        ]
+        if args.ffmpeg:
+            video_command.extend(["--ffmpeg", args.ffmpeg])
+        run(video_command)
+
+    if not args.skip_package:
+        package_command = [
+            sys.executable,
+            str(scripts_dir / "package_custom_pet.py"),
+            "--pet-name",
+            pet_id,
+            "--display-name",
+            display_name,
+            "--description",
+            description,
+            "--spritesheet",
+            str(final_dir / "spritesheet.webp"),
+            "--force",
+        ]
+        if args.package_dir:
+            package_command.extend(["--output-dir", str(Path(args.package_dir).expanduser().resolve())])
+        run(package_command)
+
+    package_dir = None
+    if not args.skip_package:
+        package_dir = (
+            Path(args.package_dir).expanduser().resolve()
+            if args.package_dir
+            else default_codex_home() / "pets" / pet_id
+        )
+
+    summary = {
+        "ok": True,
+        "run_dir": str(run_dir),
+        "spritesheet": str(final_dir / "spritesheet.webp"),
+        "validation": str(final_dir / "validation.json"),
+        "contact_sheet": str(qa_dir / "contact-sheet.png"),
+        "review": str(review_path),
+        "videos": None if args.skip_videos else str(qa_dir / "videos"),
+        "package": None if package_dir is None else str(package_dir),
+    }
+    summary_path = qa_dir / "run-summary.json"
+    summary_path.write_text(json.dumps(summary, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(summary, indent=2))
+
+
+if __name__ == "__main__":
+    main()