Frequently Asked Questions

I created an OpenSeadragon viewer. Why don't I see anything?
What do the zoom values mean?
Why do I see white borders between tiles?
OpenSeadragon doesn't work well on mobile devices in portrait orientation
OpenSeadragon isn't working right in my Vue application
Can I use TIFF files in OpenSeadragon?
How can I disable the default key bindings?

Questions and Answers

I created an OpenSeadragon viewer. Why don't I see anything?

The viewer must be given a non-zero size - both width and height - in order to see the results. Use your browser's developer tools to inspect the viewer element and see the width and height that are computed. One common problem is not defining the height of the viewer. Most of the time, width is non-zero by default, because div elements are full-width. However, if you have the viewer within a container with display: grid; or similar, you may need to define width or min-width to ensure the viewer can be seen.

What do the zoom values mean?

OpenSeadragon's zoom values are always relative to whatever size fills the width of the viewer. A zoom of 1 means the image width exactly fits the viewer width. A zoom of 2 means the image is twice the width of the viewer. We call this "viewport zoom", and it's particularly well suited to artworks, manuscripts, or anything where you care more about the overall image than the individual pixels. Note that a changes not only when you zoom in and out, but when you resize the viewer.

Another way of thinking about zoom is what we call "image zoom", where 1 means a 1:1 ratio between image pixels and screen pixels, 2 means a 2:1 ratio, etc. This perspective can be important for scientific imaging where you do care about the individual pixels.

You can convert between the two using imageToViewportZoom and viewportToImageZoom. Note that if you're using multi-image, you'll need to use the TiledImage versions of these functions.

Why do I see white borders between tiles?

Especially when using images with transparency, you may see seams between tiles. As of release 3.0.1, you can set subPixelRoundingForTransparency: OpenSeadragon.SUBPIXEL_ROUNDING_OCCURRENCES.ALWAYS to help address this visual artifact of the tile stitching operation (see https://github.com/openseadragon/openseadragon/discussions/2085#discussioncomment-1957842). Note that this does not fully solve the issue - for example, when the viewer and/or image are rotated, seams may still appear. This is due to intrinsic limitations of canvas context2d drawing, and an enhancement to support WebGL drawing is planned.

OpenSeadragon doesn't work well on mobile devices in portrait orientation

In portrait mode, by default the browser loads a much wider page and then zooms it down, which means the device doing a lot more work than it has to, and it can lead to major delays in loading and navigating an image. This behavior should be fixed by setting <meta name="viewport" content="width=device-width, initial-scale=1" /> in the <head> section of your HTML. (https://github.com/openseadragon/openseadragon/issues/2342#issuecomment-1524071957).

OpenSeadragon isn't working right in my Vue application

As of OpenSeadragon release 4.0.0, the technique that Vue2 uses to observe changes in objects/values interferes with the library. Vue3 should be used instead. If Vue2 must be used, to fix this issue, $.extend can be replaced by Object.assign here: ebab356c20/src/viewer.js (L1626)

Can I use TIFF files in OpenSeadragon?

OpenSeadragon doesn't support TIFF files directly, but you have a number of options. You could:

Convert your TIFF file to one of the formats OpenSeadragon supports, like DZI. There are lots of tools for that at https://openseadragon.github.io/examples/creating-zooming-images/.
Use a server that converts the TIFF file on the fly, like https://iipimage.sourceforge.io/.
Use the https://github.com/pearcetm/GeoTIFFTileSource plugin.

How can I disable the default key bindings?

The following code snippet will disable all of the default key bindings. You can edit the list of keys to be more specific depending on your application.

// suppress default OSD keydown handling for a subset of keys
viewer.addHandler('canvas-key',event=>{     
    if(['q', 'w', 'e', 'r', 'a', 's', 'd', 'f'].includes(event.originalEvent.key)){ 
        event.preventDefaultAction = true;
    }
});