.. _cmap_segment_tut:

****************************************
Color Mapped Line Segments
****************************************

Line object color can be defined using color maps based on three line methods for

* segment orientation
* segment sequence
* Cartesian coordinate segment position

Color Mapping from Orientation 
=========================================================================================

Segment color can be based on the segment orientation using the line object method::

    line.map_cmap_from_direction( cmap, direction=None, isAbs=False )

The *cmap* argument is a color map or registered color map name. The *direction* argument
is a 3D array in x,y,z coordinates.  The value used for the color map index is the dot product
of the *direction* with the progressive sequence direction.
The *isAbs* is True if the sign of the dot product is ignored.
If no arguments are provided the default values
for cmap, direction are *viridis*, the Matplot default, and [1,0,1], respectively.

.. image:: images/cmap_line2.png
   :class: sphx-glr-single-img

which was generated by the following script.  Note that the linewidth was set to 5
in the constructors (*lw=5*) to emphasize the coloring.

.. literalinclude:: source/tut_cmap_line2.py
   :language: python

This cmap method is analogous to the surface normal mapping where, for a line,
orientation is used for mapping. As with surfaces, the 3D visualization of lines may
be enhanced by shading using the method::

    line.shade( depth, direction, contrast )

where the method arguments are described in the :ref:`cmap_normals_tut` tutorial or
the :ref:`surface_shading` guide.
These two methods will produce similar results for visualization as shown in the 
following figure. 

.. image:: images/col_shade2.png
   :class: sphx-glr-single-img


.. literalinclude:: source/tut_col_shade2.py
   :language: python


Color Mapping Using Segment Sequence
=========================================================================================

Colormaps are applied from the start to end to the line segments using::

    line.map_cmap_from_sequence(cmap)

The Matplot default *viridis* colormap is used if no
color map argument, *cmap*, is specified.
When applied to the parametric line example, the resulting line plot is

.. image:: images/line_sequence.png
   :class: sphx-glr-single-img


Color Mapping Using a Function
=========================================================================================

Line color can be defined from function values that are mapped to colors using colormaps
by calling the line object method::

    line.map_cmap_from_op( operation, cmap )

The *op* argument is a function with coordinate arguments and returning a single
value.  The  *cmap* argument is a color map or registered color map name.  Returned
function values at segment coordinates are normalized and colors mapped from the colormap.

For example, defining the functional operation as:

.. literalinclude:: source/tut_line_color.py
   :language: python
   :lines: 7-10

for the parametric line object mapped using this function is

.. image:: images/line_color.png
   :class: sphx-glr-single-img


Influence of Line Rez
=========================================================================================

Since color mapping is applied to each segment, the line segment sizes
control the smoothness of the color variations.

For parametric lines, the segment size is controlled by the *rez* argument of the
constructor.  The previous sequential cmap example for different rez are shown below.

.. image:: images/line_shred_rez_2.png
   :class: sphx-glr-single-img

In addition, the line segments can be increased along each initial segment using the method::

    line.shred(rez)

Where  *rez* is the recursive number of doubling the line segments.
For the simple four segment line color mapped in the z-direction, the effect of applying
this method for various rez values is

.. image:: images/line_shred_rez_1.png
   :class: sphx-glr-single-img

This shred method can be applied to any line object. For the parametric line example,  
applying colormapping after applying the *shred* method is shown below. 

.. image:: images/line_shred_rez_3.png
   :class: sphx-glr-single-img

The value of the *rez* in the line constructor influences the smoothness of the geometry.  Further
applying *shred* provides a smoothness in the colormapping.