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

---
title: Custom Animation
description: Write a custom animation that moves smoothly from one image to another, zooming out in the middle for a nice overview
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/uayKGKFgECvAlgw5yYsAlboIiOrMUdnHqB02FgPBgzmk.m3u8
coverImageUrl: https://image.mux.com/uayKGKFgECvAlgw5yYsAlboIiOrMUdnHqB02FgPBgzmk/thumbnail.png?time=396
code: https://gitlab.com/fullstackio/books/newline-course-apps/ian-gilman-newline-guide-to-displaying-huge-images-with-openseadragon-app/-/tree/main/code/module_05/lesson_05.02/src
---

import VideoEmbed from '~/components/VideoEmbed'

## Custom Animation

In the previous lesson, you learned how to zoom in on a single image using the default spring animation. In many cases, this is all you need, but sometimes, it's nice to be able to create your own custom animations.

You might want to add the ability to go to a specific image from wherever the user happens to be zoomed/panned. You can use the standard OpenSeadragon `fitBounds` to animate to the new location, but that can be a very fast transition if you're going long distances. You can write your own animation if you have something smoother in mind. In this lesson, you'll do just that.

<ReplitEmbed
  src="//replit.com/@newlineauthors/OpenSeadragon-5-2-Custom-Animation"
/>

### UI First

In this case, just add a "random image" button. For starters, you'll use the built-in OpenSeadragon animation, and then you'll write your own.

Drop a button in your toolbar in the HTML:

```html
<button class="random-image">Random Image</button>
```

Add a little margin to your buttons so they're not jammed up against each other:

```css
button {
  margin-bottom: 10px;
}
```

### Basic Spring Animation

Now hook up a handler for the new button in your `main` function:

```javascript
document.querySelector('.random-image').addEventListener('click', () => {
  const index = Math.floor(Math.random() * viewer.world.getItemCount());
  const tiledImage = viewer.world.getItemAt(index);
  const imageBounds = tiledImage.getBounds(true);
  viewer.viewport.fitBounds(imageBounds);
});
```

This should look pretty familiar. It's very similar to the code for animating to an image that you've clicked on.

Give it a try! It should whip you around the viewer at a good clip. Keep in mind that since it's completely random, sometimes it won't do anything because it's already on the image that it chose to go to.

### Smoother Animation: Tween.js

To create a custom animation, you need to introduce your own animation system, and for each frame, you'll tell OpenSeadragon where to go, always using the `immediately` flag so it doesn't try to animate as well.

For doing custom animations, I recommend the ["tween.js" library](https://tweenjs.github.io/tween.js/). It's nice and simple but gets the job done.

To add it to the project, you need to add it to the HTML:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/18.6.4/tween.umd.js"></script>
```

In the JavaScript, to support the animation, you need to create a `requestAnimationFrame` loop that repeatedly calls `TWEEN.update`.

```javascript { actualFilename=./protected/src/main.js endChar=165 endLine=9 startChar=51 startLine=5 statedFilename=main.js url=https&#x3A;//gitlab.com/fullstackio/books/openseadragon-deep-dive/module_05/lesson_05.02/protected/src/main.js#L5 }
function animate(time) {
  requestAnimationFrame(animate);
  TWEEN.update(time);
}
requestAnimationFrame(animate);
```

In production, you would want to only do this loop when actually animating, but for this example, just let it run all the time. When there aren't any tweens, `TWEEN.update` is quite fast, so it's not a real performance problem.

### Example Tween

Tween.js basically has one mission: to change an object's properties from their starting values to some new values over time. Here's a very simple example:

```javascript
const point = { x: 0, y: 0 };

const tween = new TWEEN.Tween(point)
  .to({ x: 100, y: 200 }, 5000)
  .onUpdate(() => {
    console.log(point);
  });

tween.start();
```

It creates a point object with x and y of 0, 0. Then, it creates a tween with that object and specifies that the tween should animate to x, y of 100, 200 over the next 5000 milliseconds. It gives the tween a function to get periodically called as it animates, and logs the current value to the console. Then it tells the tween to start! That's enough to make it work since you have already set up the update loop above.

That's pretty much all you need to know for this lesson, but if you're interested in learning more about Tween.js, check out [its documentation](https://tweenjs.github.io/tween.js/docs/user_guide.html).

### Tweening Your Pan Position

Okay, back to your app. What you want to create is a nice smooth pan from image to image, zooming out some in the middle to give the user an overview of where they are going (and to make it so it's not just a close-up of the images flying by). You'll want to build this animation up; start with just the panning portion.

Get rid of the `fitBounds` and instead create a tween:

```javascript
const duration = 5000; // Five seconds

const panTween = new TWEEN.Tween(viewBounds.getCenter())
  .to(imageBounds.getCenter(), duration)
  .easing(TWEEN.Easing.Quadratic.InOut)
  .onUpdate((point) => {
    viewer.viewport.panTo(point, true);
  });

panTween.start();
```

This is very similar to the example tween, with a few differences:

-   For the tweened object, just pass in the result of `viewBounds.getCenter()`, which creates a new `OpenSeadragon.Point`. Remember that Tween.js modifies the object you give it, so you have to be sure you don't mind the object changing. In this case, it's no problem since `getCenter` creates a new object.
-   You didn't put the `getCenter` result into a variable that you could access inside the `onUpdate`, but that's not a problem because onUpdate passes the tweened object into your update function.
-   You're asking it to apply an "easing". This makes the animation vary in speed throughout its duration to create a more naturalistic effect. Because the easing you supplied is an `InOut` easing, the animation will start off slowly and build up speed, then slow back down at the end.
-   Of course, instead of console.logging, you're actually using the point to pan the viewer! Note that pass `true` for the `immediately` argument of the `panTo` function; this disengages the springs since you are handling the animation yourselves.

So, as you can see, you're panning from the center of the current viewport bounds to the center of the image bounds over the course of 5 seconds.  

Go ahead and give it a try. Notice that it's only panning and not zooming at all. This means that if you're all the way zoomed out when you hit the "Random Image" button, it'll stay zoomed out but move so the new image is centered on the screen. If you're already zoomed in on an image, it'll move you across to the new image, but it won't zoom you in or out to properly frame the new image. So, you need to add zooming to this animation!

### Adding in Zooming

The first step is to learn where you're zooming from and to. Where you're zooming from is easy; it's the current zoom:

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