Fork me on GitHub

OpenSeadragon 4.1.0

example: overlays

Overlays are an important mechanism for displaying additional information on a zoomable image. Below we present a few examples of how to add some simple overlays.

The tile source in this example is from Chronicling America at the Library of Congress.

Highlighted Overlays

Highlighted overlays are useful for directing users' attention to specific areas of interest.

OpenSeadragon makes it easy to declare highlighted areas and control the presentation through simple CSS mechanisms. A tile source overlay is specific to the particular tile source. So if you have a sequence of tile sources and want to overlay unique content on each, use this mechanism.

Highlighted Overlays

The relevant configuration options are shown below.
The className and id attributes will be passed to the overlay element so you can bind CSS styles and events to it. Be sure to put your styles in the document head, inside the OpenSeadragon viewer element, or apply them dynamically so they will persist when full-screen mode is entered.
Prefer using outline instead of border to highlight the contours. Borders affect the size of the element causing the overlay to be misplaced.

OpenSeadragon({
    ...
    tileSources: [{
        ...
        overlays: [{
            id: 'example-overlay',
            x: 0.33,
            y: 0.75,
            width: 0.2,
            height: 0.25,
            className: 'highlight'
        }],
        ...
    }]
    ...
});

Fixed size Overlays

If you would like an overlay to point to a specific point in the image, you can omit the width and height parameters. In that case, the overlay will keep the same size independently of the zoom level. It is also possible to set which part of the overlay should be at the specified location by specifying a placement. For example, if your overlay is an arrow pointing to the right, you should set the placement to RIGHT.

Fixed size Overlays
Right arrow

The coordinates specified are those of the hand of the statue.
Note the checkResize property set to false. Because the arrow will not change size, we can tell OpenSeadragon to not verify its size at every frame. This improve performances if you have a lot of overlays.

OpenSeadragon({
    ...
    overlays: [{
        id: 'right-arrow-overlay',
        x: 0.2008,
        y: 0.4778,
        placement: 'RIGHT',
        checkResize: false
    }],
    ...
});

Viewport Overlays

OpenSeadragon also supports overlays that persist across image sequences. In this case the overlay is simply configured outside of the tileSource.

This example also demonstrates the ability to configure the overlay position in terms of image pixel coordinates. The difference is inferred from the use of px and py instead of x and y.

Viewport Overlays
OpenSeadragon({
    ...
    overlays: [{
        id: 'global-overlay-filter',
        px: 0,
        py: 0,
        width: 6425,
        height: 8535,
        className: 'filter'
    }],
    ...
});

Overlaying Complex HTML

By default OpenSeadragon checks for an existing element in the DOM that matches the overlay ID (if one is specified). If that content is found, OpenSeadragon will use it for the overlay. Otherwise, it will create a link to ensure keyboard accessibilty to the target (as in the examples above).

In this example we display some additional metadata to the right of the image itself.

Overlaying Complex HTML
Title:
The San Francisco call. : (San Francisco [Calif.]) 1895-1913
Alternative Titles:
  • Call
  • Call chronicle examiner
  • Call-chronicle-examinerApr. 19, 1906
  • Sunday call <Dec. 5, 1901>
Preceding Titles:
OpenSeadragon({
    ...
    preserveViewport: true,
    showNavigator: false,
    sequenceMode:  true,
    overlays: [{
        px: 6425,
        py: 0,
        id: 'html-overlay'
    }],
    tileSources: [{
        width: 6425,
        height: 8535,
        tileSize: 256,
        tileOverlap: 1,
        getTileUrl: chronicling_america_example(1)
    },{
        ...
    }]
}).addOnceHandler('open', function(event) {
    ...
    // MouseTracker is required for links to function in overlays
    new OpenSeadragon.MouseTracker({
        element: 'html-overlay',
        clickHandler: function(event) {
            var target = event.originalEvent.target;
            if (target.matches('a')) {
                if (target.getAttribute('target') === '_blank') {
                    window.open(target.getAttribute('href'));
                } else {
                    location.href = target.getAttribute('href');
                }
            }
        }
    });
});

Runtime Overlays

It is also possible to add overlays at runtime via Viewer.addOverlay.

Runtime Overlays
var viewer = OpenSeadragon({
    id:            "example-runtime-overlay",
    ...
});
var overlay = false;
document.querySelector('#toggle-overlay').addEventListener('click', function() {
    if (overlay) {
        viewer.removeOverlay("runtime-overlay");
    } else {
        var elt = document.createElement("div");
        elt.id = "runtime-overlay";
        elt.className = "highlight";
        viewer.addOverlay({
            element: elt,
            location: new OpenSeadragon.Rect(0.33, 0.75, 0.2, 0.25)
        });
    }
    overlay = !overlay;
});

Overlays and rotation

By default, the overlays get rotated with the viewport. One can change this behavior by setting the rotation mode property. NO_ROTATION will ignore the rotation. If both width and height are specified, BOUNDING_BOX will adapt the size of the overlay to contains the rotated rectangle.

Use the slider bar to set the rotation angle
Right arrow
var viewer = OpenSeadragon({
    id:            "example-overlay-rotation",
    ...,
    overlays: [{
        id: 'overlay-rotation-exact', // Green overlay
        x: 0.059,
        y: 0.08,
        width: 0.46,
        height: 0.59,
        rotationMode: OpenSeadragon.OverlayRotationMode.EXACT
    }, {
        id: 'right-arrow-overlay-no-rotate', // Arrow pointing to the tip of the hair
        x: 0.492,
        y: 0.496,
        placement: OpenSeadragon.Placement.RIGHT,
        rotationMode: OpenSeadragon.OverlayRotationMode.NO_ROTATION
    }, {
        id: 'overlay-rotation-bounding-box', // Yellow overlay
        x: 0.72,
        y: 1,
        width: 0.12,
        height: 0.18,
        rotationMode: OpenSeadragon.OverlayRotationMode.BOUNDING_BOX
    }]
});

Overlays and events

Events fired on elements hidden inside elements that are part of the viewer are managed by MouseTracker system. Trying to use vanilla JS or other utilities such as jQuery will fail.

Click on any overlay in the "Rotation" example above.
viewer.addHandler('open', () => {
    new OpenSeadragon.MouseTracker({
        element: document.getElementById('overlay-rotation-exact'),
        clickHandler: e => alert('Element clicked! ' + e.originalEvent.target.id),
        contextMenuHandler: e => alert('Context menu fired! ' + e.originalEvent.target.id),
    });
    new OpenSeadragon.MouseTracker({
        element: document.getElementById('right-arrow-overlay-no-rotate'),
        clickHandler: e => alert('Element clicked! ' + e.originalEvent.target.id),
        contextMenuHandler: e => alert('Context menu fired! ' + e.originalEvent.target.id),
    });
    new OpenSeadragon.MouseTracker({
        element: document.getElementById('overlay-rotation-bounding-box'),
        clickHandler: e => alert('Element clicked! ' + e.originalEvent.target.id),
        contextMenuHandler: e => alert('Context menu fired! ' + e.originalEvent.target.id),
    });
});