A fast image processing library with low memory needs.

Pyramids

Pyramids — How to use libvips to make image pyramids

libvips includes vips_dzsave(), an operation that can build image pyramids compatible with DeepZoom, Zoomify and Google Maps image viewers. It’s fast and can generate pyramids for large images using only a small amount of memory.

The TIFF writer, vips_tiffsave() can also build tiled pyramidal TIFF images, but that’s very simple to use. This page concentrates on the DeepZoom builder.

Use --layout google to write Google maps-style pyramids. These are compatible with leaflet. For example:

$ vips dzsave wtc.tif gmapdir --layout google

Will create a directory called gmapdir containing blank.png, the file to display for blank tiles, and a set of numbered directories, one for each zoom level. The pyramid can be sparse (blank tiles are not written).

As with DeepZoom, you can use --suffix to set jpeg quality.

Use --background to set the background colour. This is the colour displayed for bits of the pyramid not in the image (image edges, for example). By default, the image background is white.

Use --centre to add a border to the image large enough to centre the image within the lowest resolution tile. By default, images are not centred.

For example:

$ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre

Other options

You can use --tile-size and --overlap to control how large the tiles are and how they overlap (obviously). They default to the correct values for the selected layout.

You can use --depth to control how deep the pyramid should be. Possible values are onepixel, onetile and one. onepixel means the image is shrunk until it fits within a single pixel. onetile means shrink until it fits with a tile. one means only write one pyramid layer (the highest resolution one). It defaults to the correct value for the selected layout. --depth one is handy for slicing up a large image into tiles (rather than a pyramid).

You can use --angle to do a 90, 180 or 270 degree rotate of an image during pyramid write.

You can use --container to set the container type. Normally dzsave will write a tree of directories, but with --container zip you’ll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically:

$ vips dzsave wtc.tif mypyr.zip

to write a zipfile containing the tiles. You can use .szi as a suffix to enable zip output as well.

Use --properties to output an XML file called vips-properties.xml. This contains a dump of all the metadata vips has about the image as a set of name-value pairs. It’s handy with openslide image sources.

Preprocessing images

You can use .dz as a filename suffix, meaning send the image to vips_dzsave(). This means you can write the output of any vips operation to a pyramid. For example:

The arguments to extract_area are image-in, image-out, left, top, width, height. So this command will cut out a 10,000 by 10,000 pixel area from near the top-left-hand corner of an Aperio slide image, then build a pyramid in Google layout using just those pixels.

If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example:

$ vips dzsave CMU-1.mrxs[level=1] x

Will pull out level 1 (the half-resolution level of an MRXS slide) and make a pyramid from that.

Troubleshooting

If you are building vips from source you do need to check the summary at the end of configure carefully. You must have the libgsf-1-dev package for vips_dzsave() to work.