pillow

Pillow decodes images across 30+ formats (JPEG, PNG, GIF, WebP, TIFF, AVIF, JPEG2000, BMP, PSD, etc.) through a plugin-based architecture where each format has a dedicated ImagePlugin subclass that registers itself with the Image module. The system uses lazy loading—plugins are only instantiated when their format is encountered—and delegates actual codec work to external C libraries (libjpeg, libpng, libwebp, etc.) via ctypes bindings, enabling format support without bloating the core library.

Pillow provides resize, crop, rotate, flip, and transpose operations through a combination of Python-level coordinate transformation logic and C-accelerated resampling kernels. Resize operations support multiple resampling filters (NEAREST, BILINEAR, BICUBIC, LANCZOS) implemented in C for performance; rotation uses affine transformation matrices computed in Python but applied via C code. All operations return new Image objects, preserving immutability semantics.

Pillow provides flexible file I/O through Image.open() (supporting file paths, file-like objects, and raw bytes), Image.save() (with format-specific parameters), and ImageFile.Parser for streaming decode. The architecture uses lazy loading—image headers are parsed immediately but pixel data is loaded on-demand—enabling efficient handling of large files. Memory-mapped file access is supported for certain formats (TIFF), reducing memory overhead for large images. The ImageFile module handles format detection, error recovery, and incremental loading.

Pillow encodes images to various formats via Image.save() with format-specific parameters controlling compression, quality, and metadata preservation. Each format plugin (JpegImagePlugin, PngImagePlugin, etc.) implements format-specific encoding logic, delegating to external C libraries (libjpeg, libpng, etc.) for actual compression. The architecture allows fine-grained control over encoding parameters (JPEG quality, PNG compression level, WebP method) without exposing low-level codec details. Metadata (EXIF, ICC profiles) can be embedded during encoding if specified.

Pillow's performance-critical operations are implemented in C (via _imaging.c and libImaging), while external codec libraries (libjpeg, libpng, libwebp, etc.) are wrapped via ctypes bindings rather than static linking. This architecture enables format support to degrade gracefully when libraries are unavailable and reduces binary size by avoiding static linking. The C extension layer handles low-level operations (pixel access, resampling, convolution) while Python code provides high-level APIs and orchestration.

Pillow converts images between color spaces (RGB, CMYK, LAB, HSV, etc.) through a combination of Python-level mode tracking and C-accelerated conversion routines. ICC profile support is provided via LittleCMS2 integration, enabling color-managed workflows where profiles are embedded in images, read during decode, and applied during conversion. The Image.convert() method handles both simple mode conversions and profile-aware transformations.

Pillow's ImageDraw module provides vector drawing primitives (rectangles, ellipses, polygons, lines, arcs) and text rendering via FreeType2 integration. Text rendering supports TrueType and OpenType fonts with optional complex text layout via Raqm library, enabling proper shaping for scripts like Arabic and Devanagari. Drawing operations are implemented in C for performance and support anti-aliasing, stroke width control, and fill/outline combinations.

Pillow provides a comprehensive filter module (ImageFilter) with built-in filters (BLUR, SHARPEN, EDGE_ENHANCE, SMOOTH, etc.) and support for custom convolution kernels via the filter() method. Filters are implemented in C using efficient convolution algorithms; the module also supports separable filters (applied as two 1D convolutions) for performance optimization. Filters can be applied to entire images or specific regions via ImageDraw masking.

Pillow provides bidirectional conversion between PIL.Image.Image objects and NumPy arrays via Image.fromarray() and numpy() methods, enabling seamless integration with NumPy-based image processing pipelines. The Image.load() method returns a pixel access object supporting direct indexing (img.load()[x, y]) for per-pixel operations, though this is slower than array conversion. The architecture maintains separate in-memory representations (PIL's internal format and NumPy arrays) to avoid unnecessary copies.

Pillow handles multi-frame image sequences (GIF, APNG, TIFF) through the Image.seek() method, which navigates between frames, and Image.n_frames property, which reports frame count. The library maintains frame metadata (duration, disposal method) in the Image.info dictionary and supports writing animated sequences via Image.save() with format-specific parameters. Frame data is lazy-loaded; seeking to a frame only loads that frame into memory, enabling efficient handling of large animations.

Pillow extracts and preserves image metadata through the Image.info dictionary, which contains format-specific metadata (EXIF, XMP, ICC profiles, etc.). EXIF data is parsed via the Exif class (Pillow 9.2+), providing structured access to EXIF tags. Metadata is preserved during image operations (e.g., resize) if explicitly requested via Image.copy() or Image.convert(), and can be written back to files via Image.save() with metadata parameters. The architecture maintains metadata separately from pixel data, enabling efficient metadata-only operations.

Pillow supports palette-based images (mode 'P') through quantization (converting RGB to indexed color) and palette manipulation. The Image.quantize() method reduces image colors to a specified palette size using various algorithms (median cut, k-means via libimagequant if available). Palettes can be extracted, modified, and applied to images via Image.palette property. The architecture maintains separate palette data (color lookup table) from pixel data (indices into palette), enabling efficient storage of indexed images.

Pillow handles image transparency through alpha channels (RGBA mode) and provides alpha compositing via Image.paste() with alpha parameter and Image.alpha_composite() method. The paste() method supports alpha blending, where the alpha channel of the source image controls transparency during composition. The architecture maintains alpha as a separate channel in RGBA mode, enabling efficient alpha operations without affecting RGB data. Transparency can be converted between modes (e.g., RGBA→RGB with background color) via Image.convert().