Skip to content

Latest commit

 

History

History
270 lines (181 loc) · 12.1 KB

vendor.rst

File metadata and controls

270 lines (181 loc) · 12.1 KB
Raw

WMS vendor parameters

WMS vendor parameters are non-standard request parameters that are defined by an implementation to provide enhanced capabilities. GeoServer supports a variety of vendor-specific WMS parameters.

angle

The angle parameter rotates the output map clockwise around its center. The syntax is:

angle=<x>

where <x> is the number of degrees to rotate by.

Map rotation is supported in all raster formats, PDF, and SVG when using the Batik producer (which is the default).

buffer

The buffer parameter specifies the number of additional border pixels that are used in the GetMap and GetFeatureInfo operations. The syntax is:

buffer=<bufferwidth>

where <bufferwidth> is the width of the buffer in pixels.

In the wms_getmap operation, buffering includes features that lie outside the request bounding box, but whose styling is thick enough to be visible inside the map area.

In the wms_getfeatureinfo operation, buffering creates a "search radius" around the location of the request. Feature info is returned for features intersecting the search area. This is useful when working with an OpenLayers map (such as those generated by the layerpreview page) since it relaxes the need to click precisely on a point for the appropriate feature info to be returned.

In both operations GeoServer attempts to compute the buffer value automatically by inspecting the styles for each layer. All active symbolizers are evaluated, and the size of the largest is used (i.e. largest point symbolizer, thickest line symbolizer). Automatic buffer sizing cannot be computed 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 this event, the following defaults are used:

  • 0 pixels for wms_getmap requests
  • 5 pixels for wms_getfeatureinfo requests (a different min value can be set via the org.geoserver.wms.featureinfo.minBuffer system variable, e.g., add -Dorg.geoserver.wms.featureinfo.minBuffer=10 to make the min buffer be 10 pixels)

If these are not sufficiently large, the explicit parameter can be used.

cql_filter

The cql_filter parameter is similar to the standard filter parameter, but the filter is expressed using ECQL (Extended Common Query Language). ECQL provides a more compact and readable syntax compared to OGC XML filters. For full details see the filter_ecql_reference and cql_tutorial tutorial.

If more than one layer is specified in the layers parameter, then a separate filter can be specified for each layer, separated by semicolons. The syntax is:

cql_filter=filter1;filter2...

An example of a simple CQL filter is:

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:

env=param1:value1;param2:value2;...

See sld_variable_substitution for more information.

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 in this example:

featureid=states.1,states.45

filter

The WMS specification allows only limited filtering of data. GeoServer enhances the WMS filter capability to match that provided by WFS. The filter parameter can specify a list of OGC XML filters. The list is enclosed in parentheses: ( ). When used in a GET request, the XML tag brackets must be URL-encoded.

If more than one layer is specified in the layers parameter then a separate filter can be specified for each layer.

An example of an OGC filter encoded in a GET request is:

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 syntax is:

format_options=param1:value1;param2:value2;...

The supported format options are:

  • antialiasing (values = on, off, text): controls the use of antialiased rendering in raster output.
  • callback: specifies the callback function name for the jsonp response format (default is parseResponse).
  • dpi: sets the rendering DPI (dots-per-inch) for raster outputs. The OGC standard output resolution is 90 DPI. If you need to create high resolution images (e.g for printing) it is advisable to request a larger image size and specify a higher DPI. In general, the image size should be increased by a factor equal to targetDPI/90, with the target dpi set in the format options. For example, to print a 100x100 image at 300 DPI request a 333x333 image with the DPI value set to 300: &width=333&height=333&format_options=dpi:300
  • layout: specifies a layout name to use. Layouts are used to add decorators such as compasses and legends. This capability is discussed further in the wms_decorations section.
  • quantizer ((values = octree, mediancut): controls the color quantizer used to produce PNG8 images. GeoServer 2.2.0 provides two quantizers, a fast RGB quantizer called octree that does not handle translucency and a slower but more accurate RGBA quantizer called mediancut. By default the first is used on opaque images, whilst the second is enabled if the client asks for a transparent image (transparent=true). This vendor parameter can be used to manually force the usage of a particular quantizer.
  • kmattr ((values = true,false)): determines whether the KML returned by GeoServer should include clickable attributes or not. This parameter primarily affects Google Earth rendering.
  • legend ((values = true,false)): KML may add the legend.
  • kmscore ((values = between 0 to force raster output and 100 to force vector output)): parameter sets whether GeoServer should render KML data as vector or raster. This parameter primarily affects Google Earth rendering.
  • kmltitle: parameter sets the KML title.
  • kmlrefresh ((values = greater than 0 or expires): Force Network Link reload in refresh mode on interval of seconds. When expires is specified client will refresh whenever the time has elapsed specified in cache expiration headers. The caching time may be set in the Layer configuration under Publishing tab setting HTTP Cache Time. This parameter primarily affects Google Earth rendering and is dependent on being respected by the client. Using a second interval is a more reliable choice.
  • kmlvisible ((values = true,false)): Indicates whether layers selected will default to enabled or not. Default behavior is enabled. This parameter primarily affects Google Earth rendering.

maxFeatures and startIndex

The parameters maxFeatures and startIndex can be used together to provide "paging" support. Paging 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.

The startindex=n parameter specifies the index from which to start rendering in an ordered list of features. n must be a positive integer.

The maxfeatures=n parameter sets a limit on the amount of features rendered. n must be a positive integer. When used with startindex, the features rendered will be the ones starting at the startindex value.

Note that not all layers support paging. For a layer to be queried in this way, the underlying feature source must support paging. This is usually the case for databases (such as PostGIS).

namespace

The namespace parameter causes WMS wms_getcap responses to be filtered to only contain layers in to a particular namespace. The syntax is:

namespace=<namespace>

where <namespace> is the namespace prefix.

Warning

Using an invalid namespace prefix will not cause an error, but the capabilities document returned will contain no layers, only layer groups.

Note

This affects the capabilities document only, not other requests. Other WMS operations will still process all layers, even when a namespace is specified.

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=<image>

where <image> is the filename of the palette image (without the extension). To force a web-safe palette, use the syntax palette=safe. For more information see the tutorial on tutorials_palettedimages

propertyName

The propertyName parameter specifies which properties are included in the response of the GetFeatureInfo operation. The syntax is the same as in the WFS GetFeature operation. For a request for a single layer the syntax is:

propertyName=name1,...,nameN

For multiple layers the syntax is:

propertyName=(nameLayer11,...,nameLayer1N)...(name1LayerN,...,nameNLayerN)

The nature of the properties depends on the layer type:

  • For vector layers the names specify the feature attributes.
  • For raster layers the names specify the bands.
  • For cascaded WMS layers the names specify the GML properties to be returned by the remote server.

tiled

Meta-tiling prevents issues with duplicated labels when using a tiled client such as OpenLayers. When meta-tiling is used, 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, the tile size must be set to 256x256 pixels, and the tiled and tilesorigin parameters must be specified.

The tiled parameter controls whether meta-tiling is used. The syntax is:

tiled=[true|false]

To invoke meta-tiling use tiled=true.

tilesorigin

The tilesorigin parameter is also required for meta-tiling. The syntax is:

tilesorigin=x,y

where x and y are the coordinates of the lower left corner (the "origin") of the tile grid system.

OpenLayers example

In OpenLayers, a good way to specify the tilesorigin is to reference the map extents directly.

Warning

If the map extents are modified dynamically, the tilesorigin of each meta-tiled layer must be updated accordingly.

The following code shows how to specify the meta-tiling parameters:

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} 
);

scaleMethod

The scaleMethod parameter controls how the scale denominator is computed by GeoServer The two possible values are:

  • OGC (default): the scale denominator is computed according to the OGC SLD specification, which

    imposes simplified formulas for the sake of interoperability

  • Accurate: use the full expressions for computing the scale denominator against geographic

    data, taking into account the ellipsoidal shape of Earth

The two methods tend to return values rather close to each other near the equator, but they do diverge to larger differences as the latitude approaches the poles.