.. _helloworld_line:

*****************************
Hello World, Lines
*****************************

This page covers the basics of creating a line plot, introducing the concepts of

* instantiation of a line object
* adding the line object to a 3D axes
* line resolution
* functional mapping

.. _gen-concepts_line:

General Concepts
=========================================================================================

For S3Dlib, a *Line* is defined as a continuous sequence of linear segments with a common
vertex at joining segments (a line can contain a single segment with two vertices).

Throughout this tutorial and all the example plots, the construction and display of
lines consist of three basic steps.

1. Define coordinate and coloring, either explicitly or usings functions.
2. Instantiate line objects and apply mapping methods.
3. Setup the Matplotlib figure and axes.

These three steps are similar to those described in the :ref:`helloworld` tutorial for surfaces.

.. _hello-default_line:

Default 3D Line Collection Base Class
=========================================================================================

The base class for producing a line object is::

    s3d.ColorLine3DCollection(vertexCoor, segmIndices)

This constructor produces a collection of lines or for a single line, the collection
is of size one.
The *vertexCoor* is a list (or array-like) of x,y,z coordinates ( list or array of 3 floats).
The *segmIndices* argument is the vertex indices for the lines, which is a N list of lines, each line
being a list of M segments.

The following is the script for producing a collection of two lines.

.. literalinclude:: source/tut_line_base.py
   :language: python
   :emphasize-lines: 11

which produces the following plot:

.. image:: images/line_base1.png

For a single line using the same vertices, only one line is defined in the collection by 
un-commenting the highlighted code, producing

.. image:: images/line_base2.png


The line to set the axis limits::

    ax.set(xlim=(-1,1), ylim=(-1,1), zlim=(-1,1))

is generally always inserted, over-riding the Matplotlib default axis limits.  However,
the objects can be used to auto-scale the *axes* using::

    s3d.auto_scale(axes,*obj3d)

where *obj3d* are the S3Dlib objects, which, for this case is only the line collection object.
Auto scaling can often produce plots where the x, y, and z axes are scaled differently.  However,
using this function can be convenient when the object 3D sizes are unknown prior to plotting.


.. _hello_line-0:

Single Segmented Line
=========================================================================================

When a single line object may be constructed from a sequence of vertices, the object
can be constructed without the segment indices list.  For this case, use::

    s3d.SegmentLine(vertexCoor)

A simple example of using just vertex coordinates is that of using a sequence of 
random walk 3D coordinate locations as shown in the following figure

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

which was produced using the following code.  Note that the *auto_scale* method was used
since the range of the result is initially unknown.

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


.. _hello_line-1:

Parametric Line
=========================================================================================

A line object with Cartesian coordinates defined by a single parameter is created using
the following code::

    s3d.ParametricLine(rez,operation)

A ParametricLine object is a sequence of segments, the number be controlled by the *rez* argument.
The *operation* is the name of a parametric function having one argument in the domain 0 to 1 and returning
a set of 3 X N Cartesian coordinates.

Using the *rez* argument, each segment is recursively subdivided into two segments.  The number of 
recursions (line resolution) is controlled by the *rez*.

Using the Matplotlib
`Parametric Curve <https://matplotlib.org/stable/gallery/mplot3d/lines3d.html#sphx-glr-gallery-mplot3d-lines3d-py>`_
example, for a rez of 6:

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

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

The following figure shows the progressions
to higher resolutions for this example of a ParametricLine, from rez=3 to rez=5

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



.. _hello_line-fade:

Line Fade()
=========================================================================================

To enhance the line visualization in 3D, a sense of depth for the line can be applied to
the line transparency using the line method::

    line.fade(depth,elev,azim)

where *depth* is the minimum color alpha transparency of a line segment, which ranges
from 0 to 1. The default value for *depth* is 0.  When applied, the segment alphas will
vary from 1 to the set *depth* aligned from the front to back. Alignment is based on the axis
view position set by the *elev* and *azim*, in degrees.  Then default values are
30 and -60 for  *elev* and *azim*, respectively.

Using the default fade for the previous examples results in the following visualizations of the lines:

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




.. _hello_line-2:

Names, Parameterization and Composites
=========================================================================================

In a similar manner to surface objects, line objects may be added together to form one
single ColorLine3DCollection object by simply using the + operator.  Also shown in the
surface  :ref:`param_function`  tutorial, composites object are easily formed by addition,
illustrating the parameters controlling the line geometry.

Each of the Line constructors has a named argument *'name='*, which can also be accessed with
setters and getters.  As a default, *name* is an empty string. However, for the ParametricLine
object, *name* will default to the name of the 'operation' function, if not a lambda function.

When names are assigned, the axes 'legend' will use the line names.  The colors displayed
in the line legend will be affected by the line shading.  When lines are
added together to form a composite line, the resulting line has no name until the line *name*
is assigned.

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

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



.. _hello_line-3:

Line Properties
=========================================================================================


Vertex and segment center coordinates of line objects are accessed using line properties as::

    x,y,z = line.vertices

and::

    x,y,z = line.segmentcenters

Using the parametric line example, line vertices and segment centers are displayed by using
a scatter plot as::

    x,y,z = line.vertices
    X,Y,Z = line.segmentcenters
    ax.scatter(x,y,z,label='vertices',color='b')
    ax.scatter(X,Y,Z,label="centers", color='r')
    ax.legend()

with the result shown below for a rez of 5.

.. image:: images/line_vertices.png