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.

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

The newline Guide to Displaying Huge Images with OpenSeadragon

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 lesson, you added overlays to all the images, but having all those overlays displayed all the time is kind of distracting. How about you just show them when you hover over their image? In this lesson, you'll do just that.

To do this, you can hook up an OpenSeadragon 

. OpenSeadragon does a lot of complicated event handling, so it's best to use its systems for events, rather than just using the browser's 

. For the click events, you are listening for the 

 event, but for hover, you need to now watch the mousemove events, and the viewer doesn't produce an event for that. Internally, the viewer uses a 

, which does have additional events, including mousemove. You can add your own at the end of the 

const tracker = new OpenSeadragon.MouseTracker({
  element: viewer.element,
  moveHandler: event => {
    const viewportPos = viewer.viewport.viewerElementToViewportCoordinates(event.position);
    console.log(viewportPos);
  }
});

Give it a try. Open up the developer console and see the numbers as you mouse around.

Okay, what you want to do is figure out where you've moved onto and show the overlay for that image. In order for that to make a difference, you're going to want to hide all the overlays at the beginning! To do that, you can introduce a new CSS class, 

.text-overlay.hidden {
  opacity: 0;
  pointer-events: none;
}

 style definition so the overlays can fade in and out nicely:

. There are several places you could do this, but doing it in the 

 is probably best. That way, rearranging the images hides any hovers.

With that groundwork in place, you can return to your 

. You'll want to find out who got hit by the mouse, so you can use 

 because that's where you stored the overlays. Now, refactor 

Don't forget to update everywhere that calls 

const imageRec = getHit(viewportPos);

if (imageRec) {
  const bounds = imageRec.tiledImage.getBounds(true);
  ...

---
title: Hover
description: Track the mouse movement to hide and show the text overlays on hover
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/l4NMoeztxSQVXyccnvxvTaWr2dze7HL6QCe00DhDlHu8.m3u8
coverImageUrl: https://image.mux.com/l4NMoeztxSQVXyccnvxvTaWr2dze7HL6QCe00DhDlHu8/thumbnail.png?time=159
code: https://gitlab.com/fullstackio/books/newline-course-apps/ian-gilman-newline-guide-to-displaying-huge-images-with-openseadragon-app/-/tree/main/code/module_06/lesson_06.02/src
---

## Hover

In the previous lesson, you added overlays to all the images, but having all those overlays displayed all the time is kind of distracting. How about you just show them when you hover over their image? In this lesson, you'll do just that.

<ReplitEmbed
  src="//replit.com/@newlineauthors/OpenSeadragon-6-2-Hover"
/>

### MouseTracker

To do this, you can hook up an OpenSeadragon `MouseTracker`. OpenSeadragon does a lot of complicated event handling, so it's best to use its systems for events, rather than just using the browser's `addEventListener`. For the click events, you are listening for the `canvas-click` event, but for hover, you need to now watch the mousemove events, and the viewer doesn't produce an event for that. Internally, the viewer uses a `MouseTracker`, which does have additional events, including mousemove. You can add your own at the end of the `main` function, like so:

```javascript
const tracker = new OpenSeadragon.MouseTracker({
  element: viewer.element,
  moveHandler: event => {
    const viewportPos = viewer.viewport.viewerElementToViewportCoordinates(event.position);
    console.log(viewportPos);
  }
});
```

Give it a try. Open up the developer console and see the numbers as you mouse around.

### Hiding the Overlays

Okay, what you want to do is figure out where you've moved onto and show the overlay for that image. In order for that to make a difference, you're going to want to hide all the overlays at the beginning! To do that, you can introduce a new CSS class, `hidden`. Add this new style to your `main.css` file (don't replace the existing `.text-overlay` style definition):

```css
.text-overlay.hidden {
  opacity: 0;
  pointer-events: none;
}
```

Add this one line to your `text-overlay` style definition so the overlays can fade in and out nicely:

```css
  transition: opacity 0.4s linear;
```

Then, apply the `hidden` class to all of your overlays back in `main.js`. There are several places you could do this, but doing it in the `forEach` in `updateLayout` is probably best. That way, rearranging the images hides any hovers.

```javascript
overlay.classList.add('hidden');
```

### Refactoring

With that groundwork in place, you can return to your `moveHandler`. You'll want to find out who got hit by the mouse, so you can use `getHit`. What you really want, though, is the `imageRec` rather than the `tiledImage` because that's where you stored the overlays. Now, refactor `getHit` to return the imageRec:

```javascript { actualFilename=./protected/src/main.js endChar=687 endLine=34 startChar=426 startLine=23 statedFilename=main.js url=https&#x3A;//gitlab.com/fullstackio/books/newline-guide-to-displaying-huge-images-with-openseadragon/module_06/lesson_06.02/protected/src/main.js#L23 }
function getHit(viewportPos) {
  let hitImageRec = null;

  imageRecs.forEach((imageRec) => {
    const bounds = imageRec.tiledImage.getBounds(true);
    if (bounds.containsPoint(viewportPos)) {
      hitImageRec = imageRec;
    }
  });

  return hitImageRec;
}
```

Don't forget to update everywhere that calls `getHit` so it uses an `imageRec`. It should be just the `canvas-click` handler:

```javascript
const imageRec = getHit(viewportPos);

if (imageRec) {
  const bounds = imageRec.tiledImage.getBounds(true);
  ...
```

### Showing the hovered overlay

Now in the `moveHandler`, you can use it there too!

```javascript
const imageRec = getHit(viewportPos);
if (imageRec) {
  imageRec.overlay.classList.remove('hidden');
}
```

Give it a run. None of the overlays should be visible at first, and as you mouse over them, you should see them fading into view.

### Hiding When the Mouse Moves Away

This is nice, but of course you want them to also hide again when you mouse away. For that, you'll have to keep track of which one you currently have hovered, so you can hide it again when it changes. You can add a `hoverImageRec` to your globals:

```javascript { actualFilename=./protected/src/main.js endChar=52 endLine=3 startChar=27 startLine=3 statedFilename=main.js url=https&#x3A;//gitlab.com/fullstackio/books/newline-guide-to-displaying-huge-images-with-openseadragon/module_06/lesson_06.02/protected/src/main.js#L3 }
let hoverImageRec = null;
```

This is a good time to make a function that sets the new hover image and hides the old one:

```javascript
function setHoverImageRec(imageRec) {
  if (imageRec === hoverImageRec) {
    return;
  }

  if (hoverImageRec) {
    hoverImageRec.overlay.classList.add('hidden');
  }

  hoverImageRec = imageRec;

  if (hoverImageRec) {
    hoverImageRec.overlay.classList.remove('hidden');
  }
}
```

Now in the `moveHandler` you can just call `setHoverImageRec` with the `imageRec` you got from `getHit`:

```javascript
setHoverImageRec(imageRec);
```

Note that it'll do the right thing with a real image rec or with `null`, so it's fine to give it whatever comes out of `getHit`.

### Details

Remember how you hid everyone when you changed the layout? You should update the `hoverImageRec` to match, at the bottom of `updateLayout`:

```javascript
setHoverImageRec(null);
```

One more detail while you're in here. If the user mouses out of your viewer or switches away to another window, it would be good to dismiss the hover. You can do that by adding a `leaveHandler` to the `MouseTracker`:

In the previous lesson, you added overlays to the images, but showing all the

overlays all the time is a bit distracting.

How about you only show an overlay when you hover over an image? In this lesson

To do this, we can hook up an OpenC Dragon mouse tracker.

OpenC Dragon does a lot of complicated event handling, so it's best to use its

systems for events, rather than just using the browser's ad event listener.

For the click events, we are listening to the Canvas click event, but for hover

, we need to now watch the mouse move events, and the viewer doesn't produce an

Internally, the viewer uses a mouse tracker, which does have additional events,

including mouse move. We can add our own at the end of the main function, like

Give it a try. Open up the developer console and see the numbers as you mouse

Okay, what we want to do is figure out where you've moved on to and show the

overlay for that image. In order for that to make a difference, we're going to

want to hide all the overlays at the beginning.

To do that, we can introduce a new CSS class, Hidden. Add this new style to

your main.css file. Add this one line to your text overlay style definition, so

Then we want to apply the hidden class to all of our overlays back in main.js.

There are several places we could do this, but doing it in the for each and

update layout is probably best. That way, rearranging the images hides any ho

With that groundwork in place, we can return to our move handler. We'll want to

find out who got hit by the mouse, so we can use get hit.

What we really want, though, is the image rack rather than the tiled image,

because that's where we store the overlays. Let's refactor get hit to return

Don't forget to update everywhere the calls get hit so it uses an image rack.

It should be just the canvas click handler.

Now, in the move handler, you can use it there, too.

Give it a run. None of the overlays should be visible at first, and as you

mouse over them, you should see them fading into view.

This is nice, but of course we want them to also hide again when you mouse away

For that, we'll have to keep track of which one we currently have hovered, so

We can add a hover image rack to our globals. This is a good time to make a

function that sets the new hover image and hides the old one.

Now, in the move handler, you can just call set hover image rack with the image

Note that it'll do the right thing with a real image rack or with null, so it's

fine to give it whatever comes out of get hit.

Remember how we hit everyone when we change the layout? We should update the

hover image rack to match at the bottom of update layout.

One more detail while we're in here. If the user mouse is out of your viewer or

switches away to another window, it would be good to dismiss the hover.

You can do that by adding a leave handler to the mouse tracker.

Of course, hovers don't work on mobile devices, which is probably where a lot

For them, how about we add the overlays whenever they tap on an image and turn

off the overlays when they tap out of an image?

That's easily added to the click handler.

You've learned about the mouse tracker and used it to follow the mouse. You've

done some more refactoring and now have a nice system to keep track of overlay

And of course, you're hiding and showing the overlays. Congratulations, you've

Read on for some closing thoughts, but first, check out the next lesson for

some exercises to practice what you learned in this module.