How to make Deep Zoom images with OpenSeaDragon


If you want to show off a huge image on the web, I think the best way is by creating a deep zoom image with Open Sea Dragon.

I recently built Flagthousand using this technique:

Flagthousand: World’s biggest map of flags

Making the map took years, but the website was pretty easy to setup. I’m excited to make and share more massive infographics using this method.

Using this guide below, you can be up and running in a few minutes:

Step 1: Create your Deep Zoom Image

Install VIPS using homebrew on your terminal. If you don’t have homebrew, here’s a guide to set up homebrew and other basics.

brew install vips

Export your huge image as a JPG from Illustrator and then run this command to turn your huge picture into a tiled set.

vips dzsave "path/to/your/bigexport.jpg" hugegraphic --tile-size 1022 --suffix .png --overlap 1    

I set mine as PNG because my image is so graphical and can compress it into sharp graphics. If you’re working with a photo, I think it makes more sense to use JPG.

So you’re making a huge photo you would just remove --suffix .png in this code below if you’re exporting.

Step 2: Upload your files and make a page on your site:

Take those files you just exported, and upload the hugegraphic.dzi file and hugegraphic_files folder to your website server.

Finally, make an html file like this on your server:

<!DOCTYPE html>
    <title>Gigapixel Image Viewer</title>
        body, html {
            margin: 0;
            padding: 0;
            width: 100%;
            height: 100%;
        #openseadragon {
            width: 100%;
            height: 100%;
    <script src=""></script>
    <div id="openseadragon"></div>
        var viewer = OpenSeadragon({
            id: "openseadragon",
            animationTime: 0.1,
            prefixUrl: "",
            tileSources: "hugegraphic.dzi"
        viewer.addHandler('open',()=> = ()=>false );

And that’s it!

Just save this file as index.html and upload it next to your hugegraphic.dzi file and hugegraphic_files that you uploaded earlier.

There’s a huge range of additional things you can do with these images, including custom buttons, overlays and more that you can explore on the OpenSeaDragon site.

Bonus: Compressing your Tiled Images

One additional thing thing you can do is compress the exported files. This can take about an hour, but it means quicker load time of tiles on your website.

OpenSeaDragon does not (at the time of writing) support the next gen image formats AVIF and WebP. I’m a big fan of AVIF files, and I believe they will support both formats in the upcoming version.

That said, I found I was able to compress the PNG files quite a bit using ImageOptim, which is a great app for mac. You can simple drag the whole folder of tiled png files into it and it will compress it down to 20% of the size.

Here’s the settings I used on ImageOptim:

Common Issue: White lines with the PNG with OpenSeaDragon

One issue I ran into, is that with PNG’s on OpenSeaDragon, it will show white lines. There are a couple reasons you might see this, but in my case it was because OpenSeaDragon thinks that the PNG file might be transparent. And so what would happen, is it thinks that two anti-aliased images are butting up against each other, so you’re seeing those transparent edges overlayed on the image.

bdrichards solved this by adding a line of code (which I’ve added above already for you):

viewer = OpenSeadragon({...});
viewer.addHandler('open',()=> = ()=>false );

If you have any questions, feel free to drop a comment or send me an email.

Leave a comment

Your email address will not be published. Required fields are marked *