.. _particles.modifiers.generate_trajectory_lines:

Generate trajectory lines
-------------------------

.. image:: /images/modifiers/generate_trajectory_lines_panel.jpg
  :width: 30%
  :align: right

This modifier produces a set of continuous lines by sampling the particle positions along the loaded simulation trajectory.
It can be used to visualize the trajectories of motion of particles in a static image.

The modifier automatically reads in all simulation frames one by one, sampling the particle positions to produce the trajectory lines.
As part of this process, all upstream modifiers in the data pipeline (if any) get computed for each sampled trajectory frame.
The generated :ref:`scene_objects.lines` are kept in memory, and they will be automatically regenerated whenever you change
the upstream pipeline in some way.

.. image:: /images/modifiers/flow_trajectory_example.gif
  :width: 35%

This demo animation shows a system of Lennard-Jones particles flowing around two obstacles.
The paths of motion of the red marker particles have been visualized using trajectory lines generated by the modifier.
The option :guilabel:`Show up to current time only` of the :ref:`visual_elements.lines` visual element restricts
the rendering of the trajectories to those sections already swept by the particles up to the current animation frame.
Thus, the lines appear to be traced by the moving particles.

You can choose between generating the trajectory lines either for all particles in the system or just a subset of the particles.
For the latter, you first have to insert a modifier to define a particle selection. The trajectory lines will
then be generated just for the selected particles.

.. note::

  The particle selection is taken from the initial frame of the trajectory range, not the current frame.
  In other words, the trajectory lines are always generated for a fixed set of particles --- even if the selection
  changes dynamically in each frame. If you want to show the trajectory lines of different particles in different
  frames, you have to first generate lines for *all* particles and then dynamically filter (delete) individual lines again.

Keep in mind that generating and visualizing trajectory lines for simulations with a large number
of particles and/or timesteps can be prohibitively expensive in terms of required memory.
Thus, it typically is a good idea to restrict the generation of trajectory lines to a small group of particles of interest.

.. seealso:: :ref:`tutorials.marker_particles`

Sampling a particle property along the trajectories
"""""""""""""""""""""""""""""""""""""""""""""""""""

The modifier has an option to transfer a varying input property of the particles onto the generated trajectory lines. In other words, the time-dependent particle property
becomes a location-dependent property of the generated trajectory lines, making it available for visualizing the variation of the quantity along the motion path of the particles.
Here, for example, the instantaneous velocity of the particle (property ``Velocity Magnitude``) has been sampled and transferred to the trajectory line. The property values along
the trajectory line were then visualized using the color mapping option of the :ref:`visual_elements.lines` visual element:

.. figure:: /images/modifiers/generate_trajectories_coloring_example.jpg
  :figwidth: 50%

  Trajectory of a diffusing Lithium atom. Local line coloring indicates the atom's instantaneous velocity magnitude.

Periodic boundary conditions
""""""""""""""""""""""""""""

Molecular dynamics codes that implement periodic boundary conditions (PBC) typically fold particles back into the box
when they cross a periodic boundary of the simulation box. Thus, the time-dependent particle coordinates represent
discontinuous trajectory paths. The option :guilabel:`Unwrap trajectories` of the modifier allows you to
reconstruct continuous trajectory lines from these "wrapped" (i.e., discontinuous) particle coordinates.

When :guilabel:`Unwrap trajectories` is active, the modifier uses the `minimum image convention <https://en.wikipedia.org/wiki/Periodic_boundary_conditions#Practical_implementation:_continuity_and_the_minimum_image_convention>`__ to detect crossings of periodic box boundaries
and "unwraps" the trajectory lines to make them continuous. The option is active by default, but you can turn it off in case
you are working with MD trajectory data that is already in an "unwrapped" form.

Furthermore, note that the :ref:`visual_elements.lines` visual element (see lower panel)
provides the display option :guilabel:`Wrap lines around`. This option has a reverse effect:
The continuous trajectory lines computed by the modifier are folded back into the simulation box during rendering.
A trajectory will then appear as a set of separate line segments when it crosses a periodic simulation box boundary.

Note that unwrapping or unfolding trajectory lines correctly is generally possible only if the simulation box does not change,
i.e., when the periodicity length remains constant throughout a simulation. If this is not the case, unwrapped trajectory lines will typically
show artifacts, in particular if they are folded back into the current simulation cell later on during rendering,
because it is impossible to produce a representation that is consistent with both the static trajectory lines and the
dynamically changing simulation box.

.. seealso::

  :py:class:`ovito.modifiers.GenerateTrajectoryLinesModifier` (Python API)
