Class: DziTileSource

OpenSeadragon.DziTileSource

Members Methods

new DziTileSource(width, height, tileSize, tileOverlap, tilesUrl, fileFormat, displayRects)

Parameters:
Name Type Description
width Number | Object the pixel width of the image or the idiomatic options object which is used instead of positional arguments.
height Number
tileSize Number
tileOverlap Number
tilesUrl String
fileFormat String
displayRects Array.<OpenSeadragon.DisplayRect>
Properties:
Name Type Description
tilesUrl String
fileFormat String
displayRects Array.<OpenSeadragon.DisplayRect>
Source:

Extends

Members

aspectRatio :Number

Ratio of width to height
Type:
  • Number
Inherited From:
Source:

dimensions :OpenSeadragon.Point

Vector storing x and y dimensions ( width and height respectively ).
Type:
Inherited From:
Source:

maxLevel :Number

The maximum pyramid level this tile source supports or should attempt to load.
Type:
  • Number
Inherited From:
Source:

minLevel :Number

The minimum pyramid level this tile source supports or should attempt to load.
Type:
  • Number
Inherited From:
Source:

ready :Boolean

Type:
  • Boolean
Inherited From:
Source:

tileOverlap :Number

The overlap in pixels each tile shares with its adjacent neighbors.
Type:
  • Number
Inherited From:
Source:

Methods

addHandler(eventName, handler, userDataopt, priorityopt) → {Boolean}

Add an event handler for a given event.
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
handler OpenSeadragon.EventHandler | OpenSeadragon.AsyncEventHandler Function to call when event is triggered.
userData Object <optional>
 null Arbitrary object to be passed unchanged to the handler.
priority Number <optional>
 0 Handler priority. By default, all priorities are 0. Higher number = priority.
Inherited From:
Source:
Returns:
- True if the handler was added, false if it was rejected
Type
Boolean

addOnceHandler(eventName, handler, userDataopt, timesopt, priorityopt) → {Boolean}

Add an event handler to be triggered only once (or a given number of times) for a given event. It is not removable with removeHandler().
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
handler OpenSeadragon.EventHandler | OpenSeadragon.AsyncEventHandler Function to call when event is triggered.
userData Object <optional>
 null Arbitrary object to be passed unchanged to the handler.
times Number <optional>
 1 The number of times to handle the event before removing it.
priority Number <optional>
 0 Handler priority. By default, all priorities are 0. Higher number = priority.
Inherited From:
Source:
Returns:
- True if the handler was added, false if it was rejected
Type
Boolean

configure(data, url, postData) → {Object}

Parameters:
Name Type Description
data Object | XMLDocument the raw configuration
url String the url the data was retrieved from if any.
postData String HTTP POST data in k=v&k2=v2... form or null
Overrides:
Source:
Returns:
options - A dictionary of keyword arguments sufficient to configure this tile sources constructor.
Type
Object

createTileCache(cacheObject, data, tile)

Create cache object from the result of the download process. The cacheObject parameter should be used to attach the data to, there are no conventions on how it should be stored - all the logic is implemented within *TileCache() functions. Note that - data is cached automatically as cacheObject.data - if you override any of *TileCache() functions, you should override all of them. - these functions might be called over shared cache object managed by other TileSources simultaneously.
Parameters:
Name Type Description
cacheObject OpenSeadragon.CacheRecord context cache object
data * image data, the data sent to ImageJob.prototype.finish(), by default an Image object
tile OpenSeadragon.Tile instance the cache was created with
Inherited From:
Deprecated:
  • Yes
Source:

destroy(viewer)

Shall this source need to free some objects upon unloading, it must be done here. For example, canvas size must be set to 0 for safari to free.
Parameters:
Name Type Description
viewer OpenSeadragon.Viewer
Inherited From:
Source:

destroyTileCache(cacheObject)

Cache object destructor, unset all properties you created to allow GC collection. Note that if you override any of *TileCache() functions, you should override all of them. Note that these functions might be called over shared cache object managed by other TileSources simultaneously. Original cache data is cacheObject.data, but do not delete it manually! It is taken care for, you might break things.
Parameters:
Name Type Description
cacheObject OpenSeadragon.CacheRecord context cache object
Inherited From:
Deprecated:
  • Yes
Source:

downloadTileAbort(context)

Provide means of aborting the execution. Note that if you override this function, you should override also downloadTileStart(). Note that calling job.abort() would create an infinite loop!
Parameters:
Name Type Description
context ImageJob job, the same object as with downloadTileStart(..)
Properties
Name Type Attributes Description
userData * <optional>
 Empty object to attach (and mainly read) your own data.
Inherited From:
Source:

downloadTileStart(context)

Download tile data. Note that if you override this function, you should override also downloadTileAbort().
Parameters:
Name Type Description
context ImageJob job context that you have to call finish(...) on.
Properties
Name Type Attributes Description
src String <optional>
 URL of image to download.
loadWithAjax String <optional>
 Whether to load this image with AJAX.
ajaxHeaders String <optional>
 Headers to add to the image request if using AJAX.
ajaxWithCredentials Boolean <optional>
 Whether to set withCredentials on AJAX requests.
crossOriginPolicy String <optional>
 CORS policy to use for downloads
postData String | Object <optional>
 HTTP POST data (usually but not necessarily in k=v&k2=v2... form, see TileSource::getTilePostData) or null
userData * <optional>
 Empty object to attach your own data and helper variables to.
finish function <optional>
 Should be called unless abort() was executed upon successful data retrieval. Usage: context.finish(data, request, dataType=undefined). Pass the downloaded data object add also reference to an ajax request if used. Optionally, specify what data type the data is.
fail function <optional>
 Should be called unless abort() was executed upon unsuccessful request. Usage: context.fail(errMessage, request). Provide error message in case of failure, add also reference to an ajax request if used.
abort function <optional>
 Called automatically when the job times out. Usage: if you decide to abort the request (no fail/finish will be called), call context.abort().
callback function <optional>
 Private parameter. Called automatically once image has been downloaded (triggered by finish).
timeout Number <optional>
 Private parameter. The max number of milliseconds that this image job may take to complete.
errorMsg string <optional>
 Private parameter. The final error message, default null (set by finish).
Inherited From:
Source:

equals()

Equality comparator
Overrides:
Source:

getAwaitingHandler(eventName, bindTarget)

Get a function which iterates the list of all handlers registered for a given event, calling the handler for each and awaiting async ones.
Parameters:
Name Type Description
eventName String Name of event to get handlers for.
bindTarget any Bound target to return with the promise on finish
Inherited From:
Source:

getClosestLevel() → {Number}

Inherited From:
Source:
Returns:
The highest level in this tile source that can be contained in a single tile.
Type
Number

getHandler(eventName)

Get a function which iterates the list of all handlers registered for a given event, calling the handler for each.
Parameters:
Name Type Description
eventName String Name of event to get handlers for.
Inherited From:
Source:

getImageInfo(url)

Responsible for retrieving, and caching the image metadata pertinent to this TileSources implementation. There are three scenarios of opening a tile source: providing a parseable string, plain object, or an URL. This method is only called by OSD if the TileSource configuration is a non-parseable string (~url). The string can contain a hash `#` symbol, followed by key=value arguments. If this is the case, this method sends this data as a POST body.
Parameters:
Name Type Description
url String
Inherited From:
Source:
Throws:
Error

getLevelScale(level)

Parameters:
Name Type Description
level Number
Inherited From:
Source:

getNumTiles(level)

Parameters:
Name Type Description
level Number
Inherited From:
Source:

getPixelRatio(level)

Parameters:
Name Type Description
level Number
Inherited From:
Source:

getTileAjaxHeaders(level, x, y) → {Object}

Responsible for retrieving the headers which will be attached to the image request for the region specified by the given x, y, and level components. This option is only relevant if OpenSeadragon.Options.loadTilesWithAjax is set to true. The headers returned here will override headers specified at the Viewer or TiledImage level. Specifying a falsy value for a header will clear its existing value set at the Viewer or TiledImage level (if any). Note that the headers of existing tiles don't automatically change when this function returns updated headers. To do that, you need to call OpenSeadragon.Viewer#setAjaxHeaders and propagate the changes.
Parameters:
Name Type Description
level Number
x Number
y Number
Inherited From:
Source:
Returns:
Type
Object

getTileAtPoint(level, point)

Parameters:
Name Type Description
level Number
point OpenSeadragon.Point
Inherited From:
Source:

getTileBounds(level, x, y, isSourceopt) → {OpenSeadragon.Rect}

Parameters:
Name Type Attributes Default Description
level Number
x Number
y Number
isSource Boolean <optional>
 false Whether to return the source bounds of the tile.
Inherited From:
Source:
Returns:
Either where this tile fits (in normalized coordinates) or the portion of the tile to use as the source of the drawing operation (in pixels), depending on the isSource parameter.
Type
OpenSeadragon.Rect

getTileCacheData(cacheObject) → {OpenSeadragon.Promise.<?>}

Raw data getter, should return anything that is compatible with the system, or undefined if the system can handle it.
Parameters:
Name Type Description
cacheObject OpenSeadragon.CacheRecord context cache object
Inherited From:
Deprecated:
  • Yes
Source:
Returns:
cache data
Type
OpenSeadragon.Promise.<?>

getTileCacheDataAsContext2D(cacheObject) → {CanvasRenderingContext2D}

Compatibility context 2D getter - most heavily used rendering method is a canvas-based approach, convert the data to a canvas and return it's 2D context Note that if you override any of *TileCache() functions, you should override all of them.
Parameters:
Name Type Description
cacheObject OpenSeadragon.CacheRecord context cache object
Inherited From:
Deprecated:
  • Yes
Source:
Returns:
context of the canvas representation of the cache data
Type
CanvasRenderingContext2D

getTileCacheDataAsImage(cacheObject) → {Image}

Compatibility image element getter - plugins might need image representation of the data - div HTML rendering relies on image element presence Note that if you override any of *TileCache() functions, you should override all of them. Note that these functions might be called over shared cache object managed by other TileSources simultaneously.
Parameters:
Name Type Description
cacheObject OpenSeadragon.CacheRecord context cache object
Inherited From:
Deprecated:
  • Yes
Source:
Returns:
cache data as an Image
Type
Image

getTileHashKey(level, x, y, url, ajaxHeaders, postData) → (nullable) {String}

The tile cache object is uniquely determined by this key and used to lookup the image data in cache: keys should be different if images are different. You can return falsey tile cache key, in which case the tile will be created without invoking ImageJob --- but with data=null. Then, you are responsible for manually creating the cache data. This is useful particularly if you want to use empty TiledImage with client-side derived data only. The default tile-cache key is then called "" - an empty string. Note: default behaviour does not take into account post data.
Parameters:
Name Type Description
level Number tile level it was fetched with
x Number x-coordinate in the pyramid level
y Number y-coordinate in the pyramid level
url String the tile was fetched with
ajaxHeaders Object the tile was fetched with
postData * data the tile was fetched with (type depends on getTilePostData(..) return type)
Inherited From:
Source:
Returns:
can return the cache key or null, in that case an empty cache is initialized without downloading any data for internal use: user has to define the cache contents manually, via the cache interface of this class.
Type
String

getTileHeight(level)

Return the tileHeight for a given level. Subclasses should override this if tileHeight can be different at different levels such as in IIIFTileSource. Code should use this function rather than reading from ._tileHeight directly.
Parameters:
Name Type Description
level Number
Inherited From:
Source:

getTilePostData(level, x, y) → {*|null}

Must use AJAX in order to work, i.e. loadTilesWithAjax = true is set. If a value is returned, ajax issues POST request to the tile url. If null is returned, ajax issues GET request. The return value must comply to the header 'content type'. Examples (USED HEADER --> getTilePostData CODE): 'Content-type': 'application/x-www-form-urlencoded' --> return "key1=value=1&key2=value2"; 'Content-type': 'application/x-www-form-urlencoded' --> return JSON.stringify({key: "value", number: 5}); 'Content-type': 'multipart/form-data' --> let result = new FormData(); result.append("data", myData); return result; IMPORTANT: in case you move all the logic on image fetching to post data, you must re-define 'getTileHashKey(...)' to stay unique for different tile images.
Parameters:
Name Type Description
level Number
x Number
y Number
Inherited From:
Source:
Returns:
post data to send with tile configuration request
Type
* | null

getTileUrl(level, x, y)

Parameters:
Name Type Description
level Number
x Number
y Number
Overrides:
Source:

getTileWidth(level)

Return the tileWidth for a given level. Subclasses should override this if tileWidth can be different at different levels such as in IIIFTileSource. Code should use this function rather than reading from ._tileWidth directly.
Parameters:
Name Type Description
level Number
Inherited From:
Source:

hasTransparency(context2D, url, ajaxHeaders, post) → {boolean}

Decide whether tiles have transparency: this is crucial for correct images blending. Overriden on a tile level by setting tile.hasTransparency = true;
Parameters:
Name Type Description
context2D unused, deprecated argument
url tile.getUrl() value for given tile
ajaxHeaders tile.ajaxHeaders value for given tile
post tile.post value for given tile
Inherited From:
Source:
Returns:
true if the image has transparency
Type
boolean

numberOfHandlers(eventName) → {number}

Get the amount of handlers registered for a given event.
Parameters:
Name Type Description
eventName String Name of event to inspect.
Inherited From:
Source:
Returns:
amount of events
Type
number

raiseEvent(eventName, eventArgs) → {Boolean}

Trigger an event, optionally passing additional information. Does not await async handlers, i.e. OpenSeadragon.AsyncEventHandler.
Parameters:
Name Type Description
eventName String Name of event to register.
eventArgs Object Event-specific data.
Inherited From:
Source:
Returns:
True if the event was fired, false if it was rejected because of rejectEventHandler(eventName)
Type
Boolean

raiseEventAwaiting(eventName, eventArgs, bindTargetopt) → {OpenSeadragon.Promise|undefined}

Trigger an event, optionally passing additional information. This events awaits every asynchronous or promise-returning function, i.e. OpenSeadragon.AsyncEventHandler.
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
eventArgs Object Event-specific data.
bindTarget ? <optional>
 null Promise-resolved value on the event finish
Inherited From:
Source:
Returns:
- Promise resolved upon the event completion.
Type
OpenSeadragon.Promise | undefined

removeAllHandlers(eventName)

Remove all event handlers for a given event type. If no type is given all event handlers for every event type are removed.
Parameters:
Name Type Description
eventName String Name of event for which all handlers are to be removed.
Inherited From:
Source:

removeHandler(eventName, handler)

Remove a specific event handler for a given event.
Parameters:
Name Type Description
eventName String Name of event for which the handler is to be removed.
handler OpenSeadragon.EventHandler | OpenSeadragon.AsyncEventHandler Function to be removed.
Inherited From:
Source:

setMaxLevel(level)

Set the maxLevel to the given level, and perform the memoization of getLevelScale with the new maxLevel. This function can be useful if the memoization is required before the first call of getLevelScale, or both memoized getLevelScale and maxLevel should be changed accordingly.
Parameters:
Name Type Description
level Number
Inherited From:
Source:

supports(data, optional)

Determine if the data and/or url imply the image service is supported by this tile source.
Parameters:
Name Type Description
data Object | Array
optional String url
Overrides:
Source:

tileExists(level, x, y)

Parameters:
Name Type Description
level Number
x Number
y Number
Overrides:
Source: