The PTIF file (.ptif, pyramid .tif)

A pyramid TIFF holds one very large image in a form that is quick to view at any size. Think of a museum's 2-gigapixel scan of a painting, a map sheet, or a microscope slide: far too big to send to a browser in one piece. Stored as a pyramid TIFF, it can be shown by a deep-zoom viewer that starts with an overview and loads sharper tiles only for the area you zoom into, the way online maps work.

Two ordinary TIFF features make this work:

• Tiles: the image is stored as small squares, each compressed separately, so any region can be read without decoding the rest.
• Several resolutions: the file also holds copies of the image at 1/2, 1/4, 1/8 of the size, and so on. Stacked from the largest at the bottom to the smallest at the top, they form the pyramid.

Because it's a normal TIFF underneath, there's no separate standard and no separate media type. The .ptif extension is a convention that some tools and image servers use to mark the file out; many pyramid TIFFs are simply .tif.

Each level has a quarter of the pixels of the one below, so the whole pyramid adds only about a third to the size of the full image. In exchange, a viewer showing the picture at any zoom level never needs to decode more than a screenful of tiles.

Tools differ in where they put the smaller levels:

• As further pages (IFDs in the main chain), each flagged as reduced resolution. This is what libvips writes by default, and what the example shows.
• As SubIFDs of the main image, hidden from the page list. libvips writes this with --subifd, which suits formats such as OME-TIFF for microscopy.
• With all IFDs at the start and the smallest level's tiles first, as Cloud Optimized GeoTIFF does, so a client reading over the network gets the whole index in its first request.

Whole-slide microscopy formats add their own twists. OpenSlide's documentation describes Aperio's .svs files as single-file pyramidal tiled TIFFs, with a stripped thumbnail as the second image and optional label and macro photographs of the glass slide at the end.

Browsers can't open a pyramid TIFF directly; most can't display TIFF at all. An image server sits in between. IIPImage, for example, reads tiled pyramid TIFF and JPEG 2000 files and answers requests in several tile protocols, including IIIF, Zoomify and DeepZoom, sending each tile as JPEG, PNG, WebP or AVIF.

The most widely used protocol in libraries and museums is the IIIF Image API (International Image Interoperability Framework). Every request is a URL naming the image, the region, the output size, the rotation, the quality and the format. A viewer first fetches info.json, which lists the image's size, tile size and available scale factors, then asks for the tiles it needs:

# what a deep-zoom viewer asks a IIIF image server for
https://images.example.org/iiif/3/scan.tif/info.json
https://images.example.org/iiif/3/scan.tif/0,0,1024,1024/256,/0/default.jpg
https://images.example.org/iiif/3/scan.tif/full/600,/0/default.jpg

With a pyramid TIFF behind it, the server answers each of these by decoding a handful of tiles from the right level, instead of scaling the whole image down for every request.

The usual tool is libvips, which processes huge images in small pieces without loading them whole. Its tiffsave operation writes a pyramid with --tile --pyramid; IIPImage's documentation recommends 256 × 256 tiles:

# 256 × 256 tiles, JPEG at quality 85, one level per halving
vips tiffsave scan.png scan.tif --tile --pyramid \
  --compression jpeg --Q 85 --tile-width 256 --tile-height 256

# lossless instead, and BigTIFF for files that may pass 4 GB
vips tiffsave scan.png scan.tif --tile --pyramid \
  --compression deflate --tile-width 256 --tile-height 256 --bigtiff

# check the result: one tiled directory per level
tiffinfo scan.tif | grep -E "Image Width|Tile Width"

• Compression: JPEG or WebP make small files for viewing. Deflate or Zstandard keep every pixel; IIPImage suggests Deflate for compatibility and Zstandard for size and speed.
• Size: add --bigtiff whenever the file could pass 4 GB, the limit of classic TIFF. The server's libtiff must support BigTIFF, which libtiff 4 and later do.
• Maps: GDAL's COG driver writes Cloud Optimized GeoTIFFs: gdal_translate input.tif output.tif -of COG. It uses 512 × 512 tiles and LZW compression by default.
• Check the result with tiffinfo: you should see one tiled directory per level, each half the size of the last. A tool that silently writes a single level, or strips instead of tiles, gives a file that's valid but slow to serve.

A COG is a pyramid TIFF with stricter rules: tiles, overviews, GeoTIFF tags, and IFDs at the start of the file. Clients read it over plain HTTP with range requests, fetching only the bytes they need, so no image server is needed. See our JP2 page for how JPEG 2000 gets resolutions out of a single codestream.

• Look inside: tiffinfo scan.tif lists every directory with its size, tiling and compression; vipsheader -a scan.tif shows the same through libvips; gdalinfo lists a COG's overviews.
• View it: rename a copy to .tif if needed and open it in an image editor that handles large TIFFs, such as GIMP, or use a whole-slide viewer for microscopy files. Ordinary viewers show the first, full-size level and may struggle with its size.
• Extract a level: vips copy "scan.tif[page=2]" level2.png writes the third level (500 × 375 in the example) as a PNG.
• Turn it into a folder of tiles for a static website: vips dzsave scan.tif scan writes Deep Zoom tiles that viewers such as OpenSeadragon can show without an image server.

• The image server is slow. The file is probably striped, not tiled, or has only one level, so the server decodes huge areas for every tile. Rebuild it with vips tiffsave … --tile --pyramid.
• Writing stops at 4 GB, or the file is corrupt. Classic TIFF can't address more. Save with --bigtiff.
• An ordinary app freezes opening it. It's decoding the full-size level, which may be billions of pixels. Use vips or a deep-zoom viewer, or extract a smaller level.
• JPEG tiles fail to decode in some tools. JPEG-in-TIFF with shared JPEGTables and YCbCr colour isn't supported everywhere. Re-save with Deflate if the file has to work in many programs.
• Visible seams between tiles. Heavy lossy compression treats each tile separately; raise the quality, or use lossless compression for master files.
• Huge declared dimensions. A small file can describe an enormous image. Servers that accept uploads should check the size in the first IFD before decoding.