Symbology Encoding
^^^^^^^^^^^^^^^^^^

The GeoTools rendering process is controlled styling information that you provide. The data structures we use to describe styling are based on the Style Layer Descriptor (SLD) and Symbology Encoding (SE) specifications provided by the OGC.

These specifications define an XML document you can use to save and load your styles on disk, we use the same data structure internally to control the rendering process.

References:

* :doc:`style </tutorial/map/style>` (tutorial)
* :doc:`gt-api sld <../api/sld>`
* :doc:`gt-render style <../render/index>`
* http://www.opengeospatial.org/standards/sld (style layer descriptor)
* http://www.opengeospatial.org/standards/symbol (symbology encoding)

FeatureTypeStyle
^^^^^^^^^^^^^^^^

The Symbology Encoding specification provides us the FeatureTypeStyle which is focused on how to draw features in a manner similar to CSS.


.. image:: /images/se.PNG

The key concepts for symbology encoding are:

* FeatureTypeStyle: captures the recipe for drawing a specific kind of feature
* Rule: used to select features for drawing, using a list of symbolizers to control the actual drawing process.
* Symbolizer

Symbolizer
''''''''''

A Symbolizer defines how a geometry is to be rendered in terms of pixels; selecting the geometry
from the feature, and drawing using the information provided here.


.. image:: /images/symbolizer.PNG

.. note:: The Symbology Encoding standard does its best to render something in all cases; thus a PointSymbolizer applied to a Polygon will draw a point in the centre, more interestingly a LineSymbolizer applied to a point will draw a small line (of a fixed size) at the indicated location.

The available symbolizers are:

* TextSymbolizer
  
  Used to control the labelling system; labels are generated by TextSymbolizers and
  thrown into the rendering engine which detect overlaps, sorts things out according
  to priorities you have defined and decides on a final label placement.

* LineSymbolizer
  
  Used to control how lines (or edges) are drawn.

* PolygonSymbolizer
  
  Used to control how solid shapes are drawn.

* PointSymbolizer
  
  Used to draw a point location, the actual graphic drawn is referred to as a Mark with the option to use
  some well known marks (circle, square etc..) or your own external graphics such as PNG icons.

* RasterSymbolizer
  
  Used to control the rendering of raster data with full "color map" control.

Here is a quick example showing the creation of a PointSymbolizer:
  
.. literalinclude:: /../src/main/java/org/geotools/opengis/StyleExamples.java
   :language: java
   :start-after: // styleFactoryExample start
   :end-before: // styleFactoryExample end

Fill
''''

Fill is used both to fill a polygon, and also when creating greater control over Mark appearance (where it can be used to define the interior of a Mark).


.. image:: /images/fill.PNG

Stroke
''''''

In a similar fashion Stroke is used to render edges (either polygon edges, linestrings or the outside edge of a Mark).

.. image:: /images/stroke.PNG

Graphic
'''''''

The idea of a Graphic is used in a number of contexts when drawing:

* Graphic: As an "icon" when rendering a point location
* GraphicFilter: As a pattern when filling an area
* GraphicStroke: As a pattern when drawing along a line
* GraphicLegend: As a an entry in a legend (GeoTools does not use this one yet)

Although the symbology encoding specification defines the above destinct kinds of Graphic the GeoTools
library does not distinguish between them at this time.


.. image:: /images/graphic.PNG

The interesting part is the list of **GraphicalSymbol**. This list is considered in order, with 
the rendering engine selecting the first format it is able to draw allowing you to order your highest quality
**ExternalGraphic** formats first (such as SVG or a true type font) and moving on to lower quality choices such as PNG files and
finally ending with a fallback **Mark**.

* ExternalGraphic
  
  In addition to allowing you the use of svg and image formats there is the interesting use of *inline content* in the form of
  a Java Icon allowing you greater control. You also have a chance to apply colour replacements (which cab be used to render a
  black and white image into a set colour as needed.

* Mark
  
  Check the javadocs for the list of well known names (such as "circle" or "square"). Of interest is the use of 
  an **ExternalMark** in which the mark index can be used to refer to a specific character entry in a true type font.

StyleVisitor
^^^^^^^^^^^^

A style visitor is defined allowing you to traverse the style data structure. For details on the use of a visitor please review
:doc:`filter` on the subject.

StyleFactory
^^^^^^^^^^^^

Objects for symbology encoding are created using a StyleFactory::

    org.opengis.style.StyleFactory sf = CommonFactoryFinder.getStyleFactory(null);
    FilterFactory2 ff = CommonFactoryFinder.getFilterFactory2(null);
    
    Fill fill = sf.fill(null, ff.literal(Color.BLUE), ff.literal(1.0));