An Image Is More Than a Grid of Pixels
An image file carries several independent dimensions — frames, transparency, palette, lossy vs lossless, bit depth, metadata — not just a grid of pixels.
The “an image is one picture” instinct breaks the moment you touch real files. An image file carries several independent dimensions at once, and each one has a format built to violate the naive assumption:
| Dimension | Naive assumption | Reality / the format that breaks it |
|---|---|---|
| Frame count | one still frame | GIF, animated WebP, APNG, multi-page TIFF, and PDF all hold many frames (libvips stacks them into a page-strip, see below) |
| Transparency | an opaque rectangle | PNG, WebP, and AVIF have an alpha channel; JPEG does not (paste a transparent PNG onto JPEG and you get a black or white fill) |
| Color storage | full RGB per pixel | GIF and PNG-8 use an indexed palette (≤256 colors), so photos posterize badly |
| Lossy vs lossless | pixels are exact | JPEG throws pixels away to shrink, and re-saving repeatedly degrades (generation loss); PNG keeps every pixel |
| Raster vs vector | a fixed pixel grid | SVG is math, not pixels, so it zooms infinitely with no resolution |
| Bit depth | 8-bit, 256 levels | 16-bit and HDR formats exist, and clipping to 8-bit loses tonal range |
| Hidden metadata | just pixels | EXIF orientation, ICC color profile, GIF per-frame delay: strip the wrong one and the image rotates, shifts color, or loses its animation timing |
The point: before processing, ask which dimensions this file uses: frames, alpha, palette, profile. That’s why libvips exposes Pages(), PageHeight(), color space, and metadata separately. The pixel grid is only one layer.
The pixel grid is only one layer of an image, not the whole thing.
References:
Related: For how libvips stacks those many frames into a page-strip, see libvips stores an animation as one tall stacked strip, and pair it with the image format cheat sheet — or go back to the crop, resize, fill overview.