deepzoom - converting images into the DZI format


   # everything will be generated in the current directory
   deepzoom holidays.png

   # creating the relevant files somewhere else
   deepzoom --path=/var/www/ holidays.jpg

   # also renaming them
   deepzoom --path=/var/www/ --prefix=vienna holidays.jpg

   # converting a whole album
   deepzoom day1.jpg day2.jpg day3.jpg ...

   # trying this with a document
   deepzoom --document=linear page1.png page2.png page3.png ...


This program allows to convert one (large) image into a set of specifically designed image tiles, so that the image can be viewed with DeepZoom image clients (AJAX or MS SilverLight) with varying resolutions. Bootstrap yourself via

This program accepts image file names on the command line, and generates these tiles at a file system location of your choice. It also generates the XML descriptor as file.



Arguments are all names of image files. If one of them cannot be read by Image::Magick then the program will die.


Following command line switches are understood:

prefix (string, default: file name)

If provided, then the outgoing files (.xml and _files) will be prefixed with this. Otherwise the file name is used. In document mode (where all images are part of one larger) the prefix is derived from the first image.

path (string, default: current directory)

This option controls where the files are to be generated.

format (string, default: png)

This controls the format of the image pyramid.

NOTE: TIFF is not yet properly supported, in that each tile currently will be stored into a separate TIFF.

overlap (integer, default: 4)

This specifies how much the generated tile images will overlap.

tilesize (integer, default: 256)

The smaller the tiles, the more there will be, but the quicker each will load. The default or 256 works well for photos and graphics. For images containing text, a larger tile size is probably better.

loglevel (string, default: OFF)

The log level can be set to any of the following values: OFF FATAL ERROR WARN INFO DEBUG ALL

document (undef, linear or exponential, default: undef)

In document mode the program will interpret all images as images of pages of a single document. It will produce composite images of the first pages (of the document). In linear mode this is pages 1, 1-4, 1-9, 1-16, in exponential mode this are pages 1, 1-4, 1-16, 1-32, 1-64.

Depending on the resolution within the DeepZoom tiling process the above composites are consulted. The overall idea being that at some distance, one only sees the start page of a document, and the more you zoom in, the more pages you get to see.

stretch (integer, default: 1)

This integer stretch factor will be applied to the incoming image. It is ok to use if your image quality is not that high, but you still want to generate larger pictures. You will see some resizing artefacts at high resolutions.

NOTE: Does not work with the document mode (yet).


...does hopefully what you would expect.


You are running out of memory with large maps?

See and .

The process takes long time?

Well, that is just so. But one wise thing is to move all newly generated stuff into the target location when everything is finished.

Should not the package delete files before writing?

I do not think so, Tim. ;-)

Tile generation looks fine, but the tiles look completely distorted in the browser?

That happened to me when a PNG image had a "page geometry" which was different from the picture geometry. The tiles seem to inherit the page geometry and on the client side things get really messed up.


Robert Barta, <drrho at>


Copyright 2010 Robert Barta, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.