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:

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:

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 layers, aparam and 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:

Any of these defaults can be overridden when specifying the request. The styles parameter is derived by using the default style as configured by GeoServer for each 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

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.

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

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

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:

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:

<layout>
  <decoration type="text" affinity="bottom,right" offset="6,6">
    <option name="message" value="${avalue}"/>
    <option name="font-size" value="12"/>
    <option name="font-family" value="Arial"/>
    <option name="halo-radius" value="2"/>
  </decoration>
</layout>

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

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.