nexu-io/open-design · error · SystemExit

refusing to resize source atlas because its aspect ratio doe

Error message

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.

What it means

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.

Source

Thrown at skills/hatch-pet/scripts/compose_atlas.py:79

    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))

View on GitHub (pinned to 5be4028344)

Solutions

1. Regenerate the source atlas so its aspect ratio matches 1536:1872 (ideally at exactly 1536x1872).
2. Use --frames-root to assemble per-frame images and avoid atlas-ratio problems entirely.
3. Crop/letterbox the source in an image editor to the 8:9 cell grid ratio before feeding it in.

Example fix

# before: source is 1024x1024 (ratio 1.0, far off)
python compose_atlas.py --source-atlas square.png --output out.png --resize-source
# after: regenerate at 1536x1872, then no --resize-source needed
python compose_atlas.py --source-atlas atlas_1536x1872.png --output out.png

from PIL import Image
ATLAS_RATIO = 1536 / 1872
def assert_atlas_ratio(path):
    with Image.open(path) as im:
        ratio = im.width / im.height
        if abs(ratio - ATLAS_RATIO) > 0.02:
            raise SystemExit(f"aspect {ratio:.3f} too far from {ATLAS_RATIO:.3f}; will not resize")

When it happens

Trigger: Run compose_atlas.py --source-atlas <png> --resize-source where source.width/source.height is not within 0.02 of 1536/1872.

Common situations: 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.

Related errors

• source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {sour
• {state} row needs {frame_count} frames, found {len(files)} u
• job manifest not found: {path}
• invalid imagegen-jobs.json: jobs must be a list
• unknown job id: {job_id}

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/c0dca3bdfef5676e. Report an issue: GitHub.