Represents the viewport for Seadragon content.
The viewport's values are defined in normalized isotropic coordinates based on a width of 1.0. This means that the origin (0, 0) represents the top-left of the content, and the point (0, 1) represents the top-right. The normalized height is computed to match the content's aspect ratio. So for an aspect ratio of 2:1, the bottom-left of the content would be represented by the point (0, 0.5), and the bottom-right would be represented by the point (1, 0.5).
The viewport uses Seadragon.Springs to fluidly pan and zoom. Accessor methods thus provide both current values and target values, and modifier methods can be instructed to override the springs and pan or zoom immediately. Separate springs are used for panning and for zooming; this allows a pan to continue smoothly while a zoom is initiated, and vice versa.
| Signature | Description |
|---|---|
| Seadragon.Viewport(containerSize, contentSize) | Initializes a Viewport inside a container of the given size, for content of the given size. The content will initially be fitted snugly inside the viewport. |
Methods which use the viewport's springs provide the option to return either the target value or the current value. The default is to return the target value, but the current value can be returned by passing in the optional current flag.
| Name and Signature | Return Type | Description |
|---|---|---|
| getAspectRatio() | Number | Returns the viewport's aspect ratio (width / height). |
| getContainerSize() | Seadragon.Point | Returns the size of the viewport's container, in pixels. |
| getBounds(current?) | Seadragon.Rect | Returns the viewport's bounds. |
| getCenter(current?) | Seadragon.Point | Returns the center of the viewport. |
| getZoom(current?) | Number | Returns the zoom level of the viewport. This zoom level is the ratio of the content's width to the viewport's width, e.g. 1 means the widths are the same, 2 means the content's width is double the viewport's width, etc. |
Methods which change the viewport's values provide the option to override the springs. To do so, pass in the optional immediately flag. Otherwise, the springs will be used to smoothly change the viewport's values to the given target values.
| Name and Signature | Return Type | Description |
|---|---|---|
| applyConstraints(immediately?) | - | Zooms and pans to ensure that enough content is visible within the viewport and that the viewport is within a reasonable zoom range. The parameters of this behavior are controlled by the Seadragon.Config minZoomImageRatio, maxZoomPixelRatio and visibilityRatio properties. |
| ensureVisible(immediately?) | - | [Deprecated] Same as applyConstraints(). The name has been changed to reflect this method's expanded role, but this name still exists for backwards compatibility. |
| fitBounds(bounds, immediately?) | - | Zooms and pans so that the given Seadragon.Rect is fitted into the viewport. |
| goHome(immediately?) | - | Zooms and pans so that the content is fitted snugly into the viewport. |
| panBy(delta, immediately?) | - | Pans the viewport by the given Seadragon.Point delta amount. |
| panTo(center, immediately?) | - | Pans the viewport to the given center point. |
| zoomBy(factor, point?, immediately?) | - | Zooms by the given factor about the given point, which will remain at the same on-screen location through the zoom. If no point is given, zooms about the viewport center. |
| zoomTo(level, point?, immediately?) | - | Zooms to the given zoom level about the given point, which will remain at the same on-screen location through the zoom. If no point is given, zooms about the viewport center. |
| resize(containerSize, maintain?) | - | Resizes the viewport to match the given container size in pixels. If maintain is true, the content's on-screen appearance is maintained relative to the viewport's origin, otherwise the content is resized relative to its center, such that the previously visible content remains visible. |
| update() | Boolean | Updates the viewport's current values and returns true if they have changed since the last update. |
These convenience methods provide the constrained pan and zoom values, since these values are determined by both the viewport's and content's aspect ratios as well as multiple Seadragon.Config settings. These values are used by the applyConstraints() method.
The constrained pan values vary by zoom level, so these methods, like the accessor methods, provide the option to use either the viewport's current or target zoom value.
| Name and Signature | Return Type | Description |
|---|---|---|
| getHomeBounds() | Seadragon.Rect | Returns the viewport's fitted bounds at home. |
| getHomeCenter() | Seadragon.Point | Returns the viewport's center point at home. |
| getHomeZoom() | Number | Returns the viewport's zoom level at home. |
| getMinCenter(current?) | Seadragon.Point | Returns the minimum center value (i.e. the furthest top-left) the viewport should pan to. |
| getMaxCenter(current?) | Seadragon.Point | Returns the maximum center value (i.e. the furthest bottom-right) the viewport should pan to. |
| getMinZoom() | Number | Returns the minimum zoom value the viewport should zoom out to. |
| getMaxZoom() | Number | Returns the maximum zoom value the viewport should zoom in to. |
The regular pixel-point methods use both the zoom level and the pan to convert the values. The delta pixel-point methods use only the zoom level to convert the values. Like the accessor methods, these methods provide the option to use either the viewport's current values or the target values.
| Name and Signature | Return Type | Description |
|---|---|---|
| deltaPixelsFromPoints(deltaPoints, current?) | Seadragon.Point | Converts the given normalized point delta to an on-screen pixel delta. |
| deltaPointsFromPixels(deltaPixels, current?) | Seadragon.Point | Converts the given on-screen pixel delta to a normalized point delta. |
| pixelFromPoint(point, current?) | Seadragon.Point | Converts the given normalized point to an on-screen pixel, relative to the viewport's container. |
| pointFromPixel(pixel, current?) | Seadragon.Point | Converts the given on-screen pixel, relative to the viewport's container, to a normalized point. |