libvips includes <literal>vips_dzsave()</literal>, an operation that can build image pyramids compatible with <linkxlink:href="http://en.wikipedia.org/wiki/Deep_Zoom">DeepZoom</link>, Zoomify and <linkxlink:href="https://developers.google.com/maps/">Google Maps</link> image viewers. It’s fast and can generate pyramids for large images using only a small amount of memory.
The TIFF writer, <literal>vips_tiffsave()</literal> can also build tiled pyramidal TIFF images, but that’s very simple to use. This page concentrates on the DeepZoom builder.
You can also call <literal>vips_dzsave()</literal> from any language with a libvips binding, or by using <literal>.dz</literal> or <literal>.szi</literal> as an output file suffix.
The <literal>--layout</literal> option sets the basic mode of operation. With no <literal>--layout</literal>, dzsave writes DeepZoom pyramids. For example:
</para>
<programlisting>
$ vips dzsave huge.tif mydz
</programlisting>
<para>
This will create a directory called <literal>mydz_files</literal> containing the image tiles, and write a file called <literal>mydz.dzi</literal> containing the image metadata.
</para>
<para>
You can use the <literal>--suffix</literal> option to control how tiles are written. For example:
</para>
<programlisting>
$ vips dzsave huge.tif mydz --suffix .jpg[Q=90]
</programlisting>
<para>
will write JPEG tiles with the quality factor set to 90. You can set any format write options you like, see the API docs for <literal>vips_jpegsave()</literal> for details.
Use <literal>--layout zoomify</literal> to put dzsave into zoomify mode. For example:
</para>
<programlisting>
$ vips dzsave huge.tif myzoom --layout zoomify
</programlisting>
<para>
This will create a directory called <literal>myzoom</literal> containing a file called <literal>ImageProperties.xml</literal> with the image metadata in, and a series of directories called <literal>TileGroupn</literal>, each containing 256 image tiles.
</para>
<para>
As with DeepZoom, you can use <literal>--suffix</literal> to set jpeg quality.
Use <literal>--layout google</literal> to write Google maps-style pyramids. These are compatible with <linkxlink:href="http://leafletjs.com/">leaflet</link>. For example:
Will create a directory called <literal>gmapdir</literal> containing <literal>blank.png</literal>, 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).
</para>
<para>
As with DeepZoom, you can use <literal>--suffix</literal> to set jpeg quality.
</para>
<para>
Use <literal>--background</literal> 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.
</para>
<para>
Use <literal>--centre</literal> to add a border to the image large enough to centre the image within the lowest resolution tile. By default, images are not centred.
</para>
<para>
For example:
</para>
<programlisting>
$ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre
You can use <literal>--tile-size</literal> and <literal>--overlap</literal> to control how large the tiles are and how they overlap (obviously). They default to the correct values for the selected layout.
</para>
<para>
You can use <literal>--depth</literal> to control how deep the pyramid should be. Possible values are <literal>onepixel</literal>, <literal>onetile</literal> and <literal>one</literal>. <literal>onepixel</literal> means the image is shrunk until it fits within a single pixel. <literal>onetile</literal> means shrink until it fits with a tile. <literal>one</literal> means only write one pyramid layer (the highest resolution one). It defaults to the correct value for the selected layout. <literal>--depth one</literal> is handy for slicing up a large image into tiles (rather than a pyramid).
</para>
<para>
You can use <literal>--angle</literal> to do a 90, 180 or 270 degree rotate of an image during pyramid write.
</para>
<para>
You can use <literal>--container</literal> to set the container type. Normally dzsave will write a tree of directories, but with <literal>--container zip</literal> you’ll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically:
to write a zipfile containing the tiles. You can use <literal>.szi</literal> as a suffix to enable zip output as well.
</para>
<para>
Use <literal>--properties</literal> to output an XML file called <literal>vips-properties.xml</literal>. 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.
You can use <literal>.dz</literal> as a filename suffix, meaning send the image to <literal>vips_dzsave()</literal>. This means you can write the output of any vips operation to a pyramid. For example:
The arguments to <literal>extract_area</literal> 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.
</para>
<para>
If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example:
If you are building vips from source you do need to check the summary at the end of configure carefully. You must have the <literal>libgsf-1-dev</literal> package for <literal>vips_dzsave()</literal> to work.
