Text Symbolizer
===============

Renders text for features.

.. currentmodule:: shelley.symbolizers

.. class:: TextSymbolizer(property_name, face_name, size, color='black', placement='point', halo_radius=None, halo_color='white')

   :param property_name: name of the features property whose value will be used as text
   :param face_name: font name
   :param size: size of font
   :param color: color of line, defaults to black
   :type color: string or Color object
   :param placement: 'point' or 'line', defaults to 'point'
   :param halo_radius: increment in size of font used for halo, no halo is shown if None
   :param halo_color: color of line, defaults to white
   :type halo_color: string or Color object

.. doctest::
   :hide:

    >>> from shelley import Color, Box
    >>> from shelley.symbolizers import TextSymbolizer, LineSymbolizer, PolygonSymbolizer
    >>> from shelley.datasources.simple import Geometry, Feature
    >>> import doc_utils

Placement
---------

Point geometries
^^^^^^^^^^^^^^^^

For features with point geometries the text symbolizer places the text centered
both vertically and horizontally at the point

.. doctest::

    >>> symbolizer = TextSymbolizer(property_name='title', face_name='Sans', size=10, color=Color.name('red'))

.. doctest::

    >>> point_feature = Feature(geometry=Geometry(type='Point', coordinates=[5, 5]),
    ...                         properties={'title': 'Primary Peak'})

Need to add a point symbolizer as well to see placement

.. doctest::
   :hide:

    >>> bounds = Box(min_x=0, min_y=0, max_x=10, max_y=10)
    >>> doc_utils.render_feature([symbolizer], point_feature, 'text_point.png', bounds, 100, 100)

.. image:: .scratch/text_point.png


Line geometries
^^^^^^^^^^^^^^^

For line geometries the text can be placed at the center of the line, 
placement "point", or along the line, placement "line".

The default placement is "point".

.. doctest::

    >>> line_feature = Feature(geometry=Geometry(type='LineString', coordinates=[[1, 1], [9, 9]]),
    ...                        properties={'title': 'Simple Street'})

.. doctest::
   :hide:

    >>> line_sym = LineSymbolizer(color=Color.name('grey'), width=20)
    >>> doc_utils.render_feature([line_sym, symbolizer], line_feature, 'text_line_placement_point.png', bounds, 100, 100)

.. image:: .scratch/text_line_placement_point.png

.. doctest::

    >>> symbolizer.placement = 'line'

.. doctest::
   :hide:

    >>> doc_utils.render_feature([line_sym, symbolizer], line_feature, 'text_line_placement_line.png', bounds, 100, 100)

.. image:: .scratch/text_line_placement_line.png

For lines with segments the text follows the angle of the line

.. doctest::
   :hide:

    >>> segmented_feature = Feature(geometry=Geometry(type='LineString', coordinates=[[1, 1], [3, 6], [9, 9]]),
    ...                             properties={'title': 'Simple street'})
    >>> doc_utils.render_feature([line_sym, symbolizer], segmented_feature, 'text_segmented_line.png', bounds, 100, 100)

.. image:: .scratch/text_segmented_line.png

Polygon geometries
^^^^^^^^^^^^^^^^^^

.. doctest::

    >>> polygon_feature = Feature(
    ...     geometry=Geometry(type='Polygon',
    ...                       coordinates=[[[1, 1], [5, 8], [9, 9], [5, 2]]]),
    ...     properties={'title': 'Lake Diamond'}
    ... )

With placement 'point' the text is placed at the centroid of the polygon.

    >>> symbolizer.placement = 'point'

.. doctest::
   :hide:

    >>> poly_sym = PolygonSymbolizer(color=Color.name('grey'))
    >>> doc_utils.render_feature([poly_sym, symbolizer], polygon_feature, 'text_polygon_placement_point.png', bounds, 100, 100)

.. image:: .scratch/text_polygon_placement_point.png

TODO: rendering a polygon with placement 'line'

    >>> symbolizer.placement = 'line'

.. doctest::
   :hide:

    >>> doc_utils.render_feature([poly_sym, symbolizer], polygon_feature, 'text_polygon_placement_line.png', bounds, 100, 100)

.. image:: .scratch/text_polygon_placement_line.png

Halo
----

If a halo attribute is specified the text is drawn twice. Once with the line 
width of the text increased by the halo radius and in the halo colour and
again with normal line width and colour.

.. doctest::

    >>> symbolizer = TextSymbolizer(property_name='title', face_name='Sans', size=10, color=Color.name('red'), halo_radius=1, halo_color=Color.name('black'))

.. doctest::
   :hide:

    >>> symbolizer.halo_radius = 0
    >>> doc_utils.render_feature([symbolizer], point_feature, 'text_halo1.png', bounds, 100, 100)
    >>> symbolizer.halo_radius = 2.5
    >>> doc_utils.render_feature([symbolizer], point_feature, 'text_halo2.png', bounds, 100, 100)
    >>> symbolizer.halo_radius = 5
    >>> doc_utils.render_feature([symbolizer], point_feature, 'text_halo3.png', bounds, 100, 100)


======= ================================
0       .. image:: .scratch/text_halo1.png
2.5     .. image:: .scratch/text_halo2.png
5       .. image:: .scratch/text_halo3.png
======= ================================

An halo example with line placement

.. doctest::
   :hide:

    >>> symbolizer.halo_radius = 2
    >>> symbolizer.placement = 'line'
    >>> doc_utils.render_feature([line_sym, symbolizer], line_feature, 'text_halo.png', bounds, 100, 100)

.. image:: .scratch/text_halo.png