A PNG-only sprite packer should reject a file that decodes as JPEG even if its name ends in .png. A general-purpose preview will often render both, so a successful thumbnail only tells you that a reader recognized the bytes. Validate the format where the sequence enters the pipeline, before turning each frame into RGBA or packing the atlas.
Disclosure: Generated with AI for the FrameSprite team. The article links to our own documentation. The examples use synthetic files.
Reproduce the mismatch
This example creates two small images named with the same extension. Each image is written with an explicit encoder. The import function restricts the decoder, loads the pixels while the file is open, and checks a separate one-frame policy for still-image deliveries.
from pathlib import Path
from tempfile import TemporaryDirectory
from PIL import Image, UnidentifiedImageError
def read_still_png(path):
with Image.open(path, formats=["PNG"]) as image:
if getattr(image, "n_frames", 1) != 1:
raise ValueError(f"{path.name}: expected one still frame")
image.load()
return image.convert("RGBA")
with TemporaryDirectory() as folder:
true_png = Path(folder) / "idle_001.png"
mislabeled = Path(folder) / "idle_002.png"
image = Image.new("RGB", (8, 8), (31, 157, 92))
image.save(true_png, format="PNG")
image.save(mislabeled, format="JPEG")
with Image.open(mislabeled) as preview:
print("General decoder:", preview.format)
assert read_still_png(true_png).mode == "RGBA"
try:
read_still_png(mislabeled)
except UnidentifiedImageError:
print("PNG-only gate rejected:", mislabeled.name)
else:
raise AssertionError("JPEG was accepted by the PNG-only gate")
Give the artist a frame-level error
Keep the original filename and the expected format in the rejection message. If your diagnostics use a separate general reader to identify the actual format, keep that diagnostic outside the acceptance path. An unreadable stream should get a different message from a readable JPEG, and a multi-frame PNG should get a still-frame-policy message. Run the gate for the entire selection before replacing the last good atlas. If a team intentionally supports JPEG inputs, define their separate rules for transparency and keep that decision visible in the import settings.
For a review fixture, use a valid still PNG, a JPEG under a PNG filename, and a PNG whose pixel data is truncated. The first should pack, the second should fail format selection, and the third should fail validation or decoding. Add a multi-frame APNG if your input rule requires one file per pose. Validate dimensions, order and expected frame count as separate acceptance steps.
Pillow's Image.open reference explains format restriction and deferred loading. The FrameSprite PNG sequence preflight guide has the companion decoder-format example and downloadable verification materials.
Top comments (0)