{"record":{"id":"c0dca3bdfef5676e","repo":"nexu-io/open-design","slug":"refusing-to-resize-source-atlas-because-its-aspect","errorCode":null,"errorMessage":"refusing to resize source atlas because its aspect ratio does not match the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. Generate exact atlas dimensions or use --frames-root.","messagePattern":"refusing to resize source atlas because its aspect ratio does not match the Codex atlas ratio (.+?); got (.+?)\\. Generate exact atlas dimensions or use --frames-root\\.","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"skills/hatch-pet/scripts/compose_atlas.py","lineNumber":79,"sourceCode":"    frame = source.convert(\"RGBA\")\n    if frame.size != (CELL_WIDTH, CELL_HEIGHT):\n        frame.thumbnail((CELL_WIDTH, CELL_HEIGHT), Image.Resampling.LANCZOS)\n    left = column * CELL_WIDTH + (CELL_WIDTH - frame.width) // 2\n    top = row * CELL_HEIGHT + (CELL_HEIGHT - frame.height) // 2\n    atlas.alpha_composite(frame, (left, top))\n\n\ndef compose_from_source_atlas(path: Path, resize_source: bool) -> Image.Image:\n    with Image.open(path) as opened:\n        source = opened.convert(\"RGBA\")\n    if source.size != (ATLAS_WIDTH, ATLAS_HEIGHT):\n        if not resize_source:\n            raise SystemExit(\n                f\"source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {source.width}x{source.height}\"\n            )\n        source_ratio = source.width / source.height\n        if abs(source_ratio - ATLAS_ASPECT_RATIO) > 0.02:\n            raise SystemExit(\n                \"refusing to resize source atlas because its aspect ratio does not match \"\n                f\"the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. \"\n                \"Generate exact atlas dimensions or use --frames-root.\"\n            )\n        source = source.resize((ATLAS_WIDTH, ATLAS_HEIGHT), Image.Resampling.LANCZOS)\n\n    atlas = Image.new(\"RGBA\", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))\n    for _state, row, frame_count in ROW_SPECS:\n        for column in range(frame_count):\n            left = column * CELL_WIDTH\n            top = row * CELL_HEIGHT\n            cell = source.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))\n            atlas.alpha_composite(cell, (left, top))\n    return atlas\n\n\ndef compose_from_frames(root: Path) -> Image.Image:\n    atlas = Image.new(\"RGBA\", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/skills/hatch-pet/scripts/compose_atlas.py#L61-L97","documentation":"Thrown by compose_from_source_atlas() when --resize-source was passed but the source atlas aspect ratio differs from the Codex atlas ratio (ATLAS_WIDTH/ATLAS_HEIGHT = 1536/1872 approx 0.821) by more than 0.02. Resizing across mismatched ratios would stretch frames non-uniformly and corrupt animation, so the script refuses even with consent.","triggerScenarios":"Run compose_atlas.py --source-atlas <png> --resize-source where source.width/source.height is not within 0.02 of 1536/1872.","commonSituations":"Source atlas cropped or padded differently than the target grid; a portrait/landscape source fed by mistake; exporting at a canvas size that preserves content ratio but not grid ratio.","solutions":["Regenerate the source atlas so its aspect ratio matches 1536:1872 (ideally at exactly 1536x1872).","Use --frames-root to assemble per-frame images and avoid atlas-ratio problems entirely.","Crop/letterbox the source in an image editor to the 8:9 cell grid ratio before feeding it in."],"exampleFix":"# before: source is 1024x1024 (ratio 1.0, far off)\npython compose_atlas.py --source-atlas square.png --output out.png --resize-source\n# after: regenerate at 1536x1872, then no --resize-source needed\npython compose_atlas.py --source-atlas atlas_1536x1872.png --output out.png","handlingStrategy":"validation","validationCode":"from PIL import Image\nATLAS_RATIO = 1536 / 1872\ndef assert_atlas_ratio(path):\n    with Image.open(path) as im:\n        ratio = im.width / im.height\n        if abs(ratio - ATLAS_RATIO) > 0.02:\n            raise SystemExit(f\"aspect {ratio:.3f} too far from {ATLAS_RATIO:.3f}; will not resize\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use --resize-source when the source already has the 8:9 grid ratio.","Crop/pad the source to the grid ratio in an image editor before resizing."],"tags":["image-processing","hatch-pet","atlas"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}