Fork me on GitHub

OpenSeadragon 4.1.1

Viewport Coordinates

OpenSeadragon zooms your images to fit into your webpage. To do this, it uses three coordinate systems: Image, Web, and Viewport.

Image coordinates are the actual pixels of your image. If the image is 1000px wide, its left side is at x = 0, and its right side is x = 1000.

Web coordinates are the normal "pixel" coordinates of the webpage. Note that this may not be physical screen pixels, if you're on a "retina" display.

Viewport coordinates are an arbitrary coordinate system that OpenSeadragon uses to allow you to lay things out, and to be a neutral space between image and web coordinates. They allow you to forget about how many pixels are in your image, and just think in terms of relative locations (i.e. halfway down the image).

By default, a single image will be placed with its left side at viewport x = 0 and its right side at viewport x = 1. The default top is at at viewport y = 0 and its bottom is wherever is appropriate for the image's aspect ratio. For instance, the bottom of a square image would be at y = 1, but the bottom of an image that's twice as wide as it is tall would be at y = 0.5.

Viewport coordinates become more interesting with multiple images in the same viewer. When you open the images, or add them later, you can specify x, y, and either width or height. If you specify the width, it will set the height automatically based on the aspect ratio; likewise for width if you specify height. It's entirely up to you where and how big you place your images, regardless of their resolution. You can mix high-resolution and low-resolution images side by side.

Different OpenSeadragon functions work with different systems; for instance, the MouseTracker generally deals with web coordinates, whereas the Viewport generally deals with viewport coordinates. The documentation for each function should make it clear. If you need to convert between coordinate systems, Viewport and TiledImage have functions that do so.

Also see the OpenSeadragonImagingHelper plugin, which has additional functions for working with the OpenSeadragon coordinate systems.


Here you can see the three coordinate systems as you mouse over the image. It also shows your zoom level, both in terms of the regular viewport zoom (where 1 means the image width fits the viewport exactly) and the image zoom (where 1 means the image is being shown at its full resolution).

Here's a code sample coordinate conversion, based on clicks:

// Assuming we have an OpenSeadragon Viewer called "viewer", we can catch the clicks 
// with addHandler like so:
viewer.addHandler('canvas-click', function(event) {
    // The canvas-click event gives us a position in web coordinates.
    var webPoint = event.position;

    // Convert that to viewport coordinates, the lingua franca of OpenSeadragon coordinates.
    var viewportPoint = viewer.viewport.pointFromPixel(webPoint);

    // Convert from viewport coordinates to image coordinates.
    var imagePoint = viewer.viewport.viewportToImageCoordinates(viewportPoint);

    // Show the results.
    console.log(webPoint.toString(), viewportPoint.toString(), imagePoint.toString());