Class: TiledImage

OpenSeadragon.TiledImage

Handles rendering of tiles for an OpenSeadragon.Viewer. A new instance is created for each TileSource opened.
Members Methods Events

Constructor

new TiledImage(options)

You shouldn't have to create a TiledImage instance directly; get it asynchronously by using OpenSeadragon.Viewer#open or OpenSeadragon.Viewer#addTiledImage instead.
Parameters:
Name Type Description
options Object Configuration for this TiledImage.
Properties
Name Type Attributes Default Description
source OpenSeadragon.TileSource The TileSource that defines this TiledImage.
viewer OpenSeadragon.Viewer The Viewer that owns this TiledImage.
tileCache OpenSeadragon.TileCache The TileCache for this TiledImage to use.
drawer OpenSeadragon.Drawer The Drawer for this TiledImage to draw onto.
imageLoader OpenSeadragon.ImageLoader The ImageLoader for this TiledImage to use.
x Number <optional>
 0 Left position, in viewport coordinates.
y Number <optional>
 0 Top position, in viewport coordinates.
width Number <optional>
 1 Width, in viewport coordinates.
height Number <optional>
 Height, in viewport coordinates.
fitBounds OpenSeadragon.Rect <optional>
 The bounds in viewport coordinates to fit the image into. If specified, x, y, width and height get ignored.
fitBoundsPlacement OpenSeadragon.Placement <optional>
 OpenSeadragon.Placement.CENTER How to anchor the image in the bounds if options.fitBounds is set.
clip OpenSeadragon.Rect <optional>
 An area, in image pixels, to clip to (portions of the image outside of this area will not be visible). Only works on browsers that support the HTML5 canvas.
springStiffness Number <optional>
 See OpenSeadragon.Options.
animationTime Boolean <optional>
 See OpenSeadragon.Options.
minZoomImageRatio Number <optional>
 See OpenSeadragon.Options.
wrapHorizontal Boolean <optional>
 See OpenSeadragon.Options.
wrapVertical Boolean <optional>
 See OpenSeadragon.Options.
immediateRender Boolean <optional>
 See OpenSeadragon.Options.
blendTime Number <optional>
 See OpenSeadragon.Options.
alwaysBlend Boolean <optional>
 See OpenSeadragon.Options.
minPixelRatio Number <optional>
 See OpenSeadragon.Options.
smoothTileEdgesMinZoom Number <optional>
 See OpenSeadragon.Options.
iOSDevice Boolean <optional>
 See OpenSeadragon.Options.
opacity Number <optional>
 1 Set to draw at proportional opacity. If zero, images will not draw.
preload Boolean <optional>
 false Set true to load even when the image is hidden by zero opacity.
compositeOperation String <optional>
 How the image is composited onto other images; see compositeOperation in OpenSeadragon.Options for possible values.
debugMode Boolean <optional>
 See OpenSeadragon.Options.
placeholderFillStyle String | CanvasGradient | CanvasPattern | function <optional>
 See OpenSeadragon.Options.
crossOriginPolicy String | Boolean <optional>
 See OpenSeadragon.Options.
ajaxWithCredentials Boolean <optional>
 See OpenSeadragon.Options.
loadTilesWithAjax Boolean <optional>
 Whether to load tile data using AJAX requests. Defaults to the setting in OpenSeadragon.Options.
ajaxHeaders Object <optional>
 {} A set of headers to include when making tile AJAX requests.
Source:

Extends

Members

source :OpenSeadragon.TileSource

The OpenSeadragon.TileSource that defines this TiledImage.
Type:
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:

destroy()

Destroy the TiledImage (unload current loaded tiles).
Source:

draw()

Draws the TiledImage to its Drawer.
Source:

fitBounds(bounds, anchoropt, immediatelyopt)

Positions and scales the TiledImage to fit in the specified bounds. Note: this method fires OpenSeadragon.TiledImage.event:bounds-change twice
Parameters:
Name Type Attributes Default Description
bounds OpenSeadragon.Rect The bounds to fit the image into.
anchor OpenSeadragon.Placement <optional>
 OpenSeadragon.Placement.CENTER How to anchor the image in the bounds.
immediately Boolean <optional>
 false Whether to animate to the new size or snap immediately.
Source:
Fires:

getBounds(currentopt) → {OpenSeadragon.Rect}

Get this TiledImage's bounds in viewport coordinates.
Parameters:
Name Type Attributes Default Description
current Boolean <optional>
 false Pass true for the current location; false for target location.
Source:
Returns:
This TiledImage's bounds in viewport coordinates.
Type
OpenSeadragon.Rect

getBoundsNoRotate(currentopt) → {OpenSeadragon.Rect}

Get this TiledImage's bounds in viewport coordinates without taking rotation into account.
Parameters:
Name Type Attributes Default Description
current Boolean <optional>
 false Pass true for the current location; false for target location.
Source:
Returns:
This TiledImage's bounds in viewport coordinates.
Type
OpenSeadragon.Rect

getClip() → {OpenSeadragon.Rect|null}

Source:
Returns:
The TiledImage's current clip rectangle, in image pixels, or null if none.
Type
OpenSeadragon.Rect | null

getClippedBounds(currentopt) → {$.Rect}

Get the bounds of the displayed part of the tiled image.
Parameters:
Name Type Attributes Default Description
current Boolean <optional>
 false Pass true for the current location, false for the target location.
Source:
Returns:
The clipped bounds in viewport coordinates.
Type
$.Rect

getCompositeOperation() → {String}

Source:
Returns:
The TiledImage's current compositeOperation.
Type
String

getContentSize() → {OpenSeadragon.Point}

Source:
Returns:
This TiledImage's content size, in original pixels.
Type
OpenSeadragon.Point

getFlip() → {Boolean}

Source:
Returns:
Whether the TiledImage should be flipped before rendering.
Type
Boolean

getFullyLoaded() → {Boolean}

Source:
Returns:
Whether all tiles necessary for this TiledImage to draw at the current view have been loaded.
Type
Boolean

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:

getOpacity() → {Number}

Source:
Returns:
The TiledImage's current opacity.
Type
Number

getPreload() → {Boolean}

Source:
Returns:
whether the tiledImage can load its tiles even when it has zero opacity.
Type
Boolean

getRotation(currentopt) → {Number}

Get the rotation of this tiled image in degrees.
Parameters:
Name Type Attributes Default Description
current Boolean <optional>
 false True for current rotation, false for target.
Source:
Returns:
the rotation of this tiled image in degrees.
Type
Number

getSizeInWindowCoordinates() → {OpenSeadragon.Point}

Source:
Returns:
The TiledImage's content size, in window coordinates.
Type
OpenSeadragon.Point

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

Parameters:
Name Type Description
level Number
x Number
y Number
Source:
Returns:
Where this tile fits (in normalized coordinates).
Type
OpenSeadragon.Rect

imageToViewerElementCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the image to viewer element coordinates.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

imageToViewportCoordinates(imageX, imageYopt, currentopt) → {OpenSeadragon.Point}

Translates from image coordinate system to OpenSeadragon viewer coordinate system This method can be called either by passing X,Y coordinates or an OpenSeadragon.Point.
Parameters:
Name Type Attributes Default Description
imageX Number | OpenSeadragon.Point The X coordinate or point in image coordinate system.
imageY Number <optional>
 The Y coordinate in image coordinate system.
current Boolean <optional>
 false Pass true to use the current location; false for target location.
Source:
Returns:
A point representing the coordinates in the viewport.
Type
OpenSeadragon.Point

imageToViewportRectangle(imageX, imageYopt, pixelWidthopt, pixelHeightopt, currentopt) → {OpenSeadragon.Rect}

Translates from a rectangle which describes a portion of the image in pixel coordinates to OpenSeadragon viewport rectangle coordinates. This method can be called either by passing X,Y,width,height or an OpenSeadragon.Rect.
Parameters:
Name Type Attributes Default Description
imageX Number | OpenSeadragon.Rect The left coordinate or rectangle in image coordinate system.
imageY Number <optional>
 The top coordinate in image coordinate system.
pixelWidth Number <optional>
 The width in pixel of the rectangle.
pixelHeight Number <optional>
 The height in pixel of the rectangle.
current Boolean <optional>
 false Pass true to use the current location; false for target location.
Source:
Returns:
A rect representing the coordinates in the viewport.
Type
OpenSeadragon.Rect

imageToViewportZoom(imageZoom) → {Number}

Convert an image zoom to a viewport zoom. Image zoom: ratio of the original image size to displayed image size. 1 means original image size, 0.5 half size... Viewport zoom: ratio of the displayed image's width to viewport's width. 1 means identical width, 2 means image's width is twice the viewport's width... Note: not accurate with multi-image.
Parameters:
Name Type Description
imageZoom Number The image zoom
Source:
Returns:
viewportZoom The viewport zoom
Type
Number

imageToWindowCoordinates(pixel) → {OpenSeadragon.Point}

Convert image coordinates to pixel coordinates relative to the window.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

needsDraw() → {Boolean}

Source:
Returns:
Whether the TiledImage needs to be drawn.
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:

reset()

Clears all tiles and triggers an update on the next call to OpenSeadragon.TiledImage#update.
Source:

resetCroppingPolygons()

Resets the cropping polygons, thus next render will remove all cropping polygon effects.
Source:

setAjaxHeaders(ajaxHeaders, propagateopt)

Update headers to include when making AJAX requests. Unless `propagate` is set to false (which is likely only useful in rare circumstances), the updated headers are propagated to all tiles and queued image loader jobs. Note that the rules for merging headers still apply, i.e. headers returned by OpenSeadragon.TileSource#getTileAjaxHeaders take precedence over the headers here in the tiled image (`TiledImage.ajaxHeaders`).
Parameters:
Name Type Attributes Default Description
ajaxHeaders Object Updated AJAX headers, which will be merged over any headers specified in OpenSeadragon.Options.
propagate Boolean <optional>
 true Whether to propagate updated headers to existing tiles and queued image loader jobs.
Source:

setClip(newClip)

Parameters:
Name Type Description
newClip OpenSeadragon.Rect | null An area, in image pixels, to clip to (portions of the image outside of this area will not be visible). Only works on browsers that support the HTML5 canvas.
Source:
Fires:

setCompositeOperation(compositeOperation)

Parameters:
Name Type Description
compositeOperation String the tiled image should be drawn with this globalCompositeOperation.
Source:
Fires:

setCroppingPolygons(polygons)

Sets an array of polygons to crop the TiledImage during draw tiles. The render function will use the default non-zero winding rule.
Parameters:
Name Type Description
polygons Array.<Array.<OpenSeadragon.Point>> represented in an array of point object in image coordinates. Example format: [ [{x: 197, y:172}, {x: 226, y:172}, {x: 226, y:198}, {x: 197, y:198}], // First polygon [{x: 328, y:200}, {x: 330, y:199}, {x: 332, y:201}, {x: 329, y:202}] // Second polygon [{x: 321, y:201}, {x: 356, y:205}, {x: 341, y:250}] // Third polygon ]
Source:

setFlip(flip)

Parameters:
Name Type Description
flip Boolean Whether the TiledImage should be flipped before rendering.
Source:
Fires:

setHeight(height, immediatelyopt)

Sets the TiledImage's height in the world, adjusting the width to match based on aspect ratio.
Parameters:
Name Type Attributes Default Description
height Number The new height, in viewport coordinates.
immediately Boolean <optional>
 false Whether to animate to the new size or snap immediately.
Source:
Fires:

setOpacity(opacity)

Parameters:
Name Type Description
opacity Number Opacity the tiled image should be drawn at.
Source:
Fires:

setPosition(position, immediatelyopt)

Sets the TiledImage's position in the world.
Parameters:
Name Type Attributes Default Description
position OpenSeadragon.Point The new position, in viewport coordinates.
immediately Boolean <optional>
 false Whether to animate to the new position or snap immediately.
Source:
Fires:

setPreload()

Set true to load even when hidden. Set false to block loading when hidden.
Source:

setRotation(degrees, immediatelyopt)

Set the current rotation of this tiled image in degrees.
Parameters:
Name Type Attributes Default Description
degrees Number the rotation in degrees.
immediately Boolean <optional>
 false Whether to animate to the new angle or rotate immediately.
Source:
Fires:

setWidth(width, immediatelyopt)

Sets the TiledImage's width in the world, adjusting the height to match based on aspect ratio.
Parameters:
Name Type Attributes Default Description
width Number The new width, in viewport coordinates.
immediately Boolean <optional>
 false Whether to animate to the new size or snap immediately.
Source:
Fires:

update() → {Boolean}

Updates the TiledImage's bounds, animating if needed.
Source:
Returns:
Whether the TiledImage animated.
Type
Boolean

viewerElementToImageCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the viewer element to image coordinates.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

viewportToImageCoordinates(viewerX, viewerYopt, currentopt) → {OpenSeadragon.Point}

Translates from OpenSeadragon viewer coordinate system to image coordinate system. This method can be called either by passing X,Y coordinates or an OpenSeadragon.Point.
Parameters:
Name Type Attributes Default Description
viewerX Number | OpenSeadragon.Point The X coordinate or point in viewport coordinate system.
viewerY Number <optional>
 The Y coordinate in viewport coordinate system.
current Boolean <optional>
 false Pass true to use the current location; false for target location.
Source:
Returns:
A point representing the coordinates in the image.
Type
OpenSeadragon.Point

viewportToImageRectangle(viewerX, viewerYopt, pointWidthopt, pointHeightopt, currentopt) → {OpenSeadragon.Rect}

Translates from a rectangle which describes a portion of the viewport in point coordinates to image rectangle coordinates. This method can be called either by passing X,Y,width,height or an OpenSeadragon.Rect.
Parameters:
Name Type Attributes Default Description
viewerX Number | OpenSeadragon.Rect The left coordinate or rectangle in viewport coordinate system.
viewerY Number <optional>
 The top coordinate in viewport coordinate system.
pointWidth Number <optional>
 The width in viewport coordinate system.
pointHeight Number <optional>
 The height in viewport coordinate system.
current Boolean <optional>
 false Pass true to use the current location; false for target location.
Source:
Returns:
A rect representing the coordinates in the image.
Type
OpenSeadragon.Rect

viewportToImageZoom(viewportZoom) → {Number}

Convert a viewport zoom to an image zoom. Image zoom: ratio of the original image size to displayed image size. 1 means original image size, 0.5 half size... Viewport zoom: ratio of the displayed image's width to viewport's width. 1 means identical width, 2 means image's width is twice the viewport's width...
Parameters:
Name Type Description
viewportZoom Number The viewport zoom
Source:
Returns:
imageZoom The image zoom
Type
Number

windowToImageCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the window to image coordinates.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

Events

bounds-change

Raised when the TiledImage's bounds are changed. Note that this event is triggered only when the animation target is changed; not for every frame of animation.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.TiledImage A reference to the TiledImage which raised the event.
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source:

clip-change

Raised when the TiledImage's clip is changed.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.TiledImage A reference to the TiledImage which raised the event.
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source:

composite-operation-change

Raised when the TiledImage's opacity is changed.
Type:
  • object
Properties:
Name Type Attributes Description
compositeOperation String The new compositeOperation value.
eventSource OpenSeadragon.TiledImage A reference to the TiledImage which raised the event.
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source:

fully-loaded-change

Fired when the TiledImage's "fully loaded" flag (whether all tiles necessary for this TiledImage to draw at the current view have been loaded) changes.
Type:
  • object
Properties:
Name Type Attributes Description
fullyLoaded Boolean The new "fully loaded" value.
eventSource OpenSeadragon.TiledImage A reference to the TiledImage which raised the event.
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source:

opacity-change

Raised when the TiledImage's opacity is changed.
Type:
  • object
Properties:
Name Type Attributes Description
opacity Number The new opacity value.
eventSource OpenSeadragon.TiledImage A reference to the TiledImage which raised the event.
userData Object <nullable>
 Arbitrary subscriber-defined object.
Source: