GetLegendGraphic¶

What’s a raster legend¶

Here below I have drawn the structure of a typical legend, where some elements of interests are parameterized.

Take as an instance one of the SLD files attached to this page, each row in the above table draws its essence from the ColorMapEntry element as shown here below:

<ColorMapEntry color="#732600" quantity="9888" opacity="1.0" label="<-70 mm"/>

The producer for the raster legend will make use of this elements in order to build the legend, with this in mind, notice that:

• the width of the Color element is driven by the requested width for the GetLegendGraphic request

• the width and height of label and rules is computed accordingly to the used Font and Font size for the prepared text (no new line management for the moment)

• the height of the Color element is driven by the requested width for the GetLegendGraphic request, but notice that for ramps we expand this a little since the goal is to turn the various Color elements into a single long strip

• the height of each row is set to the maximum height of the single elements

• the width of each row is set to the sum of the width of the various elements plus the various paddings

• dx,dy the spaces between elements and rows are set to the 15% of the requested width and height. Notice that dy is ignored for the colormaps of type ramp since they must create a continuous color strip.

• absoluteMargins true/false, used to change the Unit of Measure of dx from percentage (when false) to a fixed number of pixels (when true).

• mx,my the margins from the border of the legends are set to the 1.5% of the total size of the legend

In conclusion, here below I am adding an image of a sample legend with all the various options at work. The request that generated it is the following:

http://localhost:8081/geoserver/wms?REQUEST=GetLegendGraphic&VERSION=1.0.0&FORMAT=image/png&WIDTH=100&HEIGHT=20&LAYER=it.geosolutions:di08031_da&LEGEND_OPTIONS=forceRule:True;dx:0.2;dy:0.2;mx:0.2;my:0.2;fontStyle:bold;borderColor:0000ff;border:true;fontColor:ff0000;fontSize:18

Do not worry if it seems like something written in ancient dead language, I am going to explain the various params here below.

Raster legends’ types¶

As you may know (well, actually you might not since I never wrote any real docs about the RasterSymbolizer work I did) GeoServer supports three types of ColorMaps:

• ramp this is what SLD 1.0 dictates, which means a linear interpolation weighted on values between the colors of the various ColorMapEntries.

• values this is an extension that allows link quantities to colors as specified by the ColorMapEntries quantities. Values not specified are translated into transparent pixels.

• classes this is an extension that allows pure classifications based on intervals created from the ColorMapEntries quantities. Values not specified are translated into transparent pixels.

Here below I am going to list various examples that use the attached styles on a rainfall floating point geotiff.

ColorMap type is VALUES¶

Refer to the SLD rainfall.sld in attachment.

ColorMap type is CLASSES¶

Refer to the SLD rainfall_classes.sld in attachment.

ColorMap type is RAMP¶

Refer to the SLD rainfall_classes.sld in attachment. Notice that the first legend shows the default border behavior while the second has been forced to draw a border for the breakpoint color of the colormap entry quantity described by the rendered text. Notice that each color element has a part that show the fixed color from the colormap entry it depicts (the lowest part of it, the one that has been outlined by the border in the second legend below) while the upper part of the element has a gradient that connects each element to the previous one to point out the fact that we are using linear interpolation.

The various control parameters and how to set them¶

I am now going to briefly explain the various parameters that we can use to control the layout and content of the legend. A request that puts all the various options is shown here:

http://localhost:8081/geoserver/wms?REQUEST=GetLegendGraphic&VERSION=1.0.0&FORMAT=image/png&WIDTH=100&HEIGHT=20&LAYER=it.geosolutions:di08031_da&LEGEND_OPTIONS=forceRule:True;dx:0.2;dy:0.2;mx:0.2;my:0.2;fontStyle:bold;borderColor:0000ff;border:true;fontColor:ff0000;fontSize:18

Let’s now examine all the interesting elements, one by one. Notice that I am not going to discuss the mechanics of the GetLegendGraphic operation, for that you may want to refer to the SLD 1.0 spec, my goal is to briefly discuss the LEGEND_OPTIONS parameter.

• forceRule (boolean) by default rules for a ColorMapEntry are not drawn to keep the legend small and compact, unless there are no labels at all. You can change this behaviour by setting this parameter to true.

• dx,dy,mx,my (double) can be used to set the margin and the buffers between elements

• border (boolean) activates or deactivates the border on the color elements in order to make the separations clearer. Notice that I decided to always have a line that would split the various color elements for the ramp type of colormap.

• borderColor (hex) allows us to set the color for the border in 0xRRGGBB format

CQL Expressions and ENV¶

If CQL expressions are used in ColorMapEntry attributes (see here) to create a dynamic color map taking values from ENV, the same ENV parameters used for GetMap can be given to GetLegendGraphic to get the desired legend entries.

Content dependent legends¶

GeoServer allows building content dependent legend, that is, legends whose contents depend on the currently displayed map. In order to support it the GetLegendGraphic call needs the following extra parameters:

• BBOX

• SRS or CRS (depending on the WMS version, SRS for 1.1.1 and CRS for 1.3.0)

• SRCWIDTH and SRCHEIGHT, the size of the reference map (width and height already have a different meaning in GetLegendGraphic)

and the following LEGEND_OPTIONS parameters:

• countMatched: adds the number of features matching the particular rule at the end of the rule label (requires visible labels to work). Applicable only to vector layers.

• hideEmptyRules: hides rules that are not matching any feature.

Other parameters can also be added to better match the GetMap request, for example, it is recommended to mirror filtering vendor parameters such as, for example, CQL_FILTER,FILTER,FEATUREID,TIME,ELEVATION.

For example, let’s assume the following layout is added to GeoServer (legend.xml to be placed in GEOSERVER_DATA_DIR/layouts):

<layout>
    <decoration type="legend" affinity="top,right" offset="0,0" size="auto"/>
</layout>

This will make a legend appear in the GetMap response. The following preview request uses the layout to embed a legend and activates feature counting in it:

http://localhost:8080/geoserver/topp/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:states&styles=&bbox=-124.73142200000001,24.955967,-66.969849,49.371735&width=768&height=330&srs=EPSG:4326&format=application/openlayers&format_options=layout:legend&legend_options=countMatched:true;fontAntiAliasing:true

The result will look as follows:

The same can be achieved using a stand-alone GetLegendGraphic request:

http://localhost:8080/geoserver/topp/wms?service=WMS&version=1.1.0&request=GetLegendGraphic&width=20&height=20&layer=topp:states&bbox=-124.73142200000001,24.955967,-66.969849,49.371735&srcwidth=768&srcheight=330&srs=EPSG:4326&format=image/png&legend_options=countMatched:true;fontAntiAliasing:true

Or hide the empty rules using a stand-alone GetLegendGraphic request:

http://localhost:8080/geoserver/topp/wms?service=WMS&version=1.1.0&request=GetLegendGraphic&width=20&height=20&layer=topp:states&bbox=-101.0028076171875,31.025390625,-96.7840576171875,32.838134765625&srcwidth=768&srcheight=330&srs=EPSG:4326&format=image/png&legend_options=countMatched:true;fontAntiAliasing:true;hideEmptyRules:true

Filters and Expressions¶

Filters are encoded using ECQL, a rule with an ElseFilter has an element “ElseFilter” set to the value “true”. Expressions are also encoded in ECQL (wrapped in []) when encountered in the style.

Symbolizers¶

• PointSymbolizer

  A point symbolizer will be represented as a series of elements containing metadata and an array of graphics symbols (see here) , these can be well known marks or external graphics. The point symbolizer also provides an “URL” element which allows a client to make a request back to GeoServer to fetch a PNG image of the point symbol.

  {"Point":     {
      "title": "title",
      "abstract": "abstract",
      "url": "http://localhost:9000/geoserver/kml/icon/capitals?0.0.0=",
      "size": "6",
      "opacity": "1.0",
      "rotation": "0.0",
      "graphics": [      {
        "mark": "circle",
        "fill": "#FFFFFF",
        "fill-opacity": "1.0",
        "stroke": "#000000",
        "stroke-width": "2",
        "stroke-opacity": "1",
        "stroke-linecap": "butt",
        "stroke-linejoin": "miter"
      }]}}
  

• LineSymbolizer

  A line symbolizer is represented as a list of metadata elements and the stroke parameters, it is possible for there to be a graphic-stroke element too.

  {"Line":     {
    "stroke": "#AA3333",
    "stroke-width": "2",
    "stroke-opacity": "1",
    "stroke-linecap": "butt",
    "stroke-linejoin": "miter"
  }}
  
  
  {"Line":       {
      "graphic-stroke":         {
        "url": "http://local-test:8080/geoserver/kml/icon/Default Styler",
        "size": "6",
        "opacity": "0.4",
        "rotation": "[(rotation*-1)]",
        "graphics": [          {
          "mark": "square",
          "fill": "#FFFF00",
          "fill-opacity": "1.0"
        }]
      },
      "stroke-opacity": "1",
      "stroke-linecap": "butt",
      "stroke-linejoin": "miter",
      "perpendicular-offset": "10"
    }}
  

• PolygonSymbolizer

  A polygon symbolizer contains stroke parameters and fill parameters.

  {"Polygon":       {
    "stroke": "#000000",
    "stroke-width": "0.5",
    "stroke-opacity": "1",
    "stroke-linecap": "butt",
    "stroke-linejoin": "miter",
    "fill": "#0099CC",
    "fill-opacity": "1.0"
  }}
  

  Or a graphic stroke and/or a graphic fill (as described above).

  {"Polygon":       {
    "graphic-stroke":         {
      "url": "http://local-test:8080/geoserver/kml/icon/Default Styler",
      "size": "6",
      "opacity": "0.4",
      "rotation": "[(rotation*-1)]",
      "graphics": [          {
        "mark": "square",
        "fill": "#FFFF00",
        "fill-opacity": "1.0"
      }]
    },
    "stroke-opacity": "1",
    "stroke-linecap": "butt",
    "stroke-linejoin": "miter",
    "graphic-fill":         {
      "url": "http://local-test:8080/geoserver/kml/icon/Default Styler",
      "size": "4",
      "opacity": "0.4",
      "rotation": "[(rotation*-1)]",
      "graphics": [          {
        "mark": "circle",
        "fill": "#FFFFFF",
        "fill-opacity": "1.0"
      }]
    }}}
  

• RasterSymbolizer

  Raster symbolizers contain a colormap with an array of entries, each entry contains a label, quantity and color element.

  {"Raster":   {
    "colormap":     {
      "entries":       [
                {
          "label": "values",
          "quantity": "0",
          "color": "#AAFFAA"
        },
                {
          "quantity": "1000",
          "color": "#00FF00"
        },
                {
          "label": "values",
          "quantity": "1200",
          "color": "#FFFF00"
        },
                {
          "label": "values",
          "quantity": "1400",
          "color": "#FF7F00"
        },
                {
          "label": "values",
          "quantity": "1600",
          "color": "#BF7F3F"
        },
                {
          "label": "values",
          "quantity": "2000",
          "color": "#000000"
        }
      ],
      "type": "ramp"
    },
    "opacity": "1.0"
  }}
  

• TextSymbolizer

  A text symbolizer contains a label expression, followed by an array of fonts and a label-placement object containing details of how the label is placed.

  {"Text":         {
          "label": "[STATE_ABBR]",
          "fonts": [          {
                  "font-family": ["Times New Roman"],
                  "font-style": "Normal",
                  "font-weight": "normal",
                  "font-size": "14"
          }],
          "label-placement":           {
                  "x-anchor": "0.5",
                  "y-anchor": "0.5",
                  "rotation": "0.0"
          }
  }}
  

Vendor Options¶

In any case where one or more vendor options is included in the symbolizer there will be a vendor-options element included in the output. This object will include one line for each vendor option.

"vendor-options": {
  "labelAllGroup": "true",
  "spaceAround": "10",
  "followLine": "true",
  "autoWrap": "50"
}