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.

Every journey begins with a single step. Start this one with the simplest possible OpenSeadragon viewer you can make. In this module, you'll create a basic viewer that loads an image to fill the web page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>OpenSeadragon Basic Viewer</title>
    <style type="text/css"></style>
  </head>
  <body>
    <script type="text/javascript"></script>
  </body>
</html>

You need to add the OpenSeadragon library. You can find a number of options 

. For this example, you'll use the CDNJS version:

Now, in the script tag in the body, create a new OpenSeadragon viewer:

const options = {};
const viewer = OpenSeadragon(options);

This won't actually do anything. You need to give it some settings in the 

 object. At the bare minimum, you need to tell it where to go on the page and what image to load.

Since you're just running this straight on the webpage, you'll want to make sure that the div is above the 

 tag where you create the viewer. Otherwise, the div won't exist yet when the viewer is created, and you'll get an error.

Now include the ID for that div in the options so that OpenSeadragon knows about it:

const options = {
  id: 'osd-container'
};

---
title: Basic Viewer
description: Creating a basic viewer
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/3JkVc202E02QZx8TDkzaZs5oDWAezlLtj4PCWmDzrpHbc.m3u8
coverImageUrl: https://image.mux.com/3JkVc202E02QZx8TDkzaZs5oDWAezlLtj4PCWmDzrpHbc/thumbnail.png?time=7
code: https://gitlab.com/fullstackio/books/newline-course-apps/ian-gilman-newline-guide-to-displaying-huge-images-with-openseadragon-app/-/tree/main/code/module_02/lesson_02.01/src
---

## Basic Viewer

Every journey begins with a single step. Start this one with the simplest possible OpenSeadragon viewer you can make. In this module, you'll create a basic viewer that loads an image to fill the web page.

<ReplitEmbed
  src="//replit.com/@newlineauthors/OpenSeadragon-2-1-Basic-Viewer"
/>

### Empty Web Page

Start with a basic web page template:

```html { actualFilename=./protected/src/index0.html endChar=235 endLine=12 startChar=0 startLine=1 statedFilename=index0.html url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_02/lesson_02.01/protected/src/index0.html }
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>OpenSeadragon Basic Viewer</title>
    <style type="text/css"></style>
  </head>
  <body>
    <script type="text/javascript"></script>
  </body>
</html>
```

### Include the Openseadragon Library

You need to add the OpenSeadragon library. You can find a number of options [here](http://openseadragon.github.io/#download). For this example, you'll use the CDNJS version:

```html { actualFilename=./protected/src/index.html endLine=6 startLine=6 statedFilename=index.html url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_02/lesson_02.01/protected/src/index.html#L6 }
    <script src="https://cdnjs.cloudflare.com/ajax/libs/openseadragon/2.4.2/openseadragon.min.js"></script>
```

### Create the Viewer

Now, in the script tag in the body, create a new OpenSeadragon viewer:

```javascript
const options = {};
const viewer = OpenSeadragon(options);
```

This won't actually do anything. You need to give it some settings in the `options` object. At the bare minimum, you need to tell it where to go on the page and what image to load.

### Give It a Home

So you need a div for it to live in:

```html
<div id="osd-container"></div>
```

Since you're just running this straight on the webpage, you'll want to make sure that the div is above the `script` tag where you create the viewer. Otherwise, the div won't exist yet when the viewer is created, and you'll get an error.

Now include the ID for that div in the options so that OpenSeadragon knows about it:

```javascript
const options = {
  id: 'osd-container'
};
```

OpenSeadragon doesn't support generic selectors, just IDs. You can, however, supply an element instead. For example:

```javascript
const options = {
  element: document.querySelector('#osd-container')
};
```

### Give It an Image

OpenSeadragon is most powerful when using specially prepared images broken up into tiles, but it can work with simple images as well. For starters, do that. I went to [Unsplash](https://unsplash.com) and grabbed this URL to an image:

<https://images.unsplash.com/photo-1501785888041-af3ef285b470>

the simplest possible OpenSeadragon viewer you can make.

In this module, you'll create a basic viewer that

We'll start with a basic web page template.

We need to add the OpenSeadragon library.

For this example, we'll use the CDNJS version.

Now, in the script tag in the body, we want to

We need to give it some settings in the options object.

At the bare minimum, we need to tell it where to go on the page

Since we're just running this straight on the web page,

you'll want to make sure that the div is above the script tag

Otherwise, the div won't exist yet when the viewer is created

Now, include the ID for that div in the options so that

OpenSeadragon doesn't support generic selectors, just IDs.

You can, however, supply an element instead. For example.

OpenSeadragon is most powerful when using specially prepared images

but it can work with simple images as well.

I went to Unsplash and grabbed this URL to an image.

OpenSeadragon takes a tileSources setting in its options object that can take

For this sort of single image, you pass it an object with type "image" and an URL

You can run it by starting a local server or even just loading the page into

Give it a try, but you'll see that all you get is an empty page, so there's one

The OpenSeadragon viewer automatically fills whatever space you give

It doesn't change the size of the div itself.

Because of this, you always need to style your container

Otherwise, you'll get a zero pixel viewer.

So let's add some CSS to the styles section of the page.

You should see the image filling the window.

Use the scroll wheel on your mouse to zoom the image

If you're using a trackpad instead of a mouse, it should have a scroll gesture.

For instance, the two finger drag that works for zoom.

If you test on a touch device, you can pinch to zoom directly on the viewer.

If refreshing the page doesn't work, your browser may have cached

To avoid this, I have Chrome's developer console set to no cache when the

The OpenSeadragon buttons don't have their icon images for starters.

That can be fixed by giving the prefix URL for those images in the options,

We're using the URL from CDNJS to match where the library came from.

The other issue, if you really want the viewer to fill the page, is that the

The result should look like this after you've zoomed a little.

You've made your first OpenSeadragon viewer.

It may seem humble, but it's a good foundation for what's to come.

In the upcoming lessons, we'll go into more depth on how to customize it for

starting with adding multiple images in the next lesson.