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 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.
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'
}],
...
}]
...
});
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.
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
}],
...
});
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.
OpenSeadragon({
...
overlays: [{
id: 'global-overlay-filter',
px: 0,
py: 0,
width: 6425,
height: 8535,
className: 'filter'
}],
...
});
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.
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');
}
}
}
});
});
It is also possible to add overlays at runtime via Viewer.addOverlay.
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;
});
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.
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
}]
});
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.
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),
});
});