Raster Legends Explained
Overview
This page aim to briefly describe the work that I have performed in order to support legends for raster data that draw information taken from the various bits of the SLD 1.0 RasterSymbolizer element. Recall, that up to now there was no way to create legends for raster data, therefore we have tried to fill the gap by providing an implementation of the getLegendGraphic request that would work with the ColorMap element of the SLD 1.0 RasterSymbolizer. Notice that some "debug" info about the style, like colormap type and band used are printed out as well.
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 regards, 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 continous color strip.
- mx,my the margins from the border of the legends are set to the 1.5% of the total size of the legend
Just to jump right to the conclusions (which is a bad practice I know, but no one is perfect 
), 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:
Do not worry if it seems like something written in ancient dead language, I am going to explain the various params here below. Nevertheless it is important to point out that basic info on how to create and set params can be found in this page.
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 extensions that allows link quantities to colors as specified by the ColorMapEntries quantities. Values not specified are translated into transparent pixels.
- classes this is an extensions that allows pure classifications based o 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 show the default border behavior while the second has been force to draw a border for the breakpoint color of the 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 boder in the second legend here below) while the upper part of the element has a gradient tha 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 tht we can use to control the layout and content of the legend (refer also to this page). Here below I have put a request that puts all the various options at tow
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 defaul rules for a ColorMapEntry are not drawn to keep the legend small and compact, unless there are not 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
- fontStyle (string) can be set to italic or bold to control the text style. Other combination are not allowed right now but we could implement that as well.
- fontSize (integer) allows us to set the Font size for the various text elements. Notice that default size is 12.
- border (boolean) activates or deactivates the boder on the color elements in order to make the separations cleare. 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 as explained above. Valid values are hex values withouth the leading #.
- fontColor (hex) allows us to set the color for the text of rules and labels (see above for recommendation on how to create values).