Time for action – creating animated maps

The best way to understand these animation functions is to try them out. Start from the previous example:

First, add some buttons to trigger the animation effects:

<button onclick="doBounce(london);">Bounce To London</button>
<button onclick="doBounce(rome);">Bounce To Rome</button
<button onclick="doPan(london);">Pan To London</button>
<button onclick="doPan(rome);">Pan To Rome</button>
<button onclick="doRotate();">Rotate</button>
<button onclick="doZoom(2);">Zoom Out</button>
<button onclick="doZoom(0.5);">Zoom In</button>

These are regular HTML buttons that call a function when clicked. We'll add the functions in a moment.

Next, add a new location for Rome, next to the line where we defined the location of London:
```
var rome = ol.proj.transform([12.5, 41.9], 'EPSG:4326', 'EPSG:3857');
```

Now, we'll add functions at the end of our <script> tag to handle the button clicks. Start with the doBounce() function:

function doBounce(location) {
  var bounce = ol.animation.bounce({
    resolution: map.getView().getResolution() * 2
  });
  var pan = ol.animation.pan({
    source: map.getView().getCenter()
  });
  map.beforeRender(bounce);
  map.beforeRender(pan);
  map.getView().setCenter(location);
}

Next, add the doPan() function:

function doPan(location) {
  var pan = ol.animation.pan({
    source: map.getView().getCenter()
  });
  map.beforeRender(pan);
  map.getView().setCenter(location);
}

Next, add the doRotate() function:

function doRotate() {
 var rotate = ol.animation.rotate({
 rotation  : Math.PI * 2
 });
 map.beforeRender(rotate);
}

Finally, add the doZoom() function:

function doZoom(factor) {
  var resolution = map.getView().getResolution();
  var zoom = ol.animation.zoom({
    resolution: resolution
  });
  map.beforeRender(zoom);
  map.getView().setResolution(resolution * factor);
}

Now, reload the example in your web browser and try clicking on the buttons. You should see the map zoom, pan, and bounce between London and Rome.

What just happened?

Not too bad! In a few lines of code, we managed to create some pretty impressive animation effects using ol.animation functions and the Map's beforeRender() method.

In step 3, we created the doBounce() function. This function takes a single parameter, location, which is the location that we want to bounce to. The effect we want to achieve is to smoothly zoom out from our current location and then into the new location. We called ol.animation.bounce() to create a function that implements the bounce animation effect. For this example, we provided only the resolution property and let the other properties (start, duration, and easing) take their default values. We set the resolution property to two times the current resolution of the map's view. This is equivalent to clicking the ZoomOut control (the button in the top-left corner of the map with the minus sign) once. What this does is smoothly zoom out from the current resolution to the next zoom level, and then back into the current resolution.

Next, we created a function that implements the pan animation effect. Again, we used the defaults for start, duration, and easing by not specifying them and set the source property to the current center of the map's view. We added both bounce and pan functions to the map by calling beforeRender(); then, we changed the map's view to go to the location we passed into this function.

In step 4, the doPan() function takes a single parameter, location, and smoothly pans the map to it. To do this, we called ol.animation.pan() with the map's current center for the source as we did in the doBounce() function, then we told the map's view to go to the new location.

In step 5, the doRotate() function doesn't take any parameters; we just wanted to spin the map 360 degrees. We used the ol.animation.rotate() function for this and set the rotation option to specify how much to rotate. When we add this to the map using beforeRender(), the effect happens immediately.

Tip

In OpenLayers, rotation is always specified in radians. When we think about rotation, we normally think in degrees. To convert from degrees to radians, it is useful to remember that 180 degrees = PI * radians. We don't need to know the value of PI, JavaScript provides us with the useful constant, Math.PI. The formula to convert degrees to radians is var radians = degrees * Math.PI / 180;. The inverse is var degrees = radians * 180 / Math.PI;. In our example, we wanted to rotate the map 360 degrees. Using the formula above, this becomes 2 * Math.PI, which is the value we used.

Step 6 adds the doZoom() function. It takes a single parameter, factor, which is the amount to zoom. We used ol.animation.zoom() to create our animation function using the view's current resolution as our starting point. Then, we added our animation function and told the map's view to zoom to a new resolution by multiplying the current resolution by the factor parameter. A factor of two will cause the map to zoom out to the next zoom level and a factor of 0.5 will cause the map to zoom in to the next zoom level.

Have a go hero – exploring animation properties

Now that we've seen how the basic animations work, try modifying the animation properties in each function to see how to change its parameters and overriding the default duration, start time and easing functions. You can also try combining the animations in different ways.

Conversion methods

When we click on a web page, the browser generates a MouseEvent that contains, among other things, the position that the click happened at. This position is in pixels and is relative to the browser window. In an OpenLayers application, we will often want to respond to the user interacting with the map and it is important to understand these events specify the position in pixels. It is common to need to determine the geographic coordinate that corresponds to this position. OpenLayers provides several methods that allow us to convert between the browser's pixel space and geographic coordinates:

Method	Parameters	Description
`getCoordinateFromPixel( pixel )`	`pixel – ol.Pixel`	This method converts a pixel position to a geographic coordinate and returns an `ol.Coordinate`. The pixel position is relative to the HTML element the map is contained in.
`getPixelFromCoordinate( coordinate )`	`coordinate – ol.Coordinate`	This method converts a geographic coordinate into a pixel position relative to the HTML element that the map is contained in and returns an `ol.Pixel`.
`getEventCoordinate( event )`	`event – BrowserEvent`	This method computes the geographic coordinate from a browser event (such as a click or mouse move) and returns an `ol.Coordinate`.
`getEventPixel( event )`	`event - BrowserEvent`	The method computes the pixel location of a browser event relative to the map's HTML element and returns an `ol.Pixel`.

Other methods

The map object contains a few other methods that don't neatly fit into the previous groups; so, we've included them here for completeness:

Method	Parameters	Description
`forEachFeatureAtPixel(pixel, callback, opt_this, opt_layerFilter, opt_this2 )`	`pixel – ol.Pixel` `callback – function` `opt_this – object, or null` `opt_layerFilter – function or null` `opt_this2 – object or null`	This method queries all layers contained in the map for any features that intersect the pixel location provided. The callback function will be called once for each feature found with the feature as the first argument and the layer it was found in as the second argument. If provided, `opt_this` will be used as the context for the callback function (the value of `this` inside the function). By default, all layers will be queried; however, you can choose which layers to query by providing a function for the `opt_layerFilter` argument. This function will be called once for each layer, passing the layer as the only argument, and is expected to return `true` if the layer is to be queried and `false` if the layer is not to be queried. The final `opt_this2` argument will be used as the context for the layer filter function if provided.
`getViewport( )`	`None`	This method returns the HTML element that the map is contained within. Unlike the map's `target` property, which may return either a string or an HTML element, this method will always return the HTML element.
`updateSize()`	`None`	This method tells the map to recalculate its size based on its container. This is used when other code changes the size of the map's target element.

Table of Contents for OpenLayers 3 : Beginner's Guide

Time for action – creating animated maps

What just happened?

Tip

Have a go hero – exploring animation properties

Conversion methods

Other methods

Table of Contents for
OpenLayers 3 : Beginner's Guide