Tiled Images

[00:00 - 00:07] In the previous module, we used regular untiled images. This works fine if the images are only a few thousand pixels wide.

[00:08 - 00:17] But if the images are ten thousand pixels wide or more, you're not going to want to ask the user to wait to download the whole thing. Instead, we chop the images into tiles that can be loaded as needed.

[00:18 - 00:28] There are a number of tiled image formats and a number of tools available for converting images into them. For my projects, I generally use the DZI format, which is what OpenSeadragon started with.

[00:29 - 00:38] For converting, I use the VIPS command line tool. In this lesson, we'll install VIPS and use it to convert a 14,000 pixel tall image into a DZI.

[00:39 - 00:47] We'll also learn more about DZI and other tiled pyramid formats. Follow the installation instructions from the VIPS website.

[00:48 - 00:55] Then open a terminal window and type vips -v and hit return. It should show you the version information for the library.

[00:56 - 01:05] If you get an error like "vips is not recognized", you probably need to make sure that VIPS is in your system's PATH. This is important for using VIPS, so make sure to take care of it now.

[01:06 - 01:14] The details of adding a directory to your PATH depend on your system, so you'll need to look it up if you don't know how. Let's give it a spin. You'll need a giant image.

[01:15 - 01:27] Here's one that's about 14,000 pixels tall, courtesy of Wikimedia Commons. Download it and put it somewhere easy to get to on the command line, making sure to keep the same name, including the JPEG extension.

[01:28 - 01:32] Note that it takes a few seconds to load. This is why you don't want to have your page wait for the whole thing.

[01:33 - 01:49] Then open a terminal, cd to that location, and run this command. It'll think for a bit, and when it's done, there should be a file called pearl.dzi in the same folder, and a folder called pearl_files. If you open up the dZI, you'll see it looks like this.

[01:50 - 02:00] This is all the information OpenSeadragon needs to know how to put the tiles back together. If you open up pearl_files, you'll see a set of numbered folders. Each one is a tile level.

[02:01 - 02:12] The folder, with the biggest number, 14 in this case, contains tiles at full resolution. This is the only level needed to completely recreate the image, but the other levels are useful for when the viewer is zoomed out.

[02:13 - 02:23] Each level is half the resolution of the level above it, so level 13 is half size, level 12 is a quarter size, etc. all the way down to level 0, which is a single pixel.

[02:24 - 02:34] In practice, we don't use the very bottom levels, but they exist in the dZI format for historical reasons. Each of the tiles in the folder are numbered based on their X/Y position.

[02:35 - 02:43] The tile named 0_0.jpg is at the upper left corner. The 1_0.jpg is the tile just to the right of it.

[02:44 - 02:50] And 0_1.jpg is the one just below it. One of the nice things about this format is that it uses standard building blocks.

[02:51 - 03:00] The DZI file is XML, and the tiles, in this case, are JPEG. Because of this, you don't need a smart server to serve them. They can even be hosted on a CDN.

[03:01 - 03:08] Even though the DZI file is XML, some servers don't care for the DZI extension. We can change it to .xml, and it should serve fine.

[03:09 - 03:19] OpenSeadragon will happily open files with either extension. When we created the DZI, we gave it a tile size of 510, and the resulting file has TileSize="510".

[03:20 - 03:26] You'll notice that it also has a format and overlap, but these use default values. We'll discuss these options here.

[03:27 - 03:37] For more detail on vips dzsave, see the documentation. By default, the tile format, the format field, is JPEG. This is usually the best choice since it's universal and compresses well.

[03:38 - 03:46] If you want to have a DZI with transparent parts, however, you'll need to use PNG. You can specify that by adding this flag to your vips dzsave call.

[03:47 - 03:57] When tiles are drawn next to each other, there's a chance there could be visible seams at certain scales due to rounding errors. To avoid this, the DZI format includes a tile overlap feature.

[03:58 - 04:07] By default, vips dzsave gives you an overlap of 1, which in most cases should be perfect. You can change it using the overlap flag. For instance, overlap 0.

[04:08 - 04:27] One thing to be aware of with the overlap is that it affects how big the actual tiles are in combination with a tile size setting. You want tiles that aren't so big they take a lot of time to load, but big enough that it's worth a server round trip to get them, keeping in mind that some of your users will be on broadband, while others will be on mobile devices with poor connections.

[04:28 - 04:39] In addition, GPUs like images whose dimensions are powers of 2. I've found that a good balance is to go with 512x512 pixel images. To get this though, you don't just specify a tile size of 512.

[04:40 - 04:58] The overlap value gets added to each side of your tiles, so a tile size of 510 with an overlap of 1 will get you 512 pixel images. Note that the overlap is not added to every side of every tile, only the inside edges, any part of the tile that is not the actual edge of the original image.

[04:59 - 05:17] Every tile is governed by the tile size plus overlap, though the tiles along the right and bottom edges will sometimes be smaller if there aren't enough pixels in the original image to fill them out. Besides DZI, OpenSeadragon supports other formats. A very popular format is IIIF, or the International Image Interoperability Framework.

[05:18 - 05:26] Unlike DZI, it is most commonly used with specialized servers. For info on using it with OpenSeadragon, see the documentation.

[05:27 - 05:38] If you have some old Zoomify tiles and you want to swap in the OpenSeadragon viewer to take advantage of its UI and features, you can do so. For info on using them with OpenSeadragon, see the documentation.

[05:39 - 05:49] If you already have an image pyramid that's not in one of the standard formats, you can probably use it with the LegacyTileSource, or if need be, write your own custom tile source. There's a lot to digest here.

[05:50 - 06:04] Hopefully you now have a basic understanding of the purpose of tile pyramids and their general structure, as well as an overview of the different formats. You've installed VIPS, which is a handy tool for working with large images in a variety of ways, including preparing them for OpenSeadragon.

[06:05 - 06:09] In the next module, we'll take the DZI you've created and open it into your viewer.