DeepZoom (Part II): The Graphics::DZI API

(continued from Part I)

When you need to integrate the generation of DZI image pyramids into your own infrastructure, you should look first at Graphics::DZI::Files and not its superclass Graphics::DZI.

The Conventional Use Case

Objects of this class expect foremost the image to be tiled:

use Graphics::DZI::Files;
my $dzi = new Graphics::DZI::Files (image => $image);

As detailed in the manual page, you can add more parameters, such as tile size or the format.

So far nothing notable happened yet. The first thing you should do is to generate the root XML document:

my $xml = $dzi->descriptor;

The descriptor method will not write any file. Where this content goes, is completely up to you. (Maybe this will change in the future.)

The tiles themselves are then generated by iterating over the DZI structure:

$dzi->iterate ();

Logging With Log4Perl

One thing you will notice, is that every package in the distribution has its own $log object. I am using Log::Log4perl so that it is trivial to setup your own log object in your invoking program, too:

use Log::Log4perl qw(:easy);
our $log = Log::Log4perl->get_logger ("yourapp");
my $loglevel = 'DEBUG';
$log->level ($loglevel);

If you ever need to switch on debugging levels in some DZI package, then you can do this with

$Graphics::DZI::log         ->level ($loglevel);
$Graphics::DZI::Files::log  ->level ($loglevel);

Abstract Graphics::DZI

The Graphics::DZI package carries the basic algorithm. That is implemented in the iterate method which fires the method manifest whenever a tile is ready to be "output".

What that means, depends on your backend. Some people will prefer files to be written, some people will park the tiles into a cache object. Some people may even consider to stream tiles into a tar or even a cpio object. I have not implemented this; be my guest to create a Graphics::DZI::Tar or Graphics::DZI::cpio package.

Only the implementation Graphics::DZI::Files does the obvious, namely to create files.

Overlays (Collections)

In some cases you want one image to serve as canvas onto which other, more detailed images are to added in a montage. The "Contoso Fixster" demo at the Seadragon site is such a case.

Also here you generate the DZI object, and then iterate over it:

use Graphics::DZI::Files;
my $dzi = new Graphics::DZI::Files (image    => $image,
                                    overlays => \@os);
$dzi->iterate ();

But this time you have to prepare a sequence of Overlay objects. Each such object not only contains the image to be added: You also need to say

  • where the image is to be positioned in terms of x,y coordinates in the canvas image, and
  • how much the overlay image is to be made smaller than the canvas (i.e. is squeezed).

push @os,
     new Graphics::DZI::Overlay (image => ...,
                                 x => 3000,
                                 y => 2000,
                                 squeeze => 32);

The squeeze factor makes the overlay 32 times smaller than the canvas.

The implementation tries to be clever and will NOT resize the canvas accordingly. Instead, it will only virtually blow up those parts where there is one overlay in the neighborhood.

This dramatically saves not only memory during generation, but also disk space: Only those tiles will be output where there is actually any relevant detail. With that you should be able to handle fairly sizeable sparse collections.

But there is always room for improvement, of course.

Posted In


Happy to find such a wonderful thread to share about the DZI API.
It's very useful. Thanks a lot! :)

สถานที่ท่องเที่ยว (not verified) | Wed, 11/10/2010 - 07:21

Re: Thanks

I do EVERYTHING to keep the spammers happy.

rho | Mon, 01/31/2011 - 21:40