@w3kits-com/plugin-opendesign 0.1.8 → 0.1.10

package/dist/__w3kits/assets/skills/hatch-pet/scripts/generate_pet_images.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""Secondary image generation fallback for Codex pet base art and row strips."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import os
+import shutil
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+ALL_STATES = [
+    "idle",
+    "running-right",
+    "running-left",
+    "waving",
+    "jumping",
+    "failed",
+    "waiting",
+    "running",
+    "review",
+]
+CANONICAL_BASE_PATH = "references/canonical-base.png"
+
+
+def parse_states(raw: str) -> list[str]:
+    if raw.strip().lower() == "all":
+        return ALL_STATES
+    states = [item.strip() for item in raw.split(",") if item.strip()]
+    unknown = sorted(set(states) - set(ALL_STATES))
+    if unknown:
+        raise SystemExit(f"unknown state(s): {', '.join(unknown)}")
+    return states
+
+
+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 manifest_jobs(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 select_jobs(
+    manifest: dict[str, object],
+    *,
+    states: list[str],
+    skip_base: bool,
+    job_ids: list[str],
+) -> list[dict[str, object]]:
+    selected_ids = set(job_ids)
+    if not selected_ids:
+        if not skip_base:
+            selected_ids.add("base")
+        selected_ids.update(states)
+    selected = [job for job in manifest_jobs(manifest) if job.get("id") in selected_ids]
+    missing = selected_ids - {str(job.get("id")) for job in selected}
+    if missing:
+        raise SystemExit(f"unknown job id(s): {', '.join(sorted(missing))}")
+    return selected
+
+
+def _multipart_body(fields: list[tuple]) -> tuple[bytes, str]:
+    boundary = uuid.uuid4().hex
+    parts = []
+    for name, value in fields:
+        if isinstance(value, tuple):
+            fname, data, ct = value
+            parts.append(
+                f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{fname}"\r\nContent-Type: {ct}\r\n\r\n'.encode()
+                + data + b"\r\n"
+            )
+        else:
+            parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode())
+    parts.append(f"--{boundary}--\r\n".encode())
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+def run_image_edit(
+    *,
+    model: str,
+    prompt_file: Path,
+    image_paths: list[Path],
+    output_json: Path,
+    size: str,
+    api_key: str,
+) -> dict[str, object]:
+    output_json.parent.mkdir(parents=True, exist_ok=True)
+    fields: list[tuple] = [("model", model)]
+    for image_path in image_paths:
+        fields.append(("image[]", (image_path.name, image_path.read_bytes(), "image/png")))
+    fields.extend([
+        ("prompt", prompt_file.read_text(encoding="utf-8")),
+        ("size", size),
+        ("output_format", "png"),
+    ])
+    body, content_type = _multipart_body(fields)
+    req = urllib.request.Request(
+        "https://api.openai.com/v1/images/edits",
+        data=body,
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": content_type},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=300) as resp:
+        output_json.write_bytes(resp.read())
+    response = json.loads(output_json.read_text(encoding="utf-8"))
+    if response.get("error"):
+        raise SystemExit(json.dumps(response["error"], indent=2))
+    return response
+
+
+def run_image_generation(
+    *,
+    model: str,
+    prompt_file: Path,
+    output_json: Path,
+    size: str,
+    api_key: str,
+) -> dict[str, object]:
+    output_json.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps({
+        "model": model,
+        "prompt": prompt_file.read_text(encoding="utf-8"),
+        "size": size,
+        "output_format": "png",
+    }).encode()
+    req = urllib.request.Request(
+        "https://api.openai.com/v1/images/generations",
+        data=payload,
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=300) as resp:
+        output_json.write_bytes(resp.read())
+    response = json.loads(output_json.read_text(encoding="utf-8"))
+    if response.get("error"):
+        raise SystemExit(json.dumps(response["error"], indent=2))
+    return response
+
+
+def decode_response(response: dict[str, object], output_image: Path) -> None:
+    data = response.get("data")
+    if not isinstance(data, list) or not data:
+        raise SystemExit("image API response did not contain data[0]")
+    first = data[0]
+    if not isinstance(first, dict) or not isinstance(first.get("b64_json"), str):
+        raise SystemExit("image API response did not contain data[0].b64_json")
+    output_image.parent.mkdir(parents=True, exist_ok=True)
+    output_image.write_bytes(base64.b64decode(first["b64_json"]))
+
+
+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 complete_job(job: dict[str, object], output_path: Path) -> None:
+    job["status"] = "complete"
+    job["source_path"] = str(output_path)
+    job["source_provenance"] = "secondary-fallback-image-api"
+    job["source_sha256"] = file_sha256(output_path)
+    job["output_sha256"] = file_sha256(output_path)
+    job["completed_at"] = datetime.now(timezone.utc).isoformat()
+    job["secondary_fallback"] = True
+    for key in [
+        "last_error",
+        "synthetic_test_source",
+        "derived_from",
+        "mirror_decision",
+        "repair_reason",
+        "queued_at",
+    ]:
+        job.pop(key, None)
+
+
+def write_canonical_base(
+    run_dir: Path, manifest: dict[str, object], output_image: Path
+) -> None:
+    canonical = run_dir / CANONICAL_BASE_PATH
+    canonical.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(output_image, canonical)
+    reference = {
+        "path": CANONICAL_BASE_PATH,
+        "source_job": "base",
+        "sha256": file_sha256(canonical),
+    }
+    manifest["canonical_identity_reference"] = reference
+    request_path = run_dir / "pet_request.json"
+    if request_path.exists():
+        request = json.loads(request_path.read_text(encoding="utf-8"))
+        request["canonical_identity_reference"] = reference
+        request_path.write_text(json.dumps(request, indent=2) + "\n", encoding="utf-8")
+
+
+def path_list(run_dir: Path, job: dict[str, object]) -> list[Path]:
+    inputs = job.get("input_images")
+    if not isinstance(inputs, list):
+        raise SystemExit(f"job {job.get('id')} has invalid input_images")
+    paths = []
+    for item in inputs:
+        if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+            raise SystemExit(f"job {job.get('id')} has invalid input image entry")
+        path = (run_dir / item["path"]).resolve()
+        if not path.is_relative_to(run_dir):
+            raise SystemExit(f"path traversal detected in input_images for job {job.get('id')}")
+        if not path.is_file():
+            raise SystemExit(f"input image for job {job.get('id')} not found: {path}")
+        paths.append(path)
+    return paths
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--model", default="gpt-image-2")
+    parser.add_argument("--size", default="1024x1024")
+    parser.add_argument("--states", default="all")
+    parser.add_argument("--job-id", action="append", default=[])
+    parser.add_argument("--skip-base", action="store_true")
+    args = parser.parse_args()
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise SystemExit("OPENAI_API_KEY is not set")
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    manifest_path = run_dir / "imagegen-jobs.json"
+    manifest = load_manifest(run_dir)
+    jobs = select_jobs(
+        manifest,
+        states=parse_states(args.states),
+        skip_base=args.skip_base,
+        job_ids=args.job_id,
+    )
+    raw_dir = run_dir / "raw"
+
+    completed = []
+    for job in jobs:
+        job_id = str(job.get("id"))
+        prompt_raw = job.get("prompt_file")
+        output_raw = job.get("output_path")
+        if not isinstance(prompt_raw, str) or not isinstance(output_raw, str):
+            raise SystemExit(f"job {job_id} is missing prompt_file or output_path")
+        prompt_file = (run_dir / prompt_raw).resolve()
+        output_image = (run_dir / output_raw).resolve()
+        if not prompt_file.is_relative_to(run_dir):
+            raise SystemExit(f"path traversal detected in prompt_file for job {job_id}")
+        if not output_image.is_relative_to(run_dir):
+            raise SystemExit(f"path traversal detected in output_path for job {job_id}")
+        print(f"Generating {job_id} with secondary fallback")
+        image_paths = path_list(run_dir, job)
+        if image_paths:
+            response = run_image_edit(
+                model=args.model,
+                prompt_file=prompt_file,
+                image_paths=image_paths,
+                output_json=raw_dir / f"{job_id}.response.json",
+                size=args.size,
+                api_key=api_key,
+            )
+        else:
+            response = run_image_generation(
+                model=args.model,
+                prompt_file=prompt_file,
+                output_json=raw_dir / f"{job_id}.response.json",
+                size=args.size,
+                api_key=api_key,
+            )
+        decode_response(response, output_image)
+        complete_job(job, output_image)
+        if job_id == "base":
+            job["canonical_reference_path"] = CANONICAL_BASE_PATH
+            write_canonical_base(run_dir, manifest, output_image)
+        completed.append({"job_id": job_id, "output": str(output_image)})
+
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"ok": True, "completed": completed}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/dist/__w3kits/assets/skills/hatch-pet/scripts/inspect_frames.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Inspect extracted Codex pet frames before atlas composition."""
+
+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 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 and method and method != "components":
+        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("--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.",
+    )
+    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)
+    rows = [
+        inspect_state(frames_root, state, count, manifest_rows, chroma_key, args)
+        for state, count in ROW_FRAME_COUNTS.items()
+    ]
+    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),
+        "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()

package/dist/__w3kits/assets/skills/hatch-pet/scripts/make_contact_sheet.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Create a labeled contact sheet from a Codex pet atlas."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+COLUMNS = 8
+ROWS = 9
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+LABEL_HEIGHT = 22
+ROW_NAMES = [
+    "idle",
+    "running-right",
+    "running-left",
+    "waving",
+    "jumping",
+    "failed",
+    "waiting",
+    "running",
+    "review",
+]
+USED_COUNTS = [6, 8, 8, 4, 5, 8, 6, 6, 6]
+
+
+def checker(size: tuple[int, int], square: int = 16) -> Image.Image:
+    image = Image.new("RGB", size, "#ffffff")
+    draw = ImageDraw.Draw(image)
+    for y in range(0, size[1], square):
+        for x in range(0, size[0], square):
+            if (x // square + y // square) % 2:
+                draw.rectangle((x, y, x + square - 1, y + square - 1), fill="#e8e8e8")
+    return image
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("atlas")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--scale", type=float, default=0.5)
+    args = parser.parse_args()
+
+    with Image.open(Path(args.atlas).expanduser().resolve()) as opened:
+        atlas = opened.convert("RGBA")
+
+    cell_w = max(1, round(CELL_WIDTH * args.scale))
+    cell_h = max(1, round(CELL_HEIGHT * args.scale))
+    width = COLUMNS * cell_w
+    height = ROWS * (cell_h + LABEL_HEIGHT)
+    sheet = Image.new("RGB", (width, height), "#f7f7f7")
+    draw = ImageDraw.Draw(sheet)
+    font = ImageFont.load_default()
+
+    for row in range(ROWS):
+        y = row * (cell_h + LABEL_HEIGHT)
+        draw.rectangle((0, y, width, y + LABEL_HEIGHT - 1), fill="#111111")
+        draw.text((6, y + 5), f"row {row}: {ROW_NAMES[row]}", fill="#ffffff", font=font)
+        draw.text(
+            (width - 92, y + 5),
+            f"{USED_COUNTS[row]} frames",
+            fill="#ffffff",
+            font=font,
+        )
+        for column in range(COLUMNS):
+            crop = atlas.crop(
+                (
+                    column * CELL_WIDTH,
+                    row * CELL_HEIGHT,
+                    (column + 1) * CELL_WIDTH,
+                    (row + 1) * CELL_HEIGHT,
+                )
+            )
+            crop = crop.resize((cell_w, cell_h), Image.Resampling.LANCZOS)
+            bg = checker((cell_w, cell_h))
+            bg.paste(crop, (0, 0), crop)
+            x = column * cell_w
+            sheet.paste(bg, (x, y + LABEL_HEIGHT))
+            outline = "#18a058" if column < USED_COUNTS[row] else "#cc3344"
+            draw.rectangle(
+                (x, y + LABEL_HEIGHT, x + cell_w - 1, y + LABEL_HEIGHT + cell_h - 1),
+                outline=outline,
+            )
+            draw.text((x + 4, y + LABEL_HEIGHT + 4), str(column), fill="#111111", font=font)
+
+    output = Path(args.output).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(output)
+    print(f"wrote {output}")
+
+
+if __name__ == "__main__":
+    main()