WMS decorations provide a framework for visually annotating images from WMS with absolute (rather than spatial) positioning. Examples of decorations include compasses, scalebars, and watermarks.
The wms decoration code currently lives in the wmslayout community module. To build it:
and to run GeoServer with it, add target/wmslayout-1.7.3-SNAPSHOT.jar to GeoServer's classes directory, or in a development environment:
The wmslayout module provides a new base class for raster GetMapProducers that support decoration layouts. It also provides the Decoration interface for classes which provide decorations, the DecorationLayout class which manages and positions a collection of Decorations, and a few Decoration implementations.
Developers of new Decorations should implement the Decoration interface and then add a Decoration instance to the application context:
To use decorations in a WMS getmaprequest, one must first configure a layout. Layouts are stored in XML files in the GeoServer data directory, one file per layout. Each layout file must have the extension .xml. Once a layout foo.xml is defined, users can request it by adding &format_options=layout:foo to the request parameters. As an implementation detail, while the layout code is implemented as a plugin, users must also specify format=png-decorated.
Layout files follow a very simple XML structure; a root node named layout containing any number of decoration elements. Each decoration element has several attributes:
- type: must be the name of a decoration plugin (such as 'watermark' 'scaleratio' 'legend'). required
- affinity: which position to anchor this decoration to. formatted as an ordered pair, verticalposition,horizontalposition. Vertical position can be 'top', 'center', or 'bottom'. Horizontal position can be 'left', 'center', or 'right'.
- offset: how far from the 'affinity' position this decoration should be. optional (defaults to 0,0), specified in pixels, must be a pair of integers in the format x,y. If affinity is 'center' for either axis, then the offset for that direction is ignored.
- size: the maximum size to render this object at. If omitted, decorations can determine the size themselves. Plugins are not required to render at the full size, but are required to stay within these bounds if specified. optional, specified in pixels, must be a pair of integers in the format width,height, OR the text 'auto'.
Each decoration element may also contain an arbitrary number of option elements providing a parameter name and value:
Option interpretation is left to decoration providers to define.
There are currently three decorations implemented.
- Image [image]: Overlays a static image onto the document. If height and width are specified, will scale image to fit, otherwise renders at 100% size or (map dimensions - offset size), whichever is smaller. Respects one option named "url" whose value is interpreted as the URL to the image to use. The URL is evaluated relative to the GeoServer data directory.
- Scale Ratio [scaleratio]: Overlays a text description of the current scale ratio onto the document. Does not respect any options.
- Legend [legend]: Overlays a legend onto the document, similar to the one provided by WMS getLegendGraphic requests, but with labels included for all rules and with titles per-layer. Does not respect any options.
The following image was produced from this layout (right-click and 'view image' for full size):