Image Formats


Thomas Bonfort


tbonfort at


Jérome Boué


jbo-ads at

MapCache allows you to configure how the image should be saved to a cache once it has been requested from a source. The JPEG format should mostly be used for raster imagery, whereas the PNG format is most useful for vector based imagery where there are large uniform areas. Moreover a RAW format exists when nothing is known about the source format other than a file extension and MIME type.

JPEG Format

The JPEG format saves tiles to JPEG. You can configure the JPEG compression level (from 1 to 100) and the colorspace that should be used (RGB or YCbCr)

<format name="myjpeg" type="JPEG">
  • quality: This is the typical JPEG quality setting. Values under 50 produce lighter images but with notable compression artifacts. 100 should be avoided as it produces very heavy images.

  • photometric: By default the YCbCr colorspace is used as it produces images that tend to be 2 to 3 times lighter. Use RGB if you don’t want the default.

PNG Format

The PNG format creates PNG images, with optional quantization (reduction of the number of colors to create an 8-bit palleted PNG).

<format name="mypng" type="PNG">
  • compression: Choose which zlib compression to apply to the image data. Recognized values are “fast” and “best”. Omit the key to use the default zlib compression.

  • colors: Number of colors to use for quantization. Omit this key to produce 24 or 32 bit RGB/RGBA PNGs, or set to a value between 2 and 256 to create an 8-bit palleted PNG. The quantization step is destructive: There is no guarantee that pixels will not have a noticeable shift in color in the case when the tile contains many colors.

Mixed Format

There is a third special format which mixes JPEG and PNG compression depending on the contents of the image. This format allows creation of caches for raster imagery using JPEG compression (which is more efficient) on zones with imagery data, and PNG compression (which supports transparency) on zones with no imagery or on a boundary between imagery and emptiness.

<format name="mymixed" type="MIXED">
  • opaque: The format to use when the image has only fully opaque pixels

  • transparent: The format to use when the image has some transparent or semi-opaque pixels.

RAW Format

The RAW format shall be used when no information is known other than MIME type and a file extension. This format has been introduced in order to support Mapbox Vector Tile format, but can be used in other contexts (see MS RFC 119: Mapbox Vector Tile (MVT) Support). As a result features like metatile support and symbolic links for blank tiles are not supported. One bonus is that this image format can also be used for UTFGrids generated by MapServer - and presumably other sources.

<format name="MVT" type="RAW">
  • extension: The file extension of the raw tiles saved in cache

  • mime_type: The MIME type to request from the source