.. _tutorials_animreflector: WMS Animator ============= Overview -------- Current WMS can only generate static maps. There is however a number of use cases in which generating an animation is interesting. One obvious case is time based animation, but elevation based animation is just as interesting, and there are cases in which the various frames have to be generated by changing the parameters of sql views, sld substitution parameters, or plain coordinates of the generated map (to get a moving one). The animator works pretty much like the WMS reflector, but is installed on the wms/animate path: given an incomplete WMS request it fills it putting and using extra parameters to turn it into a repeated template: * **aparam**: the name of the parameter that will be used to change the request at each step. Could be anything from layers, cql_filter, bbox, style and so on. In case it is a nested parameter, like for the format_options, env and view_param case, it will take the form of container:name, for example, view_params:year * **avalues**: a comma separated list of the values the parameter will take. One example of animated request based on a changing bbox will be: .. code-block:: html http://localhost:8080/geoserver/wms/animate?layers=topp:states&aparam=bbox&avalues=-90\,40\,-60\,70,-80\,40\,-60\70,-70\,40\,-50\70 which would generate an animation of the layer with the camera scrolling towards east. An example of an animation changing colors based on SLD enviroment variable would be instead: .. code-block:: html http://localhost:8080/geoserver/wms/animate?layers=topp:states,topp:states&styles=polygon,selection&aparam=env:color&avalues=FF0000,00FF00,0000FF which would generate an animated map whose selection color (coming from the color parameter and used in the selection style) would iterate between red, green and blue. The animator would unpack the values, build the replacement parameter, kvp parse it and run the wms request which is then executed to generate one frame. This of course might generate invalid requests, it's up to the caller to ensure the request is valid. Using the WMS Animator ---------------------- To use the WMS Animator all one must do is specify ``wms/animate?`` as opposed to ``wms?`` in a request. The only mandatory parameters to a WMS Animator call are the :guilabel:`layers`, :guilabel:`aparam` and :guilabel:`avalues` parameters. As stated above the reflector fills in sensible defaults for the rest of the parameters. The following table lists all the defaults used: .. list-table:: :widths: 50 50 * - request - getmap * - service - wms * - version - 1.1.1 * - format - image/png * - width - 512 * - height - 512 if width is not specified * - srs - EPSG:4326 * - bbox - bounds of layer(s) Any of these defaults can be overridden when specifying the request. The :guilabel:`styles` parameter is derived by using the default style as configured by GeoServer for each :guilabel:`layer` specified in the layers parameter. Any parameter you send with a WMS request is also legitimate when requesting data from the reflector. Its strength is what it does with the parameters you do not specify, which is explored in the next section. **layers**: This is the only mandatory parameter. It is a comma separated list of the layers you wish to include in your image or OpenLayers application. **format**: The default output format is image/png. Alternatives include image/jpeg (good for raster backgrounds), image/png8 (8 bit colors, smaller files) and image/gif .. Warning:: In order to see an animation you need to use a format capable of handling it. At this time the only one enabled in GeoServer is **image/gif;subtype=animated** **width**: Describes the width of the image, alternatively the size of the map in an OpenLayers. It defaults to 512 pixels and can be calculated based on the height and the aspect ratio of the bounding box. **height**: Describes the height of the image, alternatively the map in an OpenLayers. It can be calculated based on the width and the aspect ratio of the bounding box. **bbox**: The bounding box is automatically determined by taking the union of the bounds of the specified layers. In essence, it determines the extent of the map. By default, if you do not specify bbox, it will show you everything. If you have one layer of Los Angeles, and another of New York, it show you most of the United States. The bounding box, automatically set or specified, also determines the aspect ratio of the map. If you only specify one of width or height, the other will be determined based on the aspect ratio of the bounding box. **styles**: You can override the default styles by providing a comma separated list with the names of styles which must be known by the server. **srs**: The spatial reference system (SRS) parameter is somewhat difficult. If not specified the WMS Reflector will use EPSG:4326 / WGS84. It will support the native SRS of the layers as well, provided all layers share the same one. Example 1 ````````` Request the layer topp:states , it will come back with the default style (demographic), width (512 pixels) and height (adjusted to aspect ratio). The animation will have two frames one at wole world BBOX and another one around USA, giving the effect of zooming in. .. code-block:: html http://localhost:8080/geoserver/wms/animate?layers=topp:states&format=image/gif;subtype=animated&aparam=bbox&avalues=-180\,-90\,180\,90,-125\,25\,-67\,50 Example 2 ````````` Request the layers topp:states and sf:restricted, it will come back with the default styles, and the specified width (640 pixels) and the height automatically adjusted to the aspect ratio. The format_options will return an infinite loop animation. .. code-block:: html http://localhost:8080/geoserver/wms/animate?layers=topp:states,sf:restricted&format=image/gif;subtype=animated&aparam=bbox&avalues=-180\,-90\,180\,90,-125\,25\,-67\,50&format_options=gif_loop_continuosly:true&width=640 Example 3 ````````` Lets now rotate the image very fast and forever. .. code-block:: html http://localhost:8080/geoserver/wms/animate?layers=topp:states,sf:restricted&format=image/gif;subtype=animated&aparam=angle&avalues=0,45,90,135,180,225,270,365&format_options=gif_loop_continuosly:true;gif_frames_delay:10&width=640 Adding current frame values as text overlays -------------------------------------------- It is possible to decorate each frame with the ``avalue`` that generated it using the ``text`` map decoration and having it exand the ``avalue`` parameter, which is fed into the ``env`` map while the animator runs (if needs be, the same value can also be used as a SLD parameter). Here is an example call that uses a decoration: .. code-block:: html http://localhost:8080/geoserver/wms/animate?LAYERS=topp%3Aworld&aparam=time&avalues=2004-01-01T00:00:00.000Z,2004-02-01T00:00:00.000Z&format=image/gif;subtype=animated&format_options=layout:message which uses the following decoration layout, located in ``layouts/message.xml``: .. code-block:: xml WMS Animator default behaviour through WMS Params ------------------------------------------------- The GeoServer amdinistrator GUI allows you also to setup some default parameters for the WMS Animator. Going to Service > WMS config panel, it's possible to find the parameters as depicted below .. figure:: animator_wms_params.jpg :align: center *WMS Animator default settings* The first three options allows you to limit the animation requests. It's possible to set the maximum number of frames an animation can contain, the maximum rendering time to produce an animation and the maximum size of the whole animation. Also it's possible to set the default animation behaviour in terms of frames delay (expressed in ms) and the loop. The latters can be overridden using the format_options like in the Examples above.