Introduction

OpenSeadragon

Basic Viewer

Take a look at two modes that help you arrange multiple images

Sequence and Collection Modes

Some exercises to help you practice what you have learned

Module 2 Exercises

Viewer Basics

Look at what to do when your image is huge

Tiled Images

Loading the DZI file into your OpenSeadragon viewer

Loading Your DZI

Automation

Build a pipeline that generates DZI files for you, as well as a data file containing information about all of those files

Pipeline

Module 3 Exercises

Loading the Images

Arrange the images in a trim and proper way

Arranging the Images

Add another arrangement and a toggle button to switch between both

Multiple Arrangements

Module 4 Exercises

Multi-Image

Make clicking in the viewer zoom you directly to whatever image you clicked on

Clicking on Images

Write a custom animation that moves smoothly from one image to another, zooming out in the middle for a nice overview

Custom Animation

Module 5 Exercises

Navigation

Add text overlays to the images to show additional information

HTML Overlays

Track the mouse movement to hide and show the text overlays on hover

Hover

Module 6 Exercises

Conclusion

Overlays

High-resolution imagery is all around us. Once the domain of high-end photography, now even our phones have many megapixels. OpenSeadragon is the premier tool for displaying these images on the web. Other tools exist, but they are either focused on geographic data, or they lack versatility and polish. OpenSeadragon has a lively community and is used throughout the world by artists, libraries, museums, medical/scientific institutions, etc.

With OpenSeadragon, you can display images too big to view on the screen, or even too big to send all at once, and seamlessly transition from low resolution to high resolution with no extra coding. OpenSeadragon works across devices, from tiny phone screens to giant wall displays.

By its very nature (allowing the user to zoom into ultra-high resolution images), OpenSeadragon has a number of very powerful concepts that may not be intuitive at first (tile pyramids, multiple coordinate systems, etc.). This course will give you a solid working understanding of those concepts. We will then dive further into many of the advanced techniques possible with OpenSeadragon to take your app to the next level. Throughout, we will work with real, functioning apps that you will build from start to finish.
  
This course is taught by Ian Gilman, the creator and maintainer of OpenSeadragon.

Transform huge images into immersive experiences

In this course, you'll learn how to prepare huge images for immersive viewing on the web using OpenSeadragon zooming technology.

OpenSeadragon Deep Dive

The key concepts behind OpenSeadragon, including tile pyramids and viewport coordinates.

How to collect huge images and convert them into a format suitable for efficient display,using the VIPS command line tool.

How to build a pipeline for converting large numbers of images, using Node.js.

How to display all of the images together in the same viewer.

How to arrange the images however you want, and how to animate between arrangements.

User interaction with the images, including custom animated movement between images, using Tween.js.

Adding overlays with additional information and links, using the OpenSeadragon HTML Overlay plugin.

In the previous module, a regular, un-tiled single image was used. This works fine when your images are only a few thousand pixels wide. However, if you want to show an image that's 10,000 pixels wide or more, you won't want to ask the user to wait to load the entire thing. Instead, chop the image into tiles that can be loaded as needed.

There are several tiled image formats and a 

 available for converting images into them. For my projects, I generally use the DZI format, which is what OpenSeadragon started with. To convert, I use the 

In this lesson, you'll install VIPS and use it to convert a 14,000-pixel tall image into a DZI. You'll also learn more about DZI and other tiled pyramid formats.

, and hit return. It should show you the version information for the library.

If you get an error like "vips is not recognized", you probably need to make sure that vips is in your system's 

. This is important for using vips, so be sure to take care of it now! 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. This 

Let's give it a spin! You'll need a giant image. Here's one that's about 14,000 pixels tall (

https://upload.wikimedia.org/wikipedia/commons/0/0f/1665_Girl_with_a_Pearl_Earring.jpg

Download it and put it somewhere easy to get to on the command line, making sure to keep the same name, including the 

 extension. 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!

vips dzsave 1665_Girl_with_a_Pearl_Earring.jpg pearl --tile-size 510

It'll think for a bit, and when it's done, there should be a file called 

If you open up the DZI, you'll see it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<Image xmlns="http://schemas.microsoft.com/deepzoom/2008"
  Format="jpeg"
  Overlap="1"
  TileSize="510"
  >
  <Size
    Height="14550"
    Width="12285"
  />
</Image>

---
title: Tiled Images
description: Look at what to do when your image is huge
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/vCc00OxtVSTRnDSjVHPPY01ZzKzMmqARqdkZgJIGXlYvg.m3u8
coverImageUrl: https://image.mux.com/vCc00OxtVSTRnDSjVHPPY01ZzKzMmqARqdkZgJIGXlYvg/thumbnail.png?time=168
code: https://gitlab.com/fullstackio/books/newline-course-apps/ian-gilman-newline-guide-to-displaying-huge-images-with-openseadragon-app/-/tree/main/code/module_03/lesson_03.01/src
---

## Tiled Images

### The Importance of Being Tiled

In the previous module, a regular, un-tiled single image was used. This works fine when your images are only a few thousand pixels wide. However, if you want to show an image that's 10,000 pixels wide or more, you won't want to ask the user to wait to load the entire thing. Instead, chop the image into tiles that can be loaded as needed.

There are several tiled image formats and a [number of tools](http://openseadragon.github.io/examples/creating-zooming-images/) available for converting images into them. For my projects, I generally use the DZI format, which is what OpenSeadragon started with. To convert, I use the [VIPS](https://libvips.github.io/libvips/) command line tool.

In this lesson, you'll install VIPS and use it to convert a 14,000-pixel tall image into a DZI. You'll also learn more about DZI and other tiled pyramid formats.

### Installing VIPS

Follow the instructions [here](https://libvips.github.io/libvips/install.html), then open a terminal window and type `vips -v`, and hit return. It should show you the version information for the library.

:::important

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 be sure to take care of it now! 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. This [post](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7) could be a good starting point.

:::

### Using VIPS

Let's give it a spin! You'll need a giant image. Here's one that's about 14,000 pixels tall ([courtesy of Wikimedia Commons](http://commons.wikimedia.org/wiki/File:1665_Girl_with_a_Pearl_Earring.jpg)):

<https://upload.wikimedia.org/wikipedia/commons/0/0f/1665_Girl_with_a_Pearl_Earring.jpg>

Download it and put it somewhere easy to get to on the command line, making sure to keep the same name, including the `jpg` extension. 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!

Then open a terminal and `cd` to that location and run:

`vips dzsave 1665_Girl_with_a_Pearl_Earring.jpg pearl --tile-size 510`

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`.

## The DZI Format

If you open up the DZI, you'll see it looks like this:

```html { actualFilename=./protected/src/dzi.xml endChar=207 endLine=12 startChar=0 startLine=1 statedFilename=dzi.xml url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.01/protected/src/dzi.xml }
<?xml version="1.0" encoding="UTF-8"?>
<Image xmlns="http://schemas.microsoft.com/deepzoom/2008"
  Format="jpeg"
  Overlap="1"
  TileSize="510"
  >
  <Size
    Height="14550"
    Width="12285"
  />
</Image>
```

In the previous module, we used regular untiled images.

This works fine if the images are only a few thousand pixels wide.

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.

There are a number of tiled image formats and a number of tools available for

For my projects, I generally use the DZI format, which is what OpenSeadragon

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

We'll also learn more about DZI and other tiled pyramid formats.

Follow the installation instructions from the VIPS website.

Then open a terminal window and type vips -v and hit return.

It should show you the version information for the library.

If you get an error like "vips is not recognized", you probably need to make sure

This is important for using VIPS, so make sure to take care of it now.

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.

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.

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.

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

and a folder called pearl_files. If you open up the dZI, you'll see it looks

This is all the information OpenSeadragon needs to know how to put the tiles

If you open up pearl_files, you'll see a set of numbered folders. Each one is a

The folder, with the biggest number, 14 in this case, contains tiles at full

This is the only level needed to completely recreate the image, but the other

levels are useful for when the viewer is zoomed out.

Each level is half the resolution of the level above it, so level 13 is half

all the way down to level 0, which is a single pixel.

In practice, we don't use the very bottom levels, but they exist in the dZI

Each of the tiles in the folder are numbered based on their X/Y position.

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.

One of the nice things about this format is that it uses standard building

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

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.

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

You'll notice that it also has a format and overlap, but these use default

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.

If you want to have a DZI with transparent parts, however, you'll need to use

You can specify that by adding this flag to your vips dzsave call.

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.

By default, vips dzsave gives you an overlap of 1, which in most cases should be

You can change it using the overlap flag. For instance, overlap 0.

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.

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.

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

any part of the tile that is not the actual edge of the original image.

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.

Unlike DZI, it is most commonly used with specialized servers.

For info on using it with OpenSeadragon, see the documentation.

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.

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