Class: OpenSeadragonContext
Defined in: openseadragon/OpenSeadragonContext.ts:68
A wrapper around an OpenSeadragon viewer
In addition to creating and destroying the viewer, this class manages viewer options (including temporary overrides while the viewer is animating) and mutations of the viewer's world.
Additions are split in two: tile sources are opened concurrently, but the
world itself is mutated one operation at a time. World indices are shared
mutable state that every addition and removal invalidates, and OpenSeadragon
applies the index option only once an addition is committed - a microtask or
more after it was requested - so an index is valid only while nothing else
touches the world in between. Removals therefore go through the same queue as
additions, rather than being applied right away. Reordering the world
afterwards is not an alternative: the navigator mirrors index changes
positionally and on a timer, and corrupts its own world if it has not caught
up yet.
Queued world mutations are ordered by request, so a caller that removes tiled images before requesting additions still resolves its indices against the world as it is once those removals have been applied.
Tiled images can also be recolored: a tiled image whose pixels carry values
rather than colors is drawn by mapping each value to an RGBA color (see
updateTiledImageDataTransfer). As OpenSeadragon has no notion of a
per-image color mapping, it is applied to the tiles themselves, in a
tile-invalidated handler installed on the viewer. Data transfers are kept
per tile source, rather than per tiled image, which also covers the
navigator: it mirrors the world with tiled images of its own, but shares
their tile sources, and OpenSeadragon raises the invalidation events of its
tiles on this viewer. Its tiles are cached separately, though, so the
navigator's mirror of a tiled image is invalidated alongside the original
whenever the data transfer changes.
Constructors
Constructor
new OpenSeadragonContext(
viewerElement,viewerOptions?):OpenSeadragonContext
Defined in: openseadragon/OpenSeadragonContext.ts:109
Creates a new OpenSeadragonContext instance and initializes the OpenSeadragon viewer
Parameters
viewerElement
HTMLElement
DOM element in which the OpenSeadragon viewer is created
viewerOptions?
Options for configuring the OpenSeadragon viewer (optional)
Returns
OpenSeadragonContext
Properties
viewer
readonlyviewer:Viewer
Defined in: openseadragon/OpenSeadragonContext.ts:84
Methods
addTiledImage()
addTiledImage(
tiledImageOptions,options?):Promise<TiledImage>
Defined in: openseadragon/OpenSeadragonContext.ts:395
Adds a tiled image to the OpenSeadragon viewer
The tile source is opened right away, i.e. concurrently with the tile sources of other additions, but the tiled images are added to the world one after another, in the order in which they were requested. The index is resolved in between, when nothing else can shift the world anymore.
The tile source may also be a promise of an already opened tile source, which is only awaited once the addition is executed. Callers can thus derive a tile source from another one that is still being opened, without giving up their place in the queue and thereby their world index.
Rejects right away once the context has been destroyed.
Aborting before the addition is executed skips it entirely. Later than that,
the pending tile source load cannot be canceled anymore: the tiled image is
added, immediately removed again, and the returned promise rejects with the
signal's reason. Aborting a replacement (tiledImageOptions.replace) instead
resolves, as the replaced tiled image is already gone by then and removing
the new one, too, would leave a gap in the world.
Parameters
tiledImageOptions
Omit<OpenSeadragon.TileSourceSpecifier, "success" | "error">
Options for adding the tiled image, including the tile source
options?
Optional abort signal and index resolver. The latter takes
precedence over tiledImageOptions.index, and appends the tiled image to the
world if it returns undefined.
getIndex?
() => number | undefined
signal?
AbortSignal
Returns
Promise<TiledImage>
A promise that resolves with the added tiled image, or rejects if adding it failed or the operation was aborted
configureAnimationHandlers()
configureAnimationHandlers(
viewerAnimationStartOptions,viewerAnimationFinishOptions):void
Defined in: openseadragon/OpenSeadragonContext.ts:188
Installs OpenSeadragon animation-start and animation-finish handlers
On animation start, the current values of all keys of the start options are saved (for the viewer and for each tiled image having such a property) and the start options are applied. On animation finish, the saved values are restored, overridden by the finish options.
Only keys of the start options are saved and restored; keys appearing solely in the finish options are applied without ever being reverted. Likewise, only tiled images present at animation start have their values restored.
Calling this method again replaces any previously installed handlers.
Parameters
viewerAnimationStartOptions
Options to apply when an animation starts
viewerAnimationFinishOptions
Options to apply when an animation finishes
Returns
void
destroy()
destroy():
Promise<void>
Defined in: openseadragon/OpenSeadragonContext.ts:603
Destroys the OpenSeadragon viewer and cleans up resources
The context is marked as destroyed immediately (see isDestroyed), but the viewer is only destroyed once no world mutation is pending anymore, as their callbacks would otherwise run against a destroyed viewer. Marking the context as destroyed also stops further world mutations from being enqueued, so awaiting the queue's current tail is enough to drain it.
Returns
Promise<void>
getContainerSize()
getContainerSize():
Dims
Defined in: openseadragon/OpenSeadragonContext.ts:280
Returns the size of the viewer container element, in screen-space pixels
Returns
getTiledImageIndex()
getTiledImageIndex(
tiledImage):number
Defined in: openseadragon/OpenSeadragonContext.ts:451
Returns the index of a tiled image in the OpenSeadragon viewer's world
Parameters
tiledImage
TiledImage
The tiled image for which to get the index
Returns
number
The index of the tiled image, or -1 if it is not in the world
getViewport()
getViewport():
Rect
Defined in: openseadragon/OpenSeadragonContext.ts:267
Returns the currently visible viewport bounds in world coordinates
Reflects the current viewport, not the target of an ongoing animation.
Returns
isDestroyed()
isDestroyed():
boolean
Defined in: openseadragon/OpenSeadragonContext.ts:258
Returns whether destroy has been called
Turns true as soon as destruction starts, i.e. before pending world
mutations have settled and before the viewer is actually destroyed. Further
additions are rejected and further removals are ignored from that point on.
Returns
boolean
openTileSource()
openTileSource(
tiledImageOptions,options?):Promise<TileSource>
Defined in: openseadragon/OpenSeadragonContext.ts:340
Resolves a tile source specifier to a ready-to-use OpenSeadragon tile source
Fetches the image information if the specifier is a URL, awaits promised tile sources, and passes ready tile sources through. Doing this before an addition keeps the loading concurrent, while the additions themselves stay serialized (see addTiledImage).
Parameters
tiledImageOptions
Omit<OpenSeadragon.TileSourceSpecifier, "success" | "error">
Options containing the tile source to open
options?
Optional abort signal
signal?
AbortSignal
Returns
Promise<TileSource>
A promise that resolves with the opened tile source
removeTiledImage()
removeTiledImage(
tiledImage):Promise<void>
Defined in: openseadragon/OpenSeadragonContext.ts:436
Removes a tiled image from the OpenSeadragon viewer
The removal is queued behind the world mutations requested before it, so that it cannot shift the world while an addition is waiting for OpenSeadragon to apply its index. Does nothing once the context has been destroyed, as the viewer tears down its world itself.
Parameters
tiledImage
TiledImage
The tiled image to remove
Returns
Promise<void>
A promise that resolves once the tiled image has been removed.
resetViewport()
resetViewport():
void
Defined in: openseadragon/OpenSeadragonContext.ts:589
Hands viewport control back to the renderers
Fits the viewport to the bounds of the world, and resumes doing so whenever they change, until the user pans or zooms again. Call this when the content of the viewer is replaced, e.g. on opening a project.
Returns
void
setViewerOptions()
setViewerOptions(
viewerOptions):void
Defined in: openseadragon/OpenSeadragonContext.ts:293
Applies viewer options to the OpenSeadragon viewer and all existing tiled images
For each option key, performs a shallow merge (one level deep) of nested objects on both the viewer instance and every tiled image in the world.
Parameters
viewerOptions
Options to apply
Returns
void
updateBounds()
updateBounds(
newBounds,options?):Promise<TiledImage>
Defined in: openseadragon/OpenSeadragonContext.ts:539
Updates the world bounds spanned by a dummy tiled image
A dummy is a fully transparent single-tile image covering newBounds. As
OpenSeadragon derives the extent of its world from the bounds of its items,
such a dummy keeps the world bounds independent of which tiled images are
currently loaded, and it doubles as a stable index anchor for renderers.
The viewport is not fitted here: it follows the bounds of the world as a whole, for as long as the renderers own it (see resetViewport).
If dummy already spans newBounds, it is returned unchanged. Otherwise, a
new dummy is created at dummyIndex (defaulting to the index of dummy, or
appended if neither is specified) and dummy is removed. Where possible,
OpenSeadragon replaces dummy as part of the addition, so that the new dummy
takes its place without leaving a gap. Replacing dummy cannot be aborted
once the new dummy has been created, as that would leave the caller without a
dummy.
Parameters
newBounds
The new world bounds
options?
Optional abort signal, dummy to replace, and index at which to insert the new dummy
dummy?
TiledImage
dummyIndex?
number
signal?
AbortSignal
Returns
Promise<TiledImage>
A promise that resolves with the new (or the unchanged) dummy
updateTiledImageDataTransfer()
updateTiledImageDataTransfer(
tiledImage,dataTransfer):void
Defined in: openseadragon/OpenSeadragonContext.ts:482
Updates the data transfer of a tiled image
The data transfer is applied per tile: the tile's pixel values are
extracted and each is replaced by the color it maps to (see
DataTransfer). Passing undefined leaves the tiles as they are. It
is applied to every tile of the tiled image, including those loaded later.
The data transfer is remembered per tile source, until the tile source is
garbage-collected. Tiled images that share a tile source therefore also
share a data transfer, with the last one set winning - including the tiled
images of the navigator, which mirror those of this viewer and are
recolored along with them. As the navigator keeps a tile cache of its own,
which the invalidation of tiledImage does not reach, its tiled images
that share the tile source are invalidated explicitly, too. Those are few
low-resolution tiles, so this stays cheap; invalidating the whole viewer
would re-run every data transfer on every loaded tile instead.
Data transfers are compared by identity: the tiles are only invalidated, and thereby recolored from their original data, if a different data transfer object is passed. Callers are expected to pass the same object for as long as its outcome would not change, as invalidating the tiles re-runs the data transfer on every loaded tile of the tile source.
Parameters
tiledImage
TiledImage
The tiled image to update
dataTransfer
DataTransfer | undefined
The data transfer to apply, or undefined for none
Returns
void