@howaboua/pi-pet 0.1.1

package/authoring/hatch/scripts/combine_direction_blind_verdicts.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Combine independent blind direction verdicts by strict per-cell majority."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for the Pi Pet authoring package.
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from pathlib import Path
+
+
+def load_pairs(path: str) -> dict[str, dict[str, object]]:
+    payload = json.loads(Path(path).expanduser().resolve().read_text(encoding="utf-8"))
+    return {entry["pair"]: entry for entry in payload.get("pairs", [])}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--verdicts", action="append", required=True)
+    parser.add_argument("--json-out", required=True)
+    args = parser.parse_args()
+
+    if len(args.verdicts) < 3 or len(args.verdicts) % 2 == 0:
+        raise SystemExit("provide an odd number of at least three verdict files")
+
+    verdict_paths = [Path(path).expanduser().resolve() for path in args.verdicts]
+    if len(set(verdict_paths)) != len(verdict_paths):
+        raise SystemExit("verdict files must be distinct")
+
+    reviews = [load_pairs(str(path)) for path in verdict_paths]
+    pair_ids = set(reviews[0])
+    if any(set(review) != pair_ids for review in reviews[1:]):
+        raise SystemExit("all verdict files must contain the same pair ids")
+
+    threshold = len(reviews) // 2 + 1
+    combined = []
+    for pair_id in reviews[0]:
+        result: dict[str, object] = {"pair": pair_id}
+        vote_summary: dict[str, object] = {}
+        for slot in ("A", "B"):
+            votes = [review[pair_id].get(slot) for review in reviews]
+            counts = Counter(votes)
+            direction, count = counts.most_common(1)[0]
+            result[slot] = direction if count >= threshold else "ambiguous"
+            vote_summary[slot] = dict(counts)
+        result["reason"] = "strict majority of independent blind reviews"
+        result["votes"] = vote_summary
+        combined.append(result)
+
+    output = Path(args.json_out).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps({"pairs": combined}, indent=2) + "\n", encoding="utf-8")
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

package/authoring/hatch/scripts/compose_atlas.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Compose or normalize a Codex pet spritesheet atlas."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for the Pi Pet authoring package.
+
+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 clear_transparent_rgb(image: Image.Image) -> Image.Image:
+    rgba = image.convert("RGBA")
+    data = bytearray(rgba.tobytes())
+    for index in range(0, len(data), 4):
+        if data[index + 3] == 0:
+            data[index] = 0
+            data[index + 1] = 0
+            data[index + 2] = 0
+    return Image.frombytes("RGBA", rgba.size, bytes(data))
+
+
+def save_outputs(atlas: Image.Image, output: Path, webp_output: Path | None) -> None:
+    atlas = clear_transparent_rgb(atlas)
+    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,
+            exact=True,
+        )
+
+
+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/authoring/hatch/scripts/compose_cardinal_anchor_strip.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Compose approved cardinal reference cells."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for the Pi Pet authoring package.
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+
+CELL_SIZE = (192, 208)
+CARDINALS = ("000", "090", "180", "270")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--anchors-dir", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+
+    anchors_dir = Path(args.anchors_dir).expanduser().resolve()
+    output = Path(args.output).expanduser().resolve()
+    strip = Image.new("RGBA", (CELL_SIZE[0] * len(CARDINALS), CELL_SIZE[1]))
+
+    for index, direction in enumerate(CARDINALS):
+        path = anchors_dir / f"{direction}.png"
+        if not path.is_file():
+            raise SystemExit(f"missing approved cardinal reference: {path}")
+        with Image.open(path) as opened:
+            reference = opened.convert("RGBA")
+        if reference.size != CELL_SIZE:
+            raise SystemExit(f"{path} is {reference.size}; expected {CELL_SIZE}")
+        if reference.getbbox() is None:
+            raise SystemExit(f"approved cardinal reference is empty: {path}")
+        strip.alpha_composite(reference, (index * CELL_SIZE[0], 0))
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    strip.save(output)
+    print(f"wrote {output}")
+
+
+if __name__ == "__main__":
+    main()

package/authoring/hatch/scripts/derive_running_left_from_running_right.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Conditionally derive running-left by mirroring the approved running-right strip."""
+
+# Modified from the Apache-2.0 Hatch Pet workflow for Pi Pet's visual-jobs manifest.
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+RUNNING_FRAME_COUNT = 8
+
+
+def load_manifest(run_dir: Path) -> dict[str, object]:
+    path = run_dir / "visual-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 visual-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 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 mirror_strip_preserving_frame_order(
+    source: Image.Image,
+    frame_count: int = RUNNING_FRAME_COUNT,
+) -> Image.Image:
+    rgba = source.convert("RGBA")
+    mirrored = Image.new("RGBA", rgba.size, (0, 0, 0, 0))
+    slot_width = rgba.width / frame_count
+    for index in range(frame_count):
+        left = round(index * slot_width)
+        right = round((index + 1) * slot_width)
+        mirrored.alpha_composite(
+            ImageOps.mirror(rgba.crop((left, 0, right, rgba.height))),
+            (left, 0),
+        )
+    return mirrored
+
+
+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 / "visual-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 = mirror_strip_preserving_frame_order(image)
+        mirrored.save(output)
+
+    derived_at = datetime.now(timezone.utc).isoformat()
+    left_job["status"] = "staged"
+    left_job["source_path"] = manifest_relative(output, run_dir)
+    left_job["derived_from"] = "running-right"
+    left_job["derived_from_source"] = manifest_relative(source, run_dir)
+    left_job["staged_at"] = derived_at
+    left_job["metadata"] = image_metadata(output)
+    left_job["mirror_decision"] = {
+        "approved": True,
+        "approved_at": derived_at,
+        "note": args.decision_note.strip(),
+        "transform": "framewise-horizontal-mirror-preserving-order",
+    }
+    left_job.pop("completed_at", None)
+    for key in [
+        "last_error",
+        "repair_reason",
+        "queued_at",
+    ]:
+        left_job.pop(key, None)
+
+    temporary = manifest_path.with_name(f".{manifest_path.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+        temporary.replace(manifest_path)
+    finally:
+        temporary.unlink(missing_ok=True)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "job_id": "running-left",
+                "derived_from": "running-right",
+                "output": str(output),
+                "decision_note": args.decision_note.strip(),
+                "transform": "framewise-horizontal-mirror-preserving-order",
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()