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 and present huge images on the web using OpenSeadragon zooming technology. This course is for web developers who want to create truly unique web front-ends – with a focus on implementing immersive experiences with high-resolution images and interactive overlays using OpenSeadragon and Node.js.

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();
```