Class: TileSource

OpenSeadragon.TileSource

The TileSource contains the most basic implementation required to create a smooth transition between layers in an image pyramid. It has only a single key interface that must be implemented to complete its key functionality: 'getTileUrl'. It also has several optional interfaces that can be implemented if a new TileSource wishes to support configuration via a simple object or array ('configure') and if the tile source supports or requires configuration via retrieval of a document on the network ala AJAX or JSONP, ('getImageInfo').
By default the image pyramid is split into N layers where the image's longest side in M (in pixels), where N is the smallest integer which satisfies 2^(N+1) >= M.
Members Methods Events

Constructor

new TileSource(options)

Parameters:
Name Type Description
options Object You can either specify a URL, or literally define the TileSource (by specifying width, height, tileSize, tileOverlap, minLevel, and maxLevel). For the former, the extending class is expected to implement 'getImageInfo' and 'configure'. For the latter, the construction is assumed to occur through the extending classes implementation of 'configure'.
Properties
Name Type Attributes Description
url String <optional>
 The URL for the data necessary for this TileSource.
referenceStripThumbnailUrl String <optional>
 The URL for a thumbnail image to be used by the reference strip
success function <optional>
 A function to be called upon successful creation.
ajaxWithCredentials Boolean <optional>
 If this TileSource needs to make an AJAX call, this specifies whether to set the XHR's withCredentials (for accessing secure data).
ajaxHeaders Object <optional>
 A set of headers to include in AJAX requests.
splitHashDataForPost Boolean <optional>
 First occurrence of '#' in the options.url is used to split URL and the latter part is treated as POST data (applies to getImageInfo(...))
width Number <optional>
 Width of the source image at max resolution in pixels.
height Number <optional>
 Height of the source image at max resolution in pixels.
tileSize Number <optional>
 The size of the tiles to assumed to make up each pyramid layer in pixels. Tile size determines the point at which the image pyramid must be divided into a matrix of smaller images. Use options.tileWidth and options.tileHeight to support non-square tiles.
tileWidth Number <optional>
 The width of the tiles to assumed to make up each pyramid layer in pixels.
tileHeight Number <optional>
 The height of the tiles to assumed to make up each pyramid layer in pixels.
tileOverlap Number <optional>
 The number of pixels each tile is expected to overlap touching tiles.
minLevel Number <optional>
 The minimum level to attempt to load.
maxLevel Number <optional>
 The maximum level to attempt to load.
Source:

Extends

Members

aspectRatio :Number

Ratio of width to height
Type:
  • Number
Source:

dimensions :OpenSeadragon.Point

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

maxLevel :Number

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

minLevel :Number

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

ready :Boolean

Type:
  • Boolean
Source:

tileOverlap :Number

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

Methods

addHandler(eventName, handler, userDataopt, priorityopt)

Add an event handler for a given event.
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
handler OpenSeadragon.EventHandler 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:

addOnceHandler(eventName, handler, userDataopt, timesopt, priorityopt)

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 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:

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

Responsible for parsing and configuring the image metadata pertinent to this TileSources implementation. This method is not implemented by this class other than to throw an Error announcing you have to implement it. Because of the variety of tile server technologies, and various specifications for building image pyramids, this method is here to allow easy integration.
Parameters:
Name Type Description
data String | Object | Array | Document
url String the url the data was loaded from if any.
postData String HTTP POST data in k=v&k2=v2... form or null value obtained from the protocol URL after '#' sign if flag splitHashDataForPost set to 'true'
Source:
Throws:
Error
Returns:
options - A dictionary of keyword arguments sufficient to configure the tile source constructor (include all values you want to instantiate the TileSource subclass with - what _options_ object should contain).
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 if you override any of *TileCache() functions, you should override all of them.
Parameters:
Name Type Description
cacheObject object context cache object
data * image data, the data sent to ImageJob.prototype.finish(), by default an Image object
tile Tile instance the cache was created with
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.
Parameters:
Name Type Description
cacheObject object context cache object
Source:

downloadTileAbort(context)

Provide means of aborting the execution. Note that if you override this function, you should override also downloadTileStart().
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.
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 <optional>
 HTTP POST data (usually but not necessarily in k=v&k2=v2... form, see TileSource::getPostData) 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, e.g. on all occasions, be it successful or unsuccessful request. Usage: context.finish(data, request, errMessage). Pass the downloaded data object or null upon failure. Add also reference to an ajax request if used. Provide error message in case of failure.
abort function <optional>
 Called automatically when the job times out. Usage: context.abort().
callback function <optional>
 @private - Called automatically once image has been downloaded (triggered by finish).
timeout Number <optional>
 @private - The max number of milliseconds that this image job may take to complete.
errorMsg string <optional>
 @private - The final error message, default null (set by finish).
Source:

getClosestLevel() → {Number}

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.
Parameters:
Name Type Description
url String
Source:
Throws:
Error

getLevelScale(level)

Parameters:
Name Type Description
level Number
Source:

getNumTiles(level)

Parameters:
Name Type Description
level Number
Source:

getPixelRatio(level)

Parameters:
Name Type Description
level Number
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
Source:
Returns:
Type
Object

getTileAtPoint(level, point)

Parameters:
Name Type Description
level Number
point OpenSeadragon.Point
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.
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) → {*}

Raw data getter Note that if you override any of *TileCache() functions, you should override all of them.
Parameters:
Name Type Description
cacheObject object context cache object
Source:
Returns:
cache data
Type
*

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 object context cache object
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.
Parameters:
Name Type Description
cacheObject object context cache object
Source:
Returns:
cache data as an Image
Type
Image

getTileHashKey(level, x, y, url, ajaxHeaders, postData)

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. In case a tile has context2D property defined (TileSource.prototype.getContext2D) or its context2D is set manually; the cache is not used and this function is irrelevant. 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)
Source:

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
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
Source:
Returns:
post data to send with tile configuration request
Type
* | null

getTileUrl(level, x, y) → {String|function}

Responsible for retrieving the url which will return an image for the region specified by the given x, y, and level components. This method is not implemented by this class other than to throw an Error announcing you have to implement it. Because of the variety of tile server technologies, and various specifications for building image pyramids, this method is here to allow easy integration.
Parameters:
Name Type Description
level Number
x Number
y Number
Source:
Throws:
Error
Returns:
url - A string for the url or a function that returns a url string.
Type
String | function

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
Source:

hasTransparency() → {boolean}

Decide whether tiles have transparency: this is crucial for correct images blending.
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)

Trigger an event, optionally passing additional information.
Parameters:
Name Type Description
eventName String Name of event to register.
eventArgs Object Event-specific data.
Inherited From:
Source:

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 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
Source:

supports(data, url) → {Boolean}

Responsible determining if a the particular TileSource supports the data format ( and allowed to apply logic against the url the data was loaded from, if any ). Overriding implementations are expected to do something smart with data and / or url to determine support. Also understand that iteration order of TileSources is not guarunteed so please make sure your data or url is expressive enough to ensure a simple and sufficient mechanisim for clear determination.
Parameters:
Name Type Description
data String | Object | Array | Document
url String the url the data was loaded from if any.
Source:
Returns:
Type
Boolean

tileExists(level, x, y)

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

Events

open-failed

Raised when an error occurs loading a TileSource.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.TileSource A reference to the TileSource which raised the event.
message String
source String
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source:

ready

Raised when a TileSource is opened and initialized.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.TileSource A reference to the TileSource which raised the event.
tileSource Object
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source: