Meziantou.FrameworkSupported formats
editThe library reads and writes every format below with its own managed codecs. This group has one page per format: what is read, what is written, how to save with its encoder and its options, and the pitfalls.
Support matrix
| Format | Reads | Writes | Animations |
|---|---|---|---|
| PNG and APNG | Every color type and bit depth, palettes, interlacing, Apple CgBI files | Lossless: gray, RGB and RGBA at 8 or 16 bits, palettes on request | Read and written |
| GIF | GIF87a and GIF89a, interlacing, transparency, comments | Lossy by design: 256 colors per frame, one transparent color | Read and written |
| JPEG | Baseline, progressive, arithmetic coded, 12-bit, lossless; CMYK with a color conversion | Lossy, 8 bits, baseline or progressive, gray or YCbCr | No |
| WebP | Lossless, lossy, alpha | Lossless (default) or lossy, alpha | Read and written |
| QOI | Every file | Lossless 8-bit RGB and RGBA | No |
| BMP | Windows and OS/2 bitmaps, 1 to 32 bits, bit fields, run-length | 24 or 32 bits by default; indexed, run-length and 16 bits on request | No |
| TGA | True-color, grayscale and color-mapped, uncompressed or run-length | True-color and grayscale, uncompressed or run-length | No |
| Netpbm | PBM, PGM, PPM and PAM, 8 and 16 bits | Lossless; PBM on request | No |
| TIFF and BigTIFF | Multi-page documents, most compressions and sample layouts, floating-point samples, CMYK with a color conversion | Multi-page documents, lossless compressions or JPEG, bilevel, palette, 32-bit floating-point | No (pages) |
| ICO and CUR | PNG and bitmap representations, cursor hotspots | PNG or 32-bit bitmap representations, hotspots | No (representations) |
| ANI | Animated cursors | Animated cursors | Read and written |
| AVIF | 8 to 12 bits, alpha, grids, HDR descriptions | Lossless (default) or lossy, 8 to 12 bits, alpha, grids | Read and written |
| HEIC | 8 to 12 bits, alpha, grids, photos of phones and cameras | Lossless (default) or lossy, 8 to 12 bits, alpha, grids | Read and written |
| JPEG XL | Lossless and lossy, up to 16 bits, recompressed JPEG files, progressive renderings | Lossless (default) or lossy, up to 16 bits; JPEG files recompressed without loss | Read and written |
| JPEG 2000 | JP2 files and codestreams, up to 16 bits, HTJ2K | Lossless (default) or lossy, up to 16 bits | No |
| OpenEXR | Half, float and integer samples, most compressions | Lossless half or float samples | No |
What a format cannot store is never dropped silently: saving an animation as JPEG, transparency to a format without it, 16-bit samples to an 8-bit format or metadata the format has no place for throws an UnsupportedImageFeatureException, unless a setting of the encoder allows the conversion. See Saving images. What the codecs do not support is listed in Limitations.
Detection by content
Image.Load, Image.Identify and the readers detect the format from the first bytes of the data, never from the file name: a PNG file named photo.jpg loads as a PNG. Image.DetectFormat returns the format of a prefix of the data, and needs Image.FormatDetectionPrefixLength (18) bytes to recognize every format: TGA has no signature, so it is recognized from its whole header, and checked last. Data that no format recognizes throws an UnknownImageFormatException. See Identifying images.
Extensions of Save(path)
Save(path) without an encoder selects the encoder from the extension, with its default settings. Save(stream, encoder) always needs an encoder.
| Extension | Encoder | Output |
|---|---|---|
.png | PngEncoder | PNG, or APNG when the image is animated |
.apng | PngEncoder { AnimationMode = PngAnimationMode.Animated } | Always APNG |
.gif | GifEncoder | GIF |
.jpg, .jpeg | JpegEncoder | Baseline JPEG, quality 90 |
.webp | WebPEncoder | Lossless WebP |
.qoi | QoiEncoder | QOI |
.bmp, .dib | BmpEncoder | 24-bit, or 32-bit with alpha |
.tga, .icb, .vda, .vst | TgaEncoder | Uncompressed TGA |
.pnm, .pam, .ppm, .pgm | PnmEncoder | The Netpbm variant of the pixel format (PGM, PPM or PAM) |
.pbm | PnmEncoder { PixelLayout = PnmPixelLayout.Bitmap } | A portable bitmap, from black and white pixels only |
.tif, .tiff | TiffEncoder | Deflate-compressed TIFF |
.ico | IcoEncoder | Icon |
.cur | IcoEncoder { Kind = IconKind.Cursor } | Cursor |
.ani | AniEncoder | Animated cursor |
.avif, .avifs | AvifEncoder | Lossless AVIF |
.heic, .heif, .heics, .heifs | HeicEncoder | Lossless HEIC |
.jxl | JpegXlEncoder | Lossless JPEG XL |
.jp2 | Jpeg2000Encoder | Lossless JP2 file |
.j2k, .j2c, .jpc | Jpeg2000Encoder { Container = Jpeg2000Container.Codestream } | Lossless JPEG 2000 codestream |
.jph | Jpeg2000Encoder { BlockCoder = Jpeg2000BlockCoder.HighThroughput } | Lossless JPH (HTJ2K) file |
.jhc | Jpeg2000Encoder { BlockCoder = Jpeg2000BlockCoder.HighThroughput, Container = Jpeg2000Container.Codestream } | Lossless HTJ2K codestream |
.exr | OpenExrEncoder | ZIP-compressed OpenEXR |
Any other extension throws an ArgumentException, including .jpx and .jpf: those JPEG 2000 files are read, not written. Note that WebP, AVIF, HEIC, JPEG XL and JPEG 2000 are lossless by default, which makes large files from photos: pass an encoder with lossy compression for them.
Choosing a format
- Photos: JPEG is read everywhere. WebP, AVIF and JPEG XL have lossy modes too, usually smaller at the same visual quality; the AVIF and HEIC encoders search longer, and their
Effortsetting trades encoding time for size. HEIC is the format of the photos of phones: read it, and convert it to share it (see Handling phone photos). - Graphics, screenshots, logos and transparency: PNG, or lossless WebP. An image with few colors gets smaller as an indexed PNG; PngOptimization.Layout picks the narrowest exact layout from one pass over the pixels, and PngOptimization.MinimumSize searches the smallest lossless PNG.
- Animations: GIF is read everywhere but has 256 colors per frame and no partial transparency. APNG and lossless WebP keep every color and alpha value; lossy WebP and AVIF image sequences are smaller. See Processing animated images.
- High dynamic range: OpenEXR stores floating-point samples, and so does TIFF; AVIF, HEIC, JPEG XL and 16-bit PNG store HDR samples as integers with their color description. See Pixel formats.
- Archival and lossless masters: PNG, TIFF (also for multi-page documents), and JPEG XL or JPEG 2000 in lossless mode, which keep 16-bit samples. A JPEG file can be recompressed to JPEG XL without loss and rebuilt byte for byte (see JPEG XL).
- Scanned documents: a bilevel TIFF with CCITT Group 4 compression.
- Icons and cursors: ICO, CUR and ANI.
- Tooling, game assets and test fixtures: QOI, TGA, BMP and Netpbm are simple formats, lossless by default.
To convert files from one format to another, see Converting between formats.
Format pages
- PNG and APNG: lossless still images and animations, palettes, the smallest file.
- GIF: animations for every viewer, and how colors and transparency are reduced.
- JPEG: photos; quality, progressive files, smaller baseline files, and what JPEG cannot store.
- WebP: lossless and lossy images and animations for the web.
- QOI: a simple lossless format for 8-bit RGB and RGBA images.
- BMP: Windows bitmaps, indexed and run-length layouts.
- TGA: asset pipelines; a format without a signature.
- Netpbm: PBM, PGM, PPM and PAM, for tools and fixtures.
- TIFF and BigTIFF: multi-page documents, scans and floating-point pages.
- ICO and CUR: icons and cursors with several sizes.
- ANI: animated cursors.
- AVIF: small photos and image sequences, HDR.
- HEIC: photos of phones and cameras.
- JPEG XL: lossless and lossy images, progressive files, lossless JPEG recompression.
- JPEG 2000: lossless and lossy images for archives and imaging pipelines.
- OpenEXR: linear-light, floating-point images for rendering and visual effects.