The latest CC3+ update is 28 (version 3.98, released June 1st 2022). Download it from your Registration page.

Deepzoom images for web display

roflo1roflo1 Surveyor
edited November 2021 in Cartographic Resources

While reading the World Builder's Compendium, I opened the beautiful Earlsdale map by Grimur Fjeldsted ( and realized I actually know a more efficient way to serve a very large image in the web for everyone to view.

Why is this an issue?

Well you see, when you open the webpage above, the server sends you a single, 12MB, 7300 x 5902 image. And then a script allows you to zoom and pan. And while 12MB is not that much by today's standards, what if you want to serve a 73000 x 59000 image? Well, you'd have a 1.2GB image, for starters, and it's time to look for other options.

Enter OpenSeadragon. And deepzoom images.

There are many formats equivalent to Deepzoom (or DZI), but I'll only talk about DZI (sometimes also called a "pyramid image"). Take the following screenshot of this folder as an example:

In this example, I split a 15000 x 12000 image in smaller tiles, each 256 x 256 pixels; and they're inside a folder named "14" where 14 is the deepest zoom level available. In other words, these tiles have the maximum resolution I have available for this map.

At a zoom level of 10, these are the files in the corresponding folder:

They're still 256 x 256 pixels (except at the edges), but they are downscaled. And this is where the beauty of a script like OpenSeadragon comes in.

If you zoom out the window, the server will send you the downscaled images, because that's what you really need to be displayed in your window. And if you zoom in, only a few high-resolution tiles will be sent to you (a link to the working example is at the end).

If you've ever used Google Maps, you've already used something similar.

How to do it?

To create all the "tiles" in one go, I discovered this tool called vips. It's a programming library and much more, but it does come with a single command-line tool (vips.exe) that offers most -if not all- the functionality.

To create a deepzoom image, you should type something like this:

vips.exe dzsave "MyBigImage.jpg" MyResultingDZI

But do mind the paths and quotes (quotes are mandatory if any folder or file name has a space in them):

"C:\Path\To\vips.exe" dzsave "C:\Path\To\MyBigImage.jpg" MyResultingDZI

This will create, in your current folder, the following:

  • A text file named MyResultingDZI.dzi
  • A folder named MyResultingDZI_files (this folder contains the "zoom level" subfolders with the tiles)

In order to upload this to your webpage, you need to create an HTML webpage and upload the OpenSeadragon scripts (which you can download from here).

A bare-bones HTML file looks like this:



 <title>OSR Dungeon</title>

  <script src="./openseadragon-bin-2.4.2/openseadragon.min.js"></script>



<div id="openseadragon1" style="width: calc(100% - 20px); height: calc(100% - 20px);"></div>

<script type="text/javascript">

  var viewer = OpenSeadragon({

    id: "openseadragon1",

    prefixUrl: "./OSRblue_files/",

    tileSources: "./OSRblue.dzi"





Note that the id "openseadragon1" is used in both the div and when creating the instance in the script.

You'd need to place this HTML file in a public folder in your webpage, and place the other resources (bolded above) in the specified location. In this case, the .dzi file is in the same folder as my HTML file, the OpenSeadragon script (openseadragon.min.js) is in a subfolder named openseadragon-bin-2.4.2, and the generated pyramid files also next to the HTML file.

Also, I had to move the OpenSeadragon images (the navigation icons in openseadragon-x-x-x/images/) to my pyramid folder ("OSRblue_files"), so the navigation "buttons" actually display an image.

And this is the resulting web page:


If you already have multiple tiled images, and want to "glue" them and create the DZ in one step, you can still use vips like this:

vips.exe arrayjoin "File1.jpg File2.jpg File3.jpg File4.jpg" --across 2

(of course, assuming 4 files, arranged 2 images across)



Sign In or Register to comment.