.. _wms_vendor_parameters: WMS vendor parameters ===================== WFS vendor parameters are options that are not defined in the official WMS specification, but are allowed by it. GeoServer supports a range of custom WMS parameters. angle ----- Starting with GeoServer 2.0.2 ``angle=x`` rotates the map around its center by `x` degrees clockwise. The rotation is supported in all raster formats, PDF and SVG based on the Batik producer (the default one). buffer ------ The ``buffer`` parameter specifies the number of extra pixels that should be taken into account when rendering a map (using the :ref:`wms_getmap` operation). This is important for catching features that are outside the current bounding box, but whose styling is thick enough to be visible inside the relevant area. GeoServer will try to compute this buffer automatically by parsing the SLD, but that may fail if line widths and point sizes are not literal values. When these size are linked to attributes, this parameter may be necessary. The syntax for using a buffer is:: buffer= where ```` is the radius of the buffer in pixels. Buffer also applies to the :ref:`wms_getfeatureinfo` operation. This creates a "search radius", where feature info will be returned for the area around the location of the request. This is useful when working with an OpenLayers map (such as those generated by the :ref:`layerpreview` page) as it relaxes the need to click precisely on a point for the appropriate feature info to be returned. Both in the :ref:`wms_getmap` and in the :ref:`wms_getfeatureinfo` cases the default ``buffer`` value is computed automatically for each layer by inspecting the associated style. This happens by visiting the style, checking all active symbolizers, and returning the size of the biggest one (biggest point symbolizer, thickest line symbolizer). This automatic inspection won't work if: * the SLD contains sizes that are specified as feature attribute values * the SLD contains external graphics and does not specify their size explicitly In case the automatic evaluation fails, the following defaults apply: * 0 pixels for :ref:`wms_getmap` requests * 2 pixels for :ref:`wms_getfeatureinfo` requests cql_filter ---------- The ``cql_filter`` parameter is similar to the ``filter`` parameter, expect that the filter is encoded using CQL (Common Query Language). This makes the request much more human readable. However, CQL isn't as flexible as OGC filters, and can't encode as many types of filters as the OGC specification does. In particular, filters by feature ID are not supported. If more than one layer is specified in the ``layers`` parameter, then more than one filter can be specified here, each corresponding to a layer. An example of the same filter as above using CQL:: cql_filter=INTERSECT(the_geom,%20POINT%20(-74.817265%2040.5296504)) env --- The ``env`` parameter defines the set of substitution values that can be used in SLD variable substitution. The syntax is:: param1:value1;param2:value2;... featureid --------- The ``featureid`` parameter filters by feature ID, a unique value given to all features. Multiple features can be selected by separating the featureids by comma, as seen in this example:: featureid=states.1,states.45 filter ------ The WMS specification does not allow for much filtering of data. GeoServer's WMS filter options are expanded to match those allowed by WFS. The ``filter`` parameter encodes a list of OGC filters (in XML). The list is enclosed in () parenthesis. When this parameter is used in a GET request, the brackets of XML need to be URL-encoded. If more than one layer is specified in the ``layers`` parameter, then more than one filter can be specified here, each corresponding to a layer. An example of an OGC filter encoded as part of a GET request:: filter=%3CFilter%20xmlns:gml=%22http://www.opengis.net/gml%22%3E%3CIntersects%3E%3CPropertyName%3Ethe_geom%3C/PropertyName%3E%3Cgml:Point%20srsName=%224326%22%3E%3Cgml:coordinates%3E-74.817265,40.5296504%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E format_options -------------- The ``format_options`` is a container for parameters that are format specific. The options in it are expressed as:: param1:value1;param2:value2;... The currently recognized format options are: * ``antialiasing`` (on, off, text): allows to control the use of antialiased rendering in raster outputs. * ``dpi``: sets the rendering dpi in raster outputs. The OGC standard dpi is 90, but if you need to perform high resolution printouts it is advised to grab a larger image and set a higher dpi. For example, to print at 300dpi a 100x100 image it is advised to ask for a 333x333 image setting the dpi value at 300. In general the image size should be increased by a factor equal to ``targetDpi/90`` and the target dpi set in the format options. * ``layout``: chooses a named layout for decorations, a tool for visually annotating GeoServer's WMS output. Layouts can be used to add information such as compasses and legends to the maps you retrieve from GeoServer. :ref:`wms_decorations` are discussed further in the :ref:`advanced_config` section. kmattr ------ The ``kmattr`` parameter determines whether the KML returned by GeoServer should include clickable attributes or not. This parameter primarily affects Google Earth rendering. The syntax is:: kmattr=[true|false] kmscore ------- The ``kmscore`` parameter sets whether GeoServer should render KML data as vector or raster. This parameter primarily affects Google Earth rendering. The syntax is:: kmscore= The possible values for this parameter are between ``0`` (force raster output) and ``100`` (force vector output). maxFeatures and startIndex -------------------------- GeoServer WMS supports the parameters ``maxFeatures`` and ``startIndex``. Both can be used together to provide "paging" support. This is helpful in situations such as KML crawling, where it is desirable to be able to retrieve the map in sections when there are a large number of features. Note that not every layer will support paging. The ``startindex`` parameter specifies with a positive integer the index in an ordered list of features to start rendering. For a layer to be queried this way, the underlying feature source shall support paging (such as PostGIS). The ``maxfeatures`` parameter sets a limit on the amount of features rendered, using a positive integer. When used with ``startindex``, the features rendered will be the ones starting at the ``startindex`` value. namespace --------- WMS :ref:`wms_getcap` requests can be filtered to only return layers corresponding to a particular namespace. The syntax is:: namespace= where ```` is the namespace prefix. Using an invalid namespace prefix will not cause any errors, but the document returned will not contain information on any layers, only layer groups. .. note:: This only affects the capabilities document, and not any other requests. WMS requests given to other layers, even when a different namespace is specified, will still be processed. palette ------- It is sometimes advisable (for speed and bandwidth reasons) to downsample the bit depth of returned maps. The way to do this is to create an image with a limited color palette, and save it in the ``palettes`` directory inside your GeoServer Data Directory. It is then possible to specify the ``palette`` parameter of the form:: palette= where ```` is the filename of the palette image (without the extension). To force a web-safe palette, you can use the syntax ``palette=safe``. For more information see the tutorial on :ref:`tutorials_palettedimages` tiled ----- When using a tiled client such as OpenLayers, there can be issues with duplicated labels. To deal with this, GeoServer can create metatiles, that is, images are rendered and then split into smaller tiles (by default in a 3x3 pattern) before being served. In order for meta-tiling to work properly, the tile size must be set to 256x256 pixels, and two extra parameters must be set. The ``tiled`` parameter is of the form:: tiled=[yes|no] For metatiling to function, this must be set to ``yes``. tilesorigin ----------- The ``tilesorigin`` parameter, also necessary for metatiling, is of the form:: tilesorigin=x,y where ``x`` and ``y`` are the coordinates of the lower left corner (the "origin") of the tile grid system in OpenLayers. A good way to setup the tilesorigin in OpenLayers is referencing the map extents directly (if the max extents are modified dynamically, also remember to update the ``tilesorigin`` of each meta-tiled layer accordingly): .. code-block:: javascript :linenos: var options = { ... maxExtent: new OpenLayers.Bounds(-180, -90, 180, 90), ... }; map = new OpenLayers.Map('map', options); tiled = new OpenLayers.Layer.WMS( "Layer name", "http://localhost:8080/geoserver/wms", { srs: 'EPSG:4326', width: 391, styles: '', height: 550, layers: 'layerName', format: 'image/png', tiled: true, tilesorigin: [map.maxExtent.left, map.maxExtent.bottom] }, {buffer: 0} );