Line Symbolizer
===============

Renders line-like geometries as lines. Polygon geometries will be rendered as
closed lines. Points are ignored.

.. currentmodule:: shelley.symbolizers

.. class:: LineSymbolizer(color='black', width=1, cap='butt', join='miter', dash=None)

    :param color: color of line
    :type color: string or Color object
    :param width: width of line
    :type width: float pixels
    :param cap: style of the line endings
    :type cap: string
    :param join: style of any line kinks
    :type join: string
    :param dash: list of alternate space and dash lengths in a dashed line
    :type dash: list

.. doctest::
    :hide:

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

Color
-----

::

    LineSymbolizer(color=Color(255, 0, 0))

.. doctest::
    :hide:

    >>> bounds = Box(0, 0, 10, 10)
    >>> geometry = Geometry(
    ...     type='LineString',
    ...     coordinates=[[2, 2], [4, 8], [6, 2], [8, 8]]
    ... )
    >>> s = LineSymbolizer(color=Color(255, 0, 0))
    >>> doc_utils.render_geometry(s, geometry, 'line_color.png', bounds, 100, 100)

.. image:: .scratch/line_color.png

Width
-----

::

    LineSymbolizer(width=0.5)

.. doctest::
    :hide:

    >>> s = LineSymbolizer(width=0.5)
    >>> doc_utils.render_geometry(s, geometry, 'line_width1.png', bounds, 100, 100)
    >>> s.width = 5
    >>> doc_utils.render_geometry(s, geometry, 'line_width2.png', bounds, 100, 100)
    >>> s.width = 25
    >>> doc_utils.render_geometry(s, geometry, 'line_width3.png', bounds, 100, 100)

======= =================================
0.5     .. image:: .scratch/line_width1.png
5       .. image:: .scratch/line_width2.png
25      .. image:: .scratch/line_width3.png
======= =================================

Cap
---

::

    LineSymbolizer(cap='round')

.. doctest::
    :hide:

    >>> s = LineSymbolizer(width=15, cap='round')
    >>> doc_utils.render_geometry(s, geometry, 'line_cap1.png', bounds, 100, 100)
    >>> s.cap = 'butt'
    >>> doc_utils.render_geometry(s, geometry, 'line_cap2.png', bounds, 100, 100)
    >>> s.cap = 'square'
    >>> doc_utils.render_geometry(s, geometry, 'line_cap3.png', bounds, 100, 100)

======== ===============================
'round'  .. image:: .scratch/line_cap1.png
'butt'   .. image:: .scratch/line_cap2.png
'square' .. image:: .scratch/line_cap3.png
======== ===============================

Join
----

::

    LineSymbolizer(join='miter')

.. doctest::
    :hide:

    >>> s = LineSymbolizer(width=15, join='miter')
    >>> doc_utils.render_geometry(s, geometry, 'line_join1.png', bounds, 100, 100)
    >>> s.join = 'round'
    >>> doc_utils.render_geometry(s, geometry, 'line_join2.png', bounds, 100, 100)
    >>> s.join = 'bevel'
    >>> doc_utils.render_geometry(s, geometry, 'line_join3.png', bounds, 100, 100)

======= ================================
'miter' .. image:: .scratch/line_join1.png
'round' .. image:: .scratch/line_join2.png
'bevel' .. image:: .scratch/line_join3.png
======= ================================

Dash
----

::

    LineSymbolizer(dash=[1, 1])

.. doctest::
    :hide:

    >>> s = LineSymbolizer(dash=[1, 1])
    >>> doc_utils.render_geometry(s, geometry, 'line_dash1.png', bounds, 100, 100)
    >>> s.dash = [1, 4]
    >>> doc_utils.render_geometry(s, geometry, 'line_dash2.png', bounds, 100, 100)
    >>> s.dash = [10, 5, 1]
    >>> doc_utils.render_geometry(s, geometry, 'line_dash3.png', bounds, 100, 100)

========== ================================
[1, 1]     .. image:: .scratch/line_dash1.png
[1, 4]     .. image:: .scratch/line_dash2.png
[10, 5, 1] .. image:: .scratch/line_dash3.png
========== ================================