Class: Viewport

OpenSeadragon.Viewport

Handles coordinate-related functionality (zoom, pan, rotation, etc.) for an OpenSeadragon.Viewer.
Methods

Constructor

new Viewport(options)

Parameters:
Name Type Description
options Object Options for this Viewport.
Properties
Name Type Attributes Description
margins Object <optional>
 See viewportMargins in OpenSeadragon.Options.
springStiffness Number <optional>
 See springStiffness in OpenSeadragon.Options.
animationTime Number <optional>
 See animationTime in OpenSeadragon.Options.
minZoomImageRatio Number <optional>
 See minZoomImageRatio in OpenSeadragon.Options.
maxZoomPixelRatio Number <optional>
 See maxZoomPixelRatio in OpenSeadragon.Options.
visibilityRatio Number <optional>
 See visibilityRatio in OpenSeadragon.Options.
wrapHorizontal Boolean <optional>
 See wrapHorizontal in OpenSeadragon.Options.
wrapVertical Boolean <optional>
 See wrapVertical in OpenSeadragon.Options.
defaultZoomLevel Number <optional>
 See defaultZoomLevel in OpenSeadragon.Options.
minZoomLevel Number <optional>
 See minZoomLevel in OpenSeadragon.Options.
maxZoomLevel Number <optional>
 See maxZoomLevel in OpenSeadragon.Options.
degrees Number <optional>
 See degrees in OpenSeadragon.Options.
homeFillsViewer Boolean <optional>
 See homeFillsViewer in OpenSeadragon.Options.
silenceMultiImageWarnings Boolean <optional>
 See silenceMultiImageWarnings in OpenSeadragon.Options.
Source:

Methods

applyConstraints(immediatelyopt) → {OpenSeadragon.Viewport}

Enforces the minZoom, maxZoom and visibilityRatio constraints by zooming and panning to the closest acceptable zoom and location.
Parameters:
Name Type Attributes Default Description
immediately Boolean <optional>
 false
Source:
Fires:
  • OpenSeadragon.Viewer.event:constrain if constraints were applied
Returns:
Chainable.
Type
OpenSeadragon.Viewport

deltaPixelsFromPoints(deltaPoints, currentopt) → {OpenSeadragon.Point}

Convert a delta (translation vector) from viewport coordinates to pixels coordinates.
Parameters:
Name Type Attributes Default Description
deltaPoints OpenSeadragon.Point The translation vector to convert.
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

deltaPixelsFromPointsNoRotate(deltaPoints, currentopt) → {OpenSeadragon.Point}

Convert a delta (translation vector) from viewport coordinates to pixels coordinates. This method does not take rotation into account. Consider using deltaPixelsFromPoints if you need to account for rotation.
Parameters:
Name Type Attributes Default Description
deltaPoints OpenSeadragon.Point The translation vector to convert.
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

deltaPointsFromPixels(deltaPixels, currentopt) → {OpenSeadragon.Point}

Convert a delta (translation vector) from pixels coordinates to viewport coordinates.
Parameters:
Name Type Attributes Default Description
deltaPixels OpenSeadragon.Point The translation vector to convert.
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

deltaPointsFromPixelsNoRotate(deltaPixels, currentopt) → {OpenSeadragon.Point}

Convert a delta (translation vector) from pixels coordinates to viewport coordinates. This method does not take rotation into account. Consider using deltaPointsFromPixels if you need to account for rotation.
Parameters:
Name Type Attributes Default Description
deltaPixels OpenSeadragon.Point The translation vector to convert.
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

ensureVisible(immediatelyopt) → {OpenSeadragon.Viewport}

Equivalent to OpenSeadragon.Viewport#applyConstraints
Parameters:
Name Type Attributes Default Description
immediately Boolean <optional>
 false
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

fitBounds(bounds, immediatelyopt) → {OpenSeadragon.Viewport}

Makes the viewport zoom and pan so that the specified bounds take as much space as possible in the viewport. Note: this method ignores the constraints (minZoom, maxZoom and visibilityRatio). Use OpenSeadragon.Viewport#fitBoundsWithConstraints to enforce them.
Parameters:
Name Type Attributes Default Description
bounds OpenSeadragon.Rect
immediately Boolean <optional>
 false
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

fitBoundsWithConstraints(bounds, immediatelyopt) → {OpenSeadragon.Viewport}

Makes the viewport zoom and pan so that the specified bounds take as much space as possible in the viewport while enforcing the constraints (minZoom, maxZoom and visibilityRatio). Note: because this method enforces the constraints, part of the provided bounds may end up outside of the viewport. Use OpenSeadragon.Viewport#fitBounds to ignore them.
Parameters:
Name Type Attributes Default Description
bounds OpenSeadragon.Rect
immediately Boolean <optional>
 false
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

fitHorizontally(immediately) → {OpenSeadragon.Viewport}

Zooms so the image just fills the viewer horizontally.
Parameters:
Name Type Description
immediately Boolean
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

fitVertically(immediately) → {OpenSeadragon.Viewport}

Zooms so the image just fills the viewer vertically.
Parameters:
Name Type Description
immediately Boolean
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

getAspectRatio()

Source:

getBounds(current) → {OpenSeadragon.Rect}

Returns the bounds of the visible area in viewport coordinates.
Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:
Returns:
The location you are zoomed/panned to, in viewport coordinates.
Type
OpenSeadragon.Rect

getBoundsNoRotate(current) → {OpenSeadragon.Rect}

Returns the bounds of the visible area in viewport coordinates. This method ignores the viewport rotation. Use OpenSeadragon.Viewport#getBounds to take it into account.
Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:
Returns:
The location you are zoomed/panned to, in viewport coordinates.
Type
OpenSeadragon.Rect

getBoundsNoRotateWithMargins(current) → {OpenSeadragon.Rect}

Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:
Returns:
The location you are zoomed/panned to, including the space taken by margins, in viewport coordinates.
Type
OpenSeadragon.Rect

getBoundsWithMargins(current) → {OpenSeadragon.Rect}

Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:
Returns:
The location you are zoomed/panned to, including the space taken by margins, in viewport coordinates.
Type
OpenSeadragon.Rect

getCenter(current)

Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:

getConstrainedBounds(current) → {OpenSeadragon.Rect}

Returns bounds taking constraints into account Added to improve constrained panning
Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:
Returns:
The bounds in viewport coordinates after applying constraints. The returned $.Rect contains additional properties constraintsApplied, xConstrained and yConstrained. These flags indicate whether the viewport bounds were modified by the constraints of the viewer rectangle, and in which dimension(s).
Type
OpenSeadragon.Rect

getContainerSize() → {OpenSeadragon.Point}

Source:
Returns:
The size of the container, in screen coordinates.
Type
OpenSeadragon.Point

getFlip() → {Boolean}

Get flip state stored on viewport.
Source:
Returns:
Flip state.
Type
Boolean

getHomeBounds() → {OpenSeadragon.Rect}

Returns the home bounds in viewport coordinates.
Source:
Returns:
The home bounds in vewport coordinates.
Type
OpenSeadragon.Rect

getHomeBoundsNoRotate() → {OpenSeadragon.Rect}

Returns the home bounds in viewport coordinates. This method ignores the viewport rotation. Use OpenSeadragon.Viewport#getHomeBounds to take it into account.
Source:
Returns:
The home bounds in vewport coordinates.
Type
OpenSeadragon.Rect

getHomeZoom() → {Number}

Returns the home zoom in "viewport zoom" value.
Source:
Returns:
The home zoom in "viewport zoom".
Type
Number

getMargins() → {Object}

The margins push the "home" region in from the sides by the specified amounts.
Source:
Returns:
Properties (Numbers, in screen coordinates): left, top, right, bottom.
Type
Object

getMaxZoom()

Source:

getMaxZoomPixelRatio() → {Number}

Gets current max zoom pixel ratio
Source:
Returns:
Max zoom pixel ratio
Type
Number

getMinZoom()

Source:

getRotation(currentopt) → {Number}

Gets the current rotation in degrees.
Parameters:
Name Type Attributes Default Description
current Boolean <optional>
 false True for current rotation, false for target.
Source:
Returns:
The current rotation in degrees.
Type
Number

getZoom(current)

Parameters:
Name Type Description
current Boolean Pass true for the current location; defaults to false (target location).
Source:

goHome(immediately)

Parameters:
Name Type Description
immediately Boolean
Source:
Fires:

imageToViewerElementCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the image to viewer element coordinates. Note: not accurate with multi-image.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

imageToViewportCoordinates(imageX, imageYopt) → {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 Note: not accurate with multi-image; use TiledImage.imageToViewportCoordinates instead.
Parameters:
Name Type Attributes Description
imageX OpenSeadragon.Point | Number the point or the X coordinate in image coordinate system.
imageY Number <optional>
 Y coordinate in image coordinate system.
Source:
Returns:
a point representing the coordinates in the viewport.
Type
OpenSeadragon.Point

imageToViewportRectangle(imageX, imageYopt, pixelWidthopt, pixelHeightopt) → {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 Note: not accurate with multi-image; use TiledImage.imageToViewportRectangle instead.
Parameters:
Name Type Attributes Description
imageX OpenSeadragon.Rect | Number the rectangle or the X coordinate of the top left corner of the rectangle in image coordinate system.
imageY Number <optional>
 the Y coordinate of the top left corner of the rectangle in image coordinate system.
pixelWidth Number <optional>
 the width in pixel of the rectangle.
pixelHeight Number <optional>
 the height in pixel of the rectangle.
Source:
Returns:
This image's bounds in viewport coordinates
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; use [TiledImage.imageToViewportZoom] for the specific image of interest.
Parameters:
Name Type Description
imageZoom Number The image zoom target zoom.
Source:
Returns:
viewportZoom The viewport zoom
Type
Number

imageToWindowCoordinates(pixel) → {OpenSeadragon.Point}

Convert image coordinates to pixel coordinates relative to the window. Note: not accurate with multi-image.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

panBy(delta, immediately) → {OpenSeadragon.Viewport}

Parameters:
Name Type Description
delta OpenSeadragon.Point
immediately Boolean
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

panTo(center, immediately) → {OpenSeadragon.Viewport}

Parameters:
Name Type Description
center OpenSeadragon.Point
immediately Boolean
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

pixelFromPoint(point, currentopt) → {OpenSeadragon.Point}

Convert viewport coordinates to pixel coordinates.
Parameters:
Name Type Attributes Default Description
point OpenSeadragon.Point the viewport coordinates
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

pixelFromPointNoRotate(point, currentopt) → {OpenSeadragon.Point}

Convert viewport coordinates to pixels coordinates. This method does not take rotation into account. Consider using pixelFromPoint if you need to account for rotation.
Parameters:
Name Type Attributes Default Description
point OpenSeadragon.Point the viewport coordinates
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

pointFromPixel(pixel, currentopt) → {OpenSeadragon.Point}

Convert pixel coordinates to viewport coordinates.
Parameters:
Name Type Attributes Default Description
pixel OpenSeadragon.Point Pixel coordinates
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

pointFromPixelNoRotate(pixel, currentopt) → {OpenSeadragon.Point}

Convert pixel coordinates to viewport coordinates. This method does not take rotation into account. Consider using pointFromPixel if you need to account for rotation.
Parameters:
Name Type Attributes Default Description
pixel OpenSeadragon.Point Pixel coordinates
current Boolean <optional>
 false Pass true for the current location; defaults to false (target location).
Source:
Returns:
Type
OpenSeadragon.Point

resetContentSize(contentSize) → {OpenSeadragon.Viewport}

Updates the viewport's home bounds and constraints for the given content size.
Parameters:
Name Type Description
contentSize OpenSeadragon.Point size of the content in content units
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

resize() → {OpenSeadragon.Viewport}

Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

rotateBy(degrees, pivotopt) → {OpenSeadragon.Viewport}

Rotates this viewport by the angle specified.
Parameters:
Name Type Attributes Description
degrees Number The degrees by which to rotate the viewport.
pivot OpenSeadragon.Point <optional>
 (Optional) point in viewport coordinates around which the rotation should be performed. Defaults to the center of the viewport. * @param {Boolean} [immediately=false] Whether to animate to the new angle or rotate immediately.
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

rotateTo(degrees, pivotopt, immediatelyopt) → {OpenSeadragon.Viewport}

Rotates this viewport to the angle specified.
Parameters:
Name Type Attributes Default Description
degrees Number The degrees to set the rotation to.
pivot OpenSeadragon.Point <optional>
 (Optional) point in viewport coordinates around which the rotation should be performed. Defaults to the center of the viewport.
immediately Boolean <optional>
 false Whether to animate to the new angle or rotate immediately.
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

setFlip(state) → {OpenSeadragon.Viewport}

Sets flip state according to the state input argument.
Parameters:
Name Type Description
state Boolean Flip state to set.
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

setMargins(margins)

The margins push the "home" region in from the sides by the specified amounts.
Parameters:
Name Type Description
margins Object Properties (Numbers, in screen coordinates): left, top, right, bottom.
Source:

setMaxZoomPixelRatio(ratio, applyConstraintsopt, immediatelyopt)

Sets max zoom pixel ratio
Parameters:
Name Type Attributes Default Description
ratio Number Max zoom pixel ratio
applyConstraints Boolean <optional>
 true Apply constraints after setting ratio; Takes effect only if current zoom is greater than set max zoom pixel ratio
immediately Boolean <optional>
 false Whether to animate to new zoom
Source:

setRotation(degrees, immediatelyopt)

Rotates this viewport to the angle specified.
Parameters:
Name Type Attributes Default Description
degrees Number The degrees to set the rotation to.
immediately Boolean <optional>
 false Whether to animate to the new angle or rotate immediately. * @returns {OpenSeadragon.Viewport} Chainable.
Source:

setRotationWithPivot(degrees, pivotopt, immediatelyopt)

Rotates this viewport to the angle specified around a pivot point. Alias for rotateTo.
Parameters:
Name Type Attributes Default Description
degrees Number The degrees to set the rotation to.
pivot OpenSeadragon.Point <optional>
 (Optional) point in viewport coordinates around which the rotation should be performed. Defaults to the center of the viewport.
immediately Boolean <optional>
 false Whether to animate to the new angle or rotate immediately. * @returns {OpenSeadragon.Viewport} Chainable.
Source:

toggleFlip() → {OpenSeadragon.Viewport}

Toggles flip state and demands a new drawing on navigator and viewer objects.
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

update() → {Boolean}

Update the zoom, degrees, and center (X and Y) springs.
Source:
Returns:
True if the viewport is still animating, false otherwise.
Type
Boolean

viewerElementToImageCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the viewer element to image coordinates. Note: not accurate with multi-image.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

viewerElementToViewportCoordinates(pixel) → {OpenSeadragon.Point}

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

viewerElementToViewportRectangle(rectangle) → {OpenSeadragon.Rect}

Convert a rectangle in pixel coordinates relative to the viewer element to viewport coordinates.
Parameters:
Name Type Description
rectangle OpenSeadragon.Rect the rectangle to convert
Source:
Returns:
the converted rectangle
Type
OpenSeadragon.Rect

viewportToImageCoordinates(viewerX, viewerYopt) → {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 Note: not accurate with multi-image; use TiledImage.viewportToImageCoordinates instead.
Parameters:
Name Type Attributes Description
viewerX OpenSeadragon.Point | Number either a point or the X coordinate in viewport coordinate system.
viewerY Number <optional>
 Y coordinate in viewport coordinate system.
Source:
Returns:
a point representing the coordinates in the image.
Type
OpenSeadragon.Point

viewportToImageRectangle(viewerX, viewerYopt, pointWidthopt, pointHeightopt)

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 Note: not accurate with multi-image; use TiledImage.viewportToImageRectangle instead.
Parameters:
Name Type Attributes Description
viewerX OpenSeadragon.Rect | Number either a rectangle or the X coordinate of the top left corner of the rectangle in viewport coordinate system.
viewerY Number <optional>
 the Y coordinate of the top left corner of the rectangle in viewport coordinate system.
pointWidth Number <optional>
 the width of the rectangle in viewport coordinate system.
pointHeight Number <optional>
 the height of the rectangle in viewport coordinate system.
Source:

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... Note: not accurate with multi-image.
Parameters:
Name Type Description
viewportZoom Number The viewport zoom target zoom.
Source:
Returns:
imageZoom The image zoom
Type
Number

viewportToViewerElementCoordinates(point) → {OpenSeadragon.Point}

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

viewportToViewerElementRectangle(rectangle) → {OpenSeadragon.Rect}

Convert a rectangle in viewport coordinates to pixel coordinates relative to the viewer element.
Parameters:
Name Type Description
rectangle OpenSeadragon.Rect the rectangle to convert
Source:
Returns:
the converted rectangle
Type
OpenSeadragon.Rect

viewportToWindowCoordinates(point) → {OpenSeadragon.Point}

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

windowToImageCoordinates(pixel) → {OpenSeadragon.Point}

Convert pixel coordinates relative to the window to image coordinates. Note: not accurate with multi-image.
Parameters:
Name Type Description
pixel OpenSeadragon.Point
Source:
Returns:
Type
OpenSeadragon.Point

windowToViewportCoordinates(pixel) → {OpenSeadragon.Point}

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

zoomBy() → {OpenSeadragon.Viewport}

Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport

zoomTo(zoom, refPointopt, immediatelyopt) → {OpenSeadragon.Viewport}

Zooms to the specified zoom level
Parameters:
Name Type Attributes Default Description
zoom Number The zoom level to zoom to.
refPoint OpenSeadragon.Point <optional>
 The point which will stay at the same screen location. Defaults to the viewport center.
immediately Boolean <optional>
 false
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewport