Class: View

ol.View

An ol.View object represents a simple 2D view of the map.

This is the object to act upon to change the center, resolution, and rotation of the map.

The view states

An ol.View is determined by three states: center, resolution, and rotation. Each state has a corresponding getter and setter, e.g. getCenter and setCenter for the center state.

An ol.View has a projection. The projection determines the coordinate system of the center, and its units determine the units of the resolution (projection units per pixel). The default projection is Spherical Mercator (EPSG:3857).

The constraints

setCenter, setResolution and setRotation can be used to change the states of the view. Any value can be passed to the setters. And the value that is passed to a setter will effectively be the value set in the view, and returned by the corresponding getter.

But an ol.View object also has a resolution constraint, a rotation constraint and a center constraint.

As said above, no constraints are applied when the setters are used to set new states for the view. Applying constraints is done explicitly through the use of the constrain* functions (constrainResolution and constrainRotation and constrainCenter).

The main users of the constraints are the interactions and the controls. For example, double-clicking on the map changes the view to the "next" resolution. And releasing the fingers after pinch-zooming snaps to the closest resolution (with an animation).

The resolution constraint snaps to specific resolutions. It is determined by the following options: resolutions, maxResolution, maxZoom, and zoomFactor. If resolutions is set, the other three options are ignored. See documentation for each option for more information.

The rotation constraint snaps to specific angles. It is determined by the following options: enableRotation and constrainRotation. By default the rotation value is snapped to zero when approaching the horizontal.

The center constraint is determined by the extent option. By default the center is not constrained at all.

new ol.View(opt_options)

src/ol/view.js, line 80
Name Type Description
options

View options.

Name Type Description
center ol.Coordinate | undefined

The initial center for the view. The coordinate system for the center is specified with the projection option. Default is undefined, and layer sources will not be fetched if this is not set.

constrainRotation boolean | number | undefined

Rotation constraint. false means no constraint. true means no constraint, but snap to zero near zero. A number constrains the rotation to that number of values. For example, 4 will constrain the rotation to 0, 90, 180, and 270 degrees. The default is true.

enableRotation boolean | undefined

Enable rotation. Default is true. If false a rotation constraint that always sets the rotation to zero is used. The constrainRotation option has no effect if enableRotation is false.

extent ol.Extent | undefined

The extent that constrains the center, in other words, center cannot be set outside this extent. Default is undefined.

maxResolution number | undefined

The maximum resolution used to determine the resolution constraint. It is used together with minResolution (or maxZoom) and zoomFactor. If unspecified it is calculated in such a way that the projection's validity extent fits in a 256x256 px tile. If the projection is Spherical Mercator (the default) then maxResolution defaults to 40075016.68557849 / 256 = 156543.03392804097.

minResolution number | undefined

The minimum resolution used to determine the resolution constraint. It is used together with maxResolution (or minZoom) and zoomFactor. If unspecified it is calculated assuming 29 zoom levels (with a factor of 2). If the projection is Spherical Mercator (the default) then minResolution defaults to 40075016.68557849 / 256 / Math.pow(2, 28) = 0.0005831682455839253.

maxZoom number | undefined

The maximum zoom level used to determine the resolution constraint. It is used together with minZoom (or maxResolution) and zoomFactor. Default is 28. Note that if minResolution is also provided, it is given precedence over maxZoom.

minZoom number | undefined

The minimum zoom level used to determine the resolution constraint. It is used together with maxZoom (or minResolution) and zoomFactor. Default is 0. Note that if maxResolution is also provided, it is given precedence over minZoom.

projection ol.ProjectionLike

The projection. Default is EPSG:3857 (Spherical Mercator).

resolution number | undefined

The initial resolution for the view. The units are projection units per pixel (e.g. meters per pixel). An alternative to setting this is to set zoom. Default is undefined, and layer sources will not be fetched if neither this nor zoom are defined.

resolutions Array.<number> | undefined

Resolutions to determine the resolution constraint. If set the maxResolution, minResolution, minZoom, maxZoom, and zoomFactor options are ignored.

rotation number | undefined

The initial rotation for the view in radians (positive rotation clockwise). Default is 0.

zoom number | undefined

Only used if resolution is not defined. Zoom level used to calculate the initial resolution for the view. The initial resolution is determined using the ol.View#constrainResolution method.

zoomFactor number | undefined

The zoom factor used to determine the resolution constraint. Default is 2.

Fires:

Extends

Observable Properties

Name Type Settable ol.Object.Event type Description
center ol.Coordinate | undefined yes change:center

The center of the view.

resolution number | undefined yes change:resolution

The resolution of the view.

rotation number yes change:rotation

The rotation of the view in radians.

Methods

animate(var_args)

src/ol/view.js, line 256

Animate the view. The view's center, zoom (or resolution), and rotation can be animated for smooth transitions between view states. For example, to animate the view to a new zoom level:

view.animate({zoom: view.getZoom() + 1});

By default, the animation lasts one second and uses in-and-out easing. You can customize this behavior by including duration (in milliseconds) and easing options (see ol.easing).

To chain together multiple animations, call the method with multiple animation objects. For example, to first zoom and then pan:

view.animate({zoom: 10}, {center: [0, 0]});

If you provide a function as the last argument to the animate method, it will get called at the end of an animation series. The callback will be called with true if the animation series completed on its own or false if it was cancelled.

Animations are cancelled by user interactions (e.g. dragging the map) or by calling view.setCenter(), view.setResolution(), or view.setRotation() (or another method that calls one of these).

Name Type Description
var_args

Animation options. Multiple animations can be run in series by passing multiple options objects. To run multiple animations in parallel, call the method multiple times. An optional callback can be provided as a final argument. The callback will be called with a boolean indicating whether the animation completed without being cancelled.

Name Type Description
center ol.Coordinate | undefined

The center of the view at the end of the animation.

zoom number | undefined

The zoom level of the view at the end of the animation. This takes precedence over resolution.

resolution number | undefined

The resolution of the view at the end of the animation. If zoom is also provided, this option will be ignored.

rotation number | undefined

The rotation of the view at the end of the animation.

anchor ol.Coordinate | undefined

Optional anchor to remained fixed during a rotation or resolution animation.

duration number | undefined

The duration of the animation in milliseconds (defaults to 1000).

easing undefined | function

The easing function used during the animation (defaults to ol.easing.inAndOut). The function will be called for each frame with a number representing a fraction of the animation's duration. The function should return a number between 0 and 1 representing the progress toward the destination state.

calculateExtent(opt_size){ol.Extent}

src/ol/view.js, line 566

Calculate the extent for the current view state and the passed size. The size is the pixel dimensions of the box into which the calculated extent should fit. In most cases you want to get the extent of the entire map, that is map.getSize().

Name Type Description
size ol.Size

Box pixel size. If not provided, the size of the first map that uses this view will be used.

Returns:
Extent.

cancelAnimations()

src/ol/view.js, line 336

Cancel any ongoing animations.

centerOn(coordinate, size, position)

src/ol/view.js, line 921

Center on coordinate and view position.

Name Type Description
coordinate ol.Coordinate

Coordinate.

size ol.Size

Box pixel size.

position ol.Pixel

Position on the view to center on.

changed() inherited

src/ol/observable.js, line 58

Increases the revision counter and dispatches a 'change' event.

constrainCenter(center){ol.Coordinate|undefined}

src/ol/view.js, line 487

Get the constrained center of this view.

Name Type Description
center ol.Coordinate | undefined

Center.

Returns:
Constrained center.

constrainResolution(resolution, opt_delta, opt_direction){number|undefined}

src/ol/view.js, line 500

Get the constrained resolution of this view.

Name Type Description
resolution number | undefined

Resolution.

delta number

Delta. Default is 0.

direction number

Direction. Default is 0.

Returns:
Constrained resolution.

constrainRotation(rotation, opt_delta){number|undefined}

src/ol/view.js, line 515

Get the constrained rotation of this view.

Name Type Description
rotation number | undefined

Rotation.

delta number

Delta. Default is 0.

Returns:
Constrained rotation.

dispatchEvent(event) inherited

src/ol/observable.js, line 75

Dispatches an event and calls all listeners listening for events of this type. The event parameter can either be a string or an Object with a type property.

Name Type Description
event Object | ol.events.Event | string

Event object.

fit(geometryOrExtent, opt_options)

src/ol/view.js, line 818

Fit the given geometry or extent based on the given map size and border. The size is pixel dimensions of the box to fit the extent into. In most cases you will want to use the map size, that is map.getSize(). Takes care of the map angle.

Name Type Description
geometryOrExtent ol.geom.SimpleGeometry | ol.Extent

The geometry or extent to fit the view to.

options

Options.

Name Type Description
size ol.Size | undefined

The size in pixels of the box to fit the extent into. Default is the current size of the first map in the DOM that uses this view, or [100, 100] if no such map is found.

padding !Array.<number> | undefined

Padding (in pixels) to be cleared inside the view. Values in the array are top, right, bottom and left padding. Default is [0, 0, 0, 0].

constrainResolution boolean | undefined

Constrain the resolution. Default is true.

nearest boolean | undefined

Get the nearest extent. Default is false.

minResolution number | undefined

Minimum resolution that we zoom to. Default is 0.

maxZoom number | undefined

Maximum zoom level that we zoom to. If minResolution is given, this property is ignored.

duration number | undefined

The duration of the animation in milliseconds. By default, there is no animations.

easing undefined | function

The easing function used during the animation (defaults to ol.easing.inAndOut). The function will be called for each frame with a number representing a fraction of the animation's duration. The function should return a number between 0 and 1 representing the progress toward the destination state.

callback undefined | function

Optional function called when the view is in it's final position. The callback will be called with true if the animation series completed on its own or false if it was cancelled.

get(key){*} inherited

src/ol/object.js, line 101

Gets a value.

Name Type Description
key string

Key name.

Returns:
Value.

getAnimating(){boolean}

src/ol/view.js, line 317

Determine if the view is being animated.

Returns:
The view is being animated.

getCenter(){ol.Coordinate|undefined}

src/ol/view.js, line 527

Get the view center.

Returns:
The center of the view.

getInteracting(){boolean}

src/ol/view.js, line 327

Determine if the user is interacting with the view, such as panning or zooming.

Returns:
The view is being interacted with.

getKeys(){Array.<string>} inherited

src/ol/object.js, line 115

Get a list of object property names.

Returns:
List of property names.

getMaxResolution(){number}

src/ol/view.js, line 584

Get the maximum resolution of the view.

Returns:
The maximum resolution of the view.

getMaxZoom(){number}

src/ol/view.js, line 604

Get the maximum zoom level for the view.

Returns:
The maximum zoom level.

getMinResolution(){number}

src/ol/view.js, line 594

Get the minimum resolution of the view.

Returns:
The minimum resolution of the view.

getMinZoom(){number}

src/ol/view.js, line 624

Get the minimum zoom level for the view.

Returns:
The minimum zoom level.

getProjection(){ol.proj.Projection}

src/ol/view.js, line 644

Get the view projection.

Returns:
The projection of the view.

getProperties(){Object.<string, *>} inherited

src/ol/object.js, line 125

Get an object of all property names and values.

Returns:
Object.

getResolution(){number|undefined}

src/ol/view.js, line 655

Get the view resolution.

Returns:
The resolution of the view.

getResolutionForExtent(extent, opt_size){number}

src/ol/view.js, line 680

Get the resolution for a provided extent (in map units) and size (in pixels).

Name Type Description
extent ol.Extent

Extent.

size ol.Size

Box pixel size.

Returns:
The resolution at which the provided extent will render at the given size.

getResolutions(){Array.<number>|undefined}

src/ol/view.js, line 667

Get the resolutions for the view. This returns the array of resolutions passed to the constructor of the {ol.View}, or undefined if none were given.

Returns:
The resolutions of the view.

getRevision(){number} inherited

src/ol/observable.js, line 84

Get the version number for this object. Each time the object is modified, its version number will be incremented.

Returns:
Revision.

getRotation(){number}

src/ol/view.js, line 717

Get the view rotation.

Returns:
The rotation of the view in radians.

getZoom(){number|undefined}

src/ol/view.js, line 769

Get the current zoom level. Return undefined if the current resolution is undefined or not within the "resolution constraints".

Returns:
Zoom.

getZoomForResolution(resolution){number|undefined}

src/ol/view.js, line 785

Get the zoom level for a resolution.

Name Type Description
resolution number

The resolution.

Returns:
The zoom level for the provided resolution.

on(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 99

Listen for a certain type of event.

Name Type Description
type string | Array.<string>

The event type or array of event types.

listener function

The listener function.

this Object

The object to use as this in listener.

Returns:
Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

once(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 124

Listen once for a certain type of event.

Name Type Description
type string | Array.<string>

The event type or array of event types.

listener function

The listener function.

this Object

The object to use as this in listener.

Returns:
Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

rotate(rotation, opt_anchor)

src/ol/view.js, line 955

Rotate the view around a given coordinate.

Name Type Description
rotation number

New rotation value for the view.

anchor ol.Coordinate

The rotation center.

set(key, value, opt_silent) inherited

src/ol/object.js, line 150

Sets a value.

Name Type Description
key string

Key name.

value *

Value.

silent boolean

Update without triggering an event.

setCenter(center)

src/ol/view.js, line 970

Set the center of the current view.

Name Type Description
center ol.Coordinate | undefined

The center of the view.

setMaxZoom(zoom)

src/ol/view.js, line 614

Set a new maximum zoom level for the view.

Name Type Description
zoom number

The maximum zoom level.

setMinZoom(zoom)

src/ol/view.js, line 634

Set a new minimum zoom level for the view.

Name Type Description
zoom number

The minimum zoom level.

setProperties(values, opt_silent) inherited

src/ol/object.js, line 170

Sets a collection of key-value pairs. Note that this changes any existing properties and adds new ones (it does not remove any existing properties).

Name Type Description
values Object.<string, *>

Values.

silent boolean

Update without triggering an event.

setResolution(resolution)

src/ol/view.js, line 996

Set the resolution for this view.

Name Type Description
resolution number | undefined

The resolution of the view.

setRotation(rotation)

src/ol/view.js, line 1010

Set the rotation for this view.

Name Type Description
rotation number

The rotation of the view in radians.

setZoom(zoom)

src/ol/view.js, line 1023

Zoom to a specific zoom level.

Name Type Description
zoom number

Zoom level.

un(type, listener, opt_this) inherited

src/ol/observable.js, line 147

Unlisten for a certain type of event.

Name Type Description
type string | Array.<string>

The event type or array of event types.

listener function

The listener function.

this Object

The object which was used as this by the listener.

unset(key, opt_silent) inherited

src/ol/object.js, line 184

Unsets a property.

Name Type Description
key string

Key name.

silent boolean

Unset without triggering an event.