.. _visual_elements.lines:

Lines
-----

.. image:: /images/visual_elements/trajectory_lines_panel.jpg
   :width: 30%
   :align: right

.. image:: /images/scene_objects/trajectory_lines_example.gif
   :width: 30%
   :align: right

This :ref:`visual element <visual_elements>` renders continuous lines. The visual element is automatically attached to :ref:`line objects <scene_objects.lines>`
created by the :ref:`particles.modifiers.generate_trajectory_lines` modifier or the :py:attr:`DataCollection.lines.create() <ovito.data.DataCollection.lines>`
Python method.

The option :guilabel:`Rounded line ends` provides hemispherical caps at the ends of lines. Without this option, lines end with a flat face.

The option :guilabel:`Wrap lines around` folds lines leaving the periodic simulation
cell back into the cell. Note that this option can only yield correct results if the simulation cell size
does not change with time (fixed box dimensions).

The option :guilabel:`Show up to current time only` restricts rendering of lines generated by the :ref:`particles.modifiers.generate_trajectory_lines` modifier
to those parts which have already been traversed by the particles up to the current animation time. Thus, the trajectory lines will
be gradually drawn while playing the animation, as in the example animation to the right. This option may not be available for lines created via Python
using the :py:attr:`DataCollection.lines.create() <ovito.data.DataCollection.lines>` method.

Line coloring
"""""""""""""

By default, the lines are all rendered with the same uniform color. Alternatively, you
can activate the :guilabel:`Color mapping` option, which tells the visual element to visualize a local property
along the lines using a pseudo-color map. When this option is selected,
OVITO opens a separate color mapping panel, which lets you pick the source property for the pseudo-coloring
and configure the color transfer function.

The :ref:`particles.modifiers.generate_trajectory_lines` modifier allows mapping a time-varying
particle property to the generated trajectory lines, which can then be visualized using the color mapping feature.
For this, make sure to activate the :guilabel:`Sample a particle property` option in the :ref:`particles.modifiers.generate_trajectory_lines` modifier.

When creating a :py:class:`Lines <ovito.data.Lines>` data object via Python, user-defined properties can be attached to each vertex, which can be used as
basis for pseudo-color coding.

.. seealso::

   :py:class:`ovito.vis.LinesVis` (Python API)