rasters.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
  1. .. _sld_cookbook_rasters:
  2. Rasters
  3. =======
  4. Rasters are geographic data displayed in a grid. They are similar to image files such as PNG files, except that instead of each point containing visual information, each point contains geographic information in numerical form. Rasters can be thought of as a georeferenced table of numerical values.
  5. One example of a raster is a Digital Elevation Model (DEM) layer, which has elevation data encoded numerically at each georeferenced data point.
  6. .. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example.
  7. Example raster
  8. --------------
  9. The :download:`raster layer <artifacts/sld_cookbook_raster.zip>` that is used in the examples below contains elevation data for a fictional world. The data is stored in EPSG:4326 (longitude/latitude) and has a data range from 70 to 256. If rendered in grayscale, where minimum values are colored black and maximum values are colored white, the raster would look like this:
  10. .. figure:: images/raster.png
  11. :align: center
  12. *Raster file as rendered in grayscale*
  13. :download:`Download the raster shapefile <artifacts/sld_cookbook_raster.zip>`
  14. .. _sld_cookbook_raster_twocolorgradient:
  15. Two-color gradient
  16. ------------------
  17. This example shows a two-color style with green at lower elevations and brown at higher elevations.
  18. .. figure:: images/raster_twocolorgradient.png
  19. :align: center
  20. *Two-color gradient*
  21. Code
  22. ~~~~
  23. :download:`View and download the full "Two-color gradient" SLD <artifacts/raster_twocolorgradient.sld>`
  24. .. code-block:: xml
  25. :linenos:
  26. <FeatureTypeStyle>
  27. <Rule>
  28. <RasterSymbolizer>
  29. <ColorMap>
  30. <ColorMapEntry color="#008000" quantity="70" />
  31. <ColorMapEntry color="#663333" quantity="256" />
  32. </ColorMap>
  33. </RasterSymbolizer>
  34. </Rule>
  35. </FeatureTypeStyle>
  36. Details
  37. ~~~~~~~
  38. There is one ``<Rule>`` in one ``<FeatureTypeStyle>`` for this example, which is the simplest possible situation. All subsequent examples will share this characteristic. Styling of rasters is done via the ``<RasterSymbolizer>`` tag (**lines 3-8**).
  39. This example creates a smooth gradient between two colors corresponding to two elevation values. The gradient is created via the ``<ColorMap>`` on **lines 4-7**. Each entry in the ``<ColorMap>`` represents one entry or anchor in the gradient. **Line 5** sets the lower value of 70 via the ``quantity`` parameter, which is styled a dark green (``#008000``). **Line 6** sets the upper value of 256 via the ``quantity`` parameter again, which is styled a dark brown (``#663333``). All data values in between these two quantities will be linearly interpolated: a value of 163 (the midpoint between 70 and 256) will be colored as the midpoint between the two colors (in this case approximately ``#335717``, a muddy green).
  40. Transparent gradient
  41. --------------------
  42. This example creates the same two-color gradient as in the :ref:`sld_cookbook_raster_twocolorgradient` as in the example above but makes the entire layer mostly transparent by setting a 30% opacity.
  43. .. figure:: images/raster_transparentgradient.png
  44. :align: center
  45. *Transparent gradient*
  46. Code
  47. ~~~~
  48. :download:`View and download the full "Transparent gradient" SLD <artifacts/raster_transparentgradient.sld>`
  49. .. code-block:: xml
  50. :linenos:
  51. <FeatureTypeStyle>
  52. <Rule>
  53. <RasterSymbolizer>
  54. <Opacity>0.3</Opacity>
  55. <ColorMap>
  56. <ColorMapEntry color="#008000" quantity="70" />
  57. <ColorMapEntry color="#663333" quantity="256" />
  58. </ColorMap>
  59. </RasterSymbolizer>
  60. </Rule>
  61. </FeatureTypeStyle>
  62. Details
  63. ~~~~~~~
  64. This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient` example save for the addition of **line 4**, which sets the opacity of the layer to 0.3 (or 30% opaque). An opacity value of 1 means that the shape is drawn 100% opaque, while an opacity value of 0 means that the shape is rendered as completely transparent. The value of 0.3 means that the raster partially takes on the color and style of whatever is drawn beneath it. Since the background is white in this example, the colors generated from the ``<ColorMap>`` look lighter, but were the raster imposed on a dark background the resulting colors would be darker.
  65. Brightness and contrast
  66. -----------------------
  67. This example normalizes the color output and then increases the brightness by a factor of 2.
  68. .. figure:: images/raster_brightnessandcontrast.png
  69. :align: center
  70. *Brightness and contrast*
  71. Code
  72. ~~~~
  73. :download:`View and download the full "Brightness and contrast" SLD <artifacts/raster_brightnessandcontrast.sld>`
  74. .. code-block:: xml
  75. :linenos:
  76. <FeatureTypeStyle>
  77. <Rule>
  78. <RasterSymbolizer>
  79. <ContrastEnhancement>
  80. <Normalize />
  81. <GammaValue>0.5</GammaValue>
  82. </ContrastEnhancement>
  83. <ColorMap>
  84. <ColorMapEntry color="#008000" quantity="70" />
  85. <ColorMapEntry color="#663333" quantity="256" />
  86. </ColorMap>
  87. </RasterSymbolizer>
  88. </Rule>
  89. </FeatureTypeStyle>
  90. Details
  91. ~~~~~~~
  92. This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient`, save for the addition of the ``<ContrastEnhancement>`` tag on **lines 4-7**. **Line 5** normalizes the output by increasing the contrast to its maximum extent. **Line 6** then adjusts the brightness by a factor of 0.5. Since values less than 1 make the output brighter, a value of 0.5 makes the output twice as bright.
  93. As with previous examples, **lines 8-11** determine the ``<ColorMap>``, with **line 9** setting the lower bound (70) to be colored dark green (``#008000``) and **line 10** setting the upper bound (256) to be colored dark brown (``#663333``).
  94. Three-color gradient
  95. --------------------
  96. This example creates a three-color gradient in primary colors.
  97. .. figure:: images/raster_threecolorgradient.png
  98. :align: center
  99. *Three-color gradient*
  100. Code
  101. ~~~~
  102. :download:`View and download the full "Three-color gradient" SLD <artifacts/raster_threecolorgradient.sld>`
  103. .. code-block:: xml
  104. :linenos:
  105. <FeatureTypeStyle>
  106. <Rule>
  107. <RasterSymbolizer>
  108. <ColorMap>
  109. <ColorMapEntry color="#0000FF" quantity="150" />
  110. <ColorMapEntry color="#FFFF00" quantity="200" />
  111. <ColorMapEntry color="#FF0000" quantity="250" />
  112. </ColorMap>
  113. </RasterSymbolizer>
  114. </Rule>
  115. </FeatureTypeStyle>
  116. Details
  117. ~~~~~~~
  118. This example creates a three-color gradient based on a ``<ColorMap>`` with three entries on **lines 4-8**: **line 5** specifies the lower bound (150) be styled in blue (``#0000FF``), **line 6** specifies an intermediate point (200) be styled in yellow (``#FFFF00``), and **line 7** specifies the upper bound (250) be styled in red (``#FF0000``).
  119. Since our data values run between 70 and 256, some data points are not accounted for in this style. Those values below the lowest entry in the color map (the range from 70 to 149) are styled the same color as the lower bound, in this case blue. Values above the upper bound in the color map (the range from 251 to 256) are styled the same color as the upper bound, in this case red.
  120. Alpha channel
  121. -------------
  122. This example creates an "alpha channel" effect such that higher values are increasingly transparent.
  123. .. figure:: images/raster_alphachannel.png
  124. :align: center
  125. *Alpha channel*
  126. Code
  127. ~~~~
  128. :download:`View and download the full "Alpha channel" SLD <artifacts/raster_alphachannel.sld>`
  129. .. code-block:: xml
  130. :linenos:
  131. <FeatureTypeStyle>
  132. <Rule>
  133. <RasterSymbolizer>
  134. <ColorMap>
  135. <ColorMapEntry color="#008000" quantity="70" />
  136. <ColorMapEntry color="#008000" quantity="256" opacity="0"/>
  137. </ColorMap>
  138. </RasterSymbolizer>
  139. </Rule>
  140. </FeatureTypeStyle>
  141. Details
  142. ~~~~~~~
  143. An alpha channel is another way of referring to variable transparency. Much like how a gradient maps values to colors, each entry in a ``<ColorMap>`` can have a value for opacity (with the default being 1.0 or completely opaque).
  144. In this example, there is a ``<ColorMap>`` with two entries: **line 5** specifies the lower bound of 70 be colored dark green (``#008000``), while **line 6** specifies the upper bound of 256 also be colored dark green but with an opacity value of 0. This means that values of 256 will be rendered at 0% opacity (entirely transparent). Just like the gradient color, the opacity is also linearly interpolated such that a value of 163 (the midpoint between 70 and 256) is rendered at 50% opacity.
  145. Discrete colors
  146. ---------------
  147. This example shows a gradient that is not linearly interpolated but instead has values mapped precisely to one of three specific colors.
  148. .. note:: This example leverages an SLD extension in GeoServer. Discrete colors are not part of the standard SLD 1.0 specification.
  149. .. figure:: images/raster_discretecolors.png
  150. :align: center
  151. *Discrete colors*
  152. Code
  153. ~~~~
  154. :download:`View and download the full "Discrete colors" SLD <artifacts/raster_discretecolors.sld>`
  155. .. code-block:: xml
  156. :linenos:
  157. <FeatureTypeStyle>
  158. <Rule>
  159. <RasterSymbolizer>
  160. <ColorMap type="intervals">
  161. <ColorMapEntry color="#008000" quantity="150" />
  162. <ColorMapEntry color="#663333" quantity="256" />
  163. </ColorMap>
  164. </RasterSymbolizer>
  165. </Rule>
  166. </FeatureTypeStyle>
  167. Details
  168. ~~~~~~~
  169. Sometimes color bands in discrete steps are more appropriate than a color gradient. The ``type="intervals"`` parameter added to the ``<ColorMap>`` on **line 4** sets the display to output discrete colors instead of a gradient. The values in each entry correspond to the upper bound for the color
  170. band such that colors are mapped to values less than the value of one entry but greater than or equal to the next lower entry. For example, **line 5** colors all values less than 150 to dark green (``#008000``) and line 6 colors all values less than 256 but greater than or equal to 150 to dark brown (``#663333``).
  171. Many color gradient
  172. -------------------
  173. This example shows a gradient interpolated across eight different colors.
  174. .. figure:: images/raster_manycolorgradient.png
  175. :align: center
  176. *Many color gradient*
  177. Code
  178. ~~~~
  179. :download:`View and download the full "Many color gradient" SLD <artifacts/raster_manycolorgradient.sld>`
  180. .. code-block:: xml
  181. :linenos:
  182. <FeatureTypeStyle>
  183. <Rule>
  184. <RasterSymbolizer>
  185. <ColorMap>
  186. <ColorMapEntry color="#000000" quantity="95" />
  187. <ColorMapEntry color="#0000FF" quantity="110" />
  188. <ColorMapEntry color="#00FF00" quantity="135" />
  189. <ColorMapEntry color="#FF0000" quantity="160" />
  190. <ColorMapEntry color="#FF00FF" quantity="185" />
  191. <ColorMapEntry color="#FFFF00" quantity="210" />
  192. <ColorMapEntry color="#00FFFF" quantity="235" />
  193. <ColorMapEntry color="#FFFFFF" quantity="256" />
  194. </ColorMap>
  195. </RasterSymbolizer>
  196. </Rule>
  197. </FeatureTypeStyle>
  198. Details
  199. ~~~~~~~
  200. A ``<ColorMap>`` can include up to 255 ``<ColorMapEntry>`` elements.
  201. This example has eight entries (**lines 4-13**):
  202. .. list-table::
  203. :widths: 15 25 30 30
  204. * - **Entry number**
  205. - **Value**
  206. - **Color**
  207. - **RGB code**
  208. * - 1
  209. - 95
  210. - Black
  211. - ``#000000``
  212. * - 2
  213. - 110
  214. - Blue
  215. - ``#0000FF``
  216. * - 3
  217. - 135
  218. - Green
  219. - ``#00FF00``
  220. * - 4
  221. - 160
  222. - Red
  223. - ``#FF0000``
  224. * - 5
  225. - 185
  226. - Purple
  227. - ``#FF00FF``
  228. * - 6
  229. - 210
  230. - Yellow
  231. - ``#FFFF00``
  232. * - 7
  233. - 235
  234. - Cyan
  235. - ``#00FFFF``
  236. * - 8
  237. - 256
  238. - White
  239. - ``#FFFFFF``