In the previous lesson, you loaded your DZIs into your viewer and displayed them all in a row using OpenSeadragon's collection mode. The 

 feature is nice for quick mockups, but if you want full control over the layout, you'll need to handle it yourself. In this lesson, you'll learn how to move images around in the OpenSeadragon viewer and how to build your own custom arrangement.

To take control of the arrangement, turn off collection mode by removing 

. If you do this and run it, you'll see that it leaves all the images stacked directly on top of each other, overlapping. This is because OpenSeadragon expects you to explicitly state where to put all the images.

One way to lay out the images is during the Viewer creation. You can specify image positioning as part of the 

 option. So far, you've just been providing an array of image URLs like so:

tileSources: [
  '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi',
  '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
]

To start, do a simple arrangement that just has each image next to the previous one in a big row. This is similar to what the collection mode does, but an important difference is that whereas the collection mode places the images in a uniform grid, you can allow the image shape to dictate how much width it takes up.

Instead of passing your tile sources in as simple URLs, you can pass in objects that give OpenSeadragon additional information about where you want them placed. For instance:

tileSources: [
  {
    x: 0,
    y: 0,
    tileSource: '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi'
  },
  {
    x: 1,
    y: 0,
    tileSource: '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
  }
]

By default, each image has a width of 1 in viewport coordinates, so this will put them right next to each other. The height of the image is whatever matches the width with the appropriate aspect ratio; so, for instance, an image with a 16:9 aspect ratio and a width of 1 would have a height of 0.5625. An image that is twice as tall as it is wide would have a height of 2.

Sometimes, it's nice to think in bigger numbers. You can change the scale of your coordinates simply by giving your images bigger sizes. For instance:

tileSources: [
  {
    width: 1000,
    x: 0,
    y: 0,
    tileSource: '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi'
  },
  {
    width: 1000,
    x: 1000,
    y: 0,
    tileSource: '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
  }
]

That will look exactly the same on the screen as the previous example because OpenSeadragon automatically zooms wherever the images are, regardless of their size.

For this example, you'll have all the images be the same height as each other and just further apart for wide images and closer for narrow ones. For this, you need to know the aspect ratio of each image, which is not something you have in the data. You could certainly include that in your pre-processing, but in this case, you'll gather that data dynamically once the images have been loaded.

---
title: Arranging the Images
description: Arrange the images in a trim and proper way
isPublicLesson: true
privateVideoUrl: https://stream.mux.com/yboyKbvJNDtZY501AaACxXGD01v9kFKhEUfe1gVEOOUXw.m3u8
coverImageUrl: https://image.mux.com/yboyKbvJNDtZY501AaACxXGD01v9kFKhEUfe1gVEOOUXw/thumbnail.png?time=290
code: https://gitlab.com/fullstackio/books/newline-course-apps/ian-gilman-newline-guide-to-displaying-huge-images-with-openseadragon-app/-/tree/main/code/module_04/lesson_04.02/src
---

## Arranging the Images

In the previous lesson, you loaded your DZIs into your viewer and displayed them all in a row using OpenSeadragon's collection mode. The `collectionMode` feature is nice for quick mockups, but if you want full control over the layout, you'll need to handle it yourself. In this lesson, you'll learn how to move images around in the OpenSeadragon viewer and how to build your own custom arrangement.

<ReplitEmbed
  src="//replit.com/@newlineauthors/OpenSeadragon-4-2-Arranging-the-Images"
/>

### Removing Collection Mode

To take control of the arrangement, turn off collection mode by removing `collectionMode: true` and `collectionRows: 1`. If you do this and run it, you'll see that it leaves all the images stacked directly on top of each other, overlapping. This is because OpenSeadragon expects you to explicitly state where to put all the images.

![Screenshot of the viewer with all images stacked on top of each other](https://d2uusema5elisf.cloudfront.net/courses/newline-guide-to-displaying-huge-images-with-openseadragon/module_04/lesson_04.02/public/stacked-on-each-other.jpg)

### Arranging at Creation Time

One way to lay out the images is during the Viewer creation. You can specify image positioning as part of the `tileSources` option. So far, you've just been providing an array of image URLs like so:

```javascript
tileSources: [
  '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi',
  '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
]
```

To start, do a simple arrangement that just has each image next to the previous one in a big row. This is similar to what the collection mode does, but an important difference is that whereas the collection mode places the images in a uniform grid, you can allow the image shape to dictate how much width it takes up.

Instead of passing your tile sources in as simple URLs, you can pass in objects that give OpenSeadragon additional information about where you want them placed. For instance:

```javascript
tileSources: [
  {
    x: 0,
    y: 0,
    tileSource: '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi'
  },
  {
    x: 1,
    y: 0,
    tileSource: '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
  }
]
```

By default, each image has a width of 1 in viewport coordinates, so this will put them right next to each other. The height of the image is whatever matches the width with the appropriate aspect ratio; so, for instance, an image with a 16:9 aspect ratio and a width of 1 would have a height of 0.5625. An image that is twice as tall as it is wide would have a height of 2.

Sometimes, it's nice to think in bigger numbers. You can change the scale of your coordinates simply by giving your images bigger sizes. For instance:

```javascript
tileSources: [
  {
    width: 1000,
    x: 0,
    y: 0,
    tileSource: '/dzi/2016_Official_Portrait_of_Our_Lady_of_Solitude_of_Porta_Vaga.dzi'
  },
  {
    width: 1000,
    x: 1000,
    y: 0,
    tileSource: '/dzi/30_Doradus%2C_Tarantula_Nebula.dzi'
  }
]
```

That will look exactly the same on the screen as the previous example because OpenSeadragon automatically zooms wherever the images are, regardless of their size.

### Arranging Dynamically

For this example, you'll have all the images be the same height as each other and just further apart for wide images and closer for narrow ones. For this, you need to know the aspect ratio of each image, which is not something you have in the data. You could certainly include that in your pre-processing, but in this case, you'll gather that data dynamically once the images have been loaded.

Arrange the images in a trim and proper way

Arranging the Images

In the previous lesson, you loaded your DZIs into the viewer and displayed them

all in a row using OpenSeadragon's collection mode.

The collection mode feature is nice for quick mock-ups, but if you want full

control over the layout, you'll want to take care of yourself.

In this lesson, you'll learn how to move images around in the OpenSeadragon

viewer and how to create your own custom arrangement.

In order to take control of the arrangement, we need to turn off collection

mode by removing collectionMode: true and collectionRows: 1.

If you do so and run it, you'll see that it leaves all the images stacked

directly on top of each other, overlapping.

This is because OpenSeadragon is expecting you to explicitly state where to put

One way to lay out the images is during the viewer creation. You can specify

image positioning as part of the tileSources option.

So far, we've just been giving an array of image URLs like so.

For starters, we'll do a simple arrangement that just has each image next to

This is similar to what the collection mode does for us, but an important

difference is that whereas the collection mode places the images in a uniform

grid, we can allow the image shape to dictate how much width it takes up.

Instead of passing our tile sources in as simple URLs, we can pass in objects

that give OpenSeadragon additional information about where we want them placed.

By default, each image has a width of 1 in viewport coordinates, so this will

The height of the image is whatever matches the width with the appropriate

So, for instance, an image with a 16 by 9 aspect ratio and a width of 1 would

An image that is twice as tall as it is wide would have a height of 2.

Sometimes it's nice to think in bigger numbers. You can change the scale of

your coordinates simply by giving your images bigger sizes.

That will look exactly the same on the screen as the previous example, because

OpenSeadragon automatically zooms to wherever the images are, regardless of

For our example, we'd like to have all the images be the same height as each

other and just further apart for wide images and closer for narrow ones.

For this, we need to know the aspect ratio of each image, which is not

We could certainly include that in our pre-processing, but in this case, we're

going to gather that data dynamically once the images have been loaded.

Opening the images is an asynchronous operation, so we need to wait for the

viewer's open event to know when the images are ready, like so.

Once the viewer is properly loaded up, we can access all of its images through

The world is how the viewer keeps track of its images, which is stored as a

If any of the images overlap, the images lower in the stack are obscured by

You can find out how many images there are by using the world's getItemCount

And you can get a specific image by passing its place in the stack into the

Each item in the world is a TiledImage, with all sorts of functions for

manipulating how they look and where they are positioned.

In our case, we just want to use setPosition to place them somewhere and

setHeight to make sure they are all the same height.

Once we've set each one's position and height, we can measure it with getBounds

To keep track, we can add an x variable above our loop.

If you give it a try, it should work, but you'll notice some funky things.

For one thing, the viewport doesn't update for the new layout, so you're left

zoomed into the upper left corner of the first image.

Remember that by default, all of the images were stacked in the range of 0 to 1

in viewport coordinates, and now we've told each image to be 1000 units wide.

That means we're just looking at the leftmost 1000th of the image.

After we loop through and set the positions of all the images, we can tell the

This works because the viewport's idea of where home is gets updated every time

Now you can see it zooms out automatically.

It's an animated zoom though, and in this case, we probably just want to start

We can accomplish this by passing true into the function, meaning do it

There are many places in OpenSeadragon that automatically animate, but you can

turn off the animation by passing in a true flag.

Now we start out zoomed out, but you can see the images themselves also animate

That could be fixed by adding true flags to the set position and set height

One subtle detail is that the new position is stored immediately, even if it's

That means if you call getBounds, it already tells you the new final location,

not wherever along the animation path it may be at the moment.

If you really want to know exactly where it is in its animation, you can call

getBounds(true), and it'll give you the true current location.

Do you see the difference from how collection mode laid the images out?

Unlike collection mode, all of the images are now the same height.

Also, the space between the images is now consistent.

Now that you have your own arrangement code, you can tweak those values as much

Okay, your code should look like this. I've taken the liberty of putting the

1000 height and the true for the immediately flag into constants to make the

You're now loading all your converted images into the viewer.

In the next lesson, we'll get into the multi-image API so you can arrange them

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Masterclasses

Tutorials

Fullstack React with TypeScript