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.

Up to now, you've been converting files directly in your script folder. However, for a real project, you'll want things to be more organized. If you have dozens of images, you won't necessarily want to download them all manually. Moreover, you might have additional information about these images that you want to access in your app. In this lesson, you'll upgrade your script to support all these needs.

I've collected a number of large images from Wikimedia Commons for you to work with. I've stored them in a JSON file called 

, with each image being an object inside the 

 (the web page that gives more information about that image). You'll want to convert the image but also store the page URL so that you can use it in your web app.

Warning: Together, these images take up a lot of space (1.16 GB for the original images and 650 MB for the DZIs). If you don't have much free space on your hard drive, consider cutting down this list before working with it. The file called Lambda20210907_003_ABCD.png is the biggest (453 MB by itself), so it would be the first one to drop.

Note that the DZI files are actually smaller than the original images in this case, even though the DZI files make up a fully-tiled pyramid and, therefore, have multiple copies of the image at different sizes. This is because the default 

 image compression is evidently greater than the original image compression. If you have the same image compression all around, the DZI should theoretically take up about 1.333 times the amount of space as the original (because the DZI includes the original plus a quarter-size version, plus a quarter of that, etc.). The most dramatic case here is 

, which is being converted from a 453 MB PNG to a series of JPG tiles adding up to 138 MB; this is because JPG naturally compresses more than PNG in most cases.

Now, it's time to update your script. Start with the script from the previous lesson. The first step is to load the JSON data like so:

const json = fs.readFileSync('./image-source-data.json', {
  encoding: 'utf8'
});

 module, which is Node's collection of file system functions. You'll need to require it:

Previously, you worked with images you had downloaded manually, but now automate the downloading process based on the image URLs in your data file. To keep things organized, download them into a folder. First, specify the download location using Node's 

const downloadDst = path.join('.', 'download');
// The download function automatically creates the folder if needed,
// so we don't need to do it ourselves.

Now, make your loop run through the images from the JSON:

for (const data of imageData.images) {
  const fileName = data.imageUrl;

But in this case, you also need to install it (since it's not built into Node). Add a quick 

{
  "dependencies": {
    "download": "^8.0.0"
  }
}

The npm command line tool would love for you to have more details in your 

, but for your purposes, this is all you need.

Go to the script's folder in your terminal and run the install:

You should be able to run the script now and have it download the files. Keep in mind that it may take a while, depending on your internet connection speed! You'll need to comment out the conversion step for now since you haven't yet updated that. The script so far should look like this:

And you can run it in the terminal like so (assuming it's called pipeline.js):

---
title: Pipeline
description: Build a pipeline that generates DZI files for you, as well as a data file containing information about all of those files
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/we00kB5XwIBdk4zbn2IRSfvJx9tsLcW6ksWnjrPjCSFA.m3u8
coverImageUrl: https://image.mux.com/we00kB5XwIBdk4zbn2IRSfvJx9tsLcW6ksWnjrPjCSFA/thumbnail.png?time=339
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.04/src
---

## Pipeline

### Keeping Things Organized

Up to now, you've been converting files directly in your script folder. However, for a real project, you'll want things to be more organized. If you have dozens of images, you won't necessarily want to download them all manually. Moreover, you might have additional information about these images that you want to access in your app. In this lesson, you'll upgrade your script to support all these needs.

### Collecting Images

I've collected a number of large images from Wikimedia Commons for you to work with. I've stored them in a JSON file called `image-source-data.json`, with each image being an object inside the `images` array. Each image has an `imageUrl` (the actual image file) and a `pageUrl` (the web page that gives more information about that image). You'll want to convert the image but also store the page URL so that you can use it in your web app.

```json { actualFilename=./protected/src/image-source-data.json endChar=2670 endLine=53 startChar=0 startLine=1 statedFilename=image-source-data.json url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/image-source-data.json }
{
  "images": [
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/4/48/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/7/78/30_Doradus%2C_Tarantula_Nebula.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:30_Doradus,_Tarantula_Nebula.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/c/cf/1562_Americ%C3%A6_Guti%C3%A9rrez.JPG",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:1562_Americæ_Gutiérrez.JPG"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/1/1e/15U_Mar_21_2013_0725Z.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:15U_Mar_21_2013_0725Z.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/0f/1665_Girl_with_a_Pearl_Earring.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:1665_Girl_with_a_Pearl_Earring.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/c/ce/20100121130111NidarosdomenPanorama.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:20100121130111NidarosdomenPanorama.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/6/62/1_zhangjiajie_huangshizhai_wulingyuan_panorama_2012.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:1_zhangjiajie_huangshizhai_wulingyuan_panorama_2012.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/c/c5/1_furong_panorama_2012.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:1_furong_panorama_2012.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/c/c7/111_Pileated_Woodpecker.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:111_Pileated_Woodpecker.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/2/25/1_rocinha_night_2014_panorama.jpg",
      "pageUrl": "http://commons.wikimedia.org/wiki/File:1_rocinha_night_2014_panorama.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/en/f/f3/Franti%C5%A1ek_Kupka_-_Katedr%C3%A1la_-_Google_Art_Project.jpg",
      "pageUrl": "https://en.wikipedia.org/wiki/File:Franti%C5%A1ek_Kupka_-_Katedr%C3%A1la_-_Google_Art_Project.jpg"
    },
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/01/Lambda20210907_003_ABCD.png",
      "pageUrl": "https://en.wikipedia.org/wiki/File:Lambda20210907_003_ABCD.png"
    }
  ]
}
```

Warning: Together, these images take up a lot of space (1.16 GB for the original images and 650 MB for the DZIs). If you don't have much free space on your hard drive, consider cutting down this list before working with it. The file called Lambda20210907_003_ABCD.png is the biggest (453 MB by itself), so it would be the first one to drop.

Note that the DZI files are actually smaller than the original images in this case, even though the DZI files make up a fully-tiled pyramid and, therefore, have multiple copies of the image at different sizes. This is because the default `vips dzsave` image compression is evidently greater than the original image compression. If you have the same image compression all around, the DZI should theoretically take up about 1.333 times the amount of space as the original (because the DZI includes the original plus a quarter-size version, plus a quarter of that, etc.). The most dramatic case here is `Lambda20210907_003_ABCD.png`, which is being converted from a 453 MB PNG to a series of JPG tiles adding up to 138 MB; this is because JPG naturally compresses more than PNG in most cases.

### Loading the JSON

Now, it's time to update your script. Start with the script from the previous lesson. The first step is to load the JSON data like so:

```javascript { actualFilename=./protected/src/pipeline1.js endChar=296 endLine=10 startChar=209 startLine=8 statedFilename=pipeline1.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/pipeline1.js#L8 }
const json = fs.readFileSync('./image-source-data.json', {
  encoding: 'utf8'
});
```

Use the built-in `fs` module, which is Node's collection of file system functions. You'll need to require it:

```javascript
const fs = require('fs');
```

### Downloading the Images

Previously, you worked with images you had downloaded manually, but now automate the downloading process based on the image URLs in your data file. To keep things organized, download them into a folder. First, specify the download location using Node's `path` module:

```javascript { actualFilename=./protected/src/pipeline1.js endChar=55 endLine=2 startChar=26 startLine=2 statedFilename=pipeline1.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/pipeline1.js#L2 }
const path = require('path');
```

```javascript { actualFilename=./protected/src/pipeline1.js endChar=499 endLine=16 startChar=337 startLine=14 statedFilename=pipeline1.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/pipeline1.js#L14 }
const downloadDst = path.join('.', 'download');
// The download function automatically creates the folder if needed,
// so we don't need to do it ourselves.
```

Now, make your loop run through the images from the JSON:

```javascript
for (const data of imageData.images) {
  const fileName = data.imageUrl;
```

And use the `download` library to download them:

```javascript
await download(fileName, downloadDst);
```

Of course, you'll need to require `download`:

```javascript { actualFilename=./protected/src/pipeline1.js endChar=93 endLine=3 startChar=56 startLine=3 statedFilename=pipeline1.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/pipeline1.js#L3 }
const download = require('download');
```

But in this case, you also need to install it (since it's not built into Node). Add a quick `package.json` to your script's folder, listing `download` as a dependency:

```json { actualFilename=./protected/src/package.json endChar=53 endLine=6 startChar=0 startLine=1 statedFilename=package.json url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/package.json }
{
  "dependencies": {
    "download": "^8.0.0"
  }
}
```

The npm command line tool would love for you to have more details in your `package.json`, but for your purposes, this is all you need.

Go to the script's folder in your terminal and run the install:

`npm install`

You should be able to run the script now and have it download the files. Keep in mind that it may take a while, depending on your internet connection speed! You'll need to comment out the conversion step for now since you haven't yet updated that. The script so far should look like this:

```javascript { actualFilename=./protected/src/pipeline1.js endChar=947 endLine=36 startChar=0 startLine=1 statedFilename=pipeline1.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_03/lesson_03.04/protected/src/pipeline1.js }
const fs = require('fs');
const path = require('path');
const download = require('download');
const util = require('util');
const exec = util.promisify(require('child_process').exec);

async function main() {
  const json = fs.readFileSync('./image-source-data.json', {
    encoding: 'utf8'
  });

  const imageData = JSON.parse(json);

  const downloadDst = path.join('.', 'download');
  // The download function automatically creates the folder if needed,
  // so we don't need to do it ourselves.

  for (const data of imageData.images) {
    const fileName = data.imageUrl;
    console.log('Starting', fileName);
    try {
      await download(fileName, downloadDst);

      // const command = `vips dzsave ${fileName}.jpg ${fileName} --tile-size 510`;
      // await exec(command);
      console.log('Success!', fileName);
    } catch (err) {
      console.log('Error!', fileName, err);
    }
  }

  console.log('Done with loop');
}

main();
```

So far, we've just been converting files directly in the script folder, but for

a real project, we'll want things to be more organized.

Also, if you have dozens of images, you probably don't want to have to be

Furthermore, you may have additional information about the images that you want

In this lesson, we'll upgrade our script to support all these needs.

I've gone to Wikimedia Commons and found a number of large images for us to

I've stored them in a JSON file called image-source-data.json, with each image

Each image has an imageUrl, the actual image file, and a pageUrl, the web

page that gives more information about that image.

We'll want to convert the image, but also store the pageUrl so that we can use

Keep in mind that, together, these images take up a lot of space, 1.16 GB for

the original images and 650 MB for the DZIs.

If you don't have much free space on your hard drive, you'll want to cut down

This file, with the name starting with Lambda, is the biggest, 453 MB by itself,

Note that the DZI files are actually smaller than the original images in this

case, even though the DZI files make up a fully tiled pyramid and therefore

have multiple copies of the image at different sizes.

This is because the default vips dzsave image compression is evidently greater

If we have the same image compression all around, the DZI should theoretically

take up about 1 1/3 times the amount of space as the original,

because the DZI includes the original plus 1/4 size version plus 1/4 of that,

The most dramatic case here is the Lambda file, which is being converted from a

453 MB PNG to a series of JPEG tiles adding up to 138 MB.

This is because JPEG naturally compresses more than PNG in most cases.

Okay, it's time to update our script. We're starting with the script from the

The first step is to load in the JSON data, like so.

We're using the built-in fs module, which is Node's collection of file system

Before, we worked with images we had downloaded manually, but now let's

automate the downloading process based on the imageUrls in our data file.

To keep things organized, let's download them into a folder.

First, we specify the download location using Node's path module.

We can now make our loop run through the images from the JSON, and use the

Of course, we'll need to require download, but in this case we also need to

install it since it's not built into Node.

Add a quick package.json to your scripts folder, listing download as a

The npm command line tool would love for you to have more details in your

package.json, but for our purposes, this is all you need.

Go to the scripts folder in your terminal and run the install.

You should be able to run the script now and have it download the files.

You'll need to comment out the conversion step for now, since we haven't yet

You can run it in the terminal like so, assuming it's called pipeline.js.

Keep in mind that it may take a while depending on your internet connection

Okay, let's step back a moment and get ourselves some names for things.

We've just been using fileName, but that's not really accurate anymore since

Furthermore, we'll want to use the whole URL for the download, but then just

For instance, the URL for one of the images is this.

But for the file that results from the download, we just want this.

And then the DZI file, we want to name this.

To help us with that, we can use the url Node module.

Inside our for loop, we can parse the imageUrl and get the file name without

Note that we're also decoding the special URI codes like %2c for comma.

We do this because the server needs to have unencoded file names to match the

For instance, when we ask for this, the server will look for this.

We could of course get around this by not having file names with special

characters, but this is the sort of real world data you'll have to deal with,

In our app, we'll also want a name to display for the image.

While we could include a hand-picked name for each image in our image-source-

data.json, we can just clean up the file name a little for now by using the

decoded URL and converting underscores to spaces like so.

Now that we have our prettyName, we can retire the old fileName and use

prettyName for all of our logging and just use data.imageUrl for the download

For the conversion, we need to know where we are finding the image, where it

was downloaded, and where we want it to be converted to.

To keep things organized, let's have a DZI folder, creating it if necessary.

Note that convertSrc includes the file extension, since that will be part

of the downloaded file, but convertDsc does not, because vips dzsave

Okay, with that info, we can now do our conversion.

Since you've already downloaded the files from the previous step, you can

comment out the download portion for now.

Now that we have all of our images converted, we also want to save all the info

We'll save that out as a JSON named image-data.json for use in our client-side

We'll need an array to collect the image info in.