.. _usage.modification_pipeline:

Pipeline concept
================

OVITO's workflow is based on a *data pipeline* concept, where a sequence of operations (*modifiers*) is
applied to the imported simulation dataset. These operations process the data step by step,
and the resulting output is displayed on the screen:

.. image:: /images/usage/pipeline/pipeline_example.*
   :width: 100%

OVITO provides a :ref:`wide range of modifiers <particles.modifiers>`, each performing tasks such as selection,
coloring, analysis, or filtering of particle structures. By combining these basic building blocks in a pipeline,
you can customize the visualization and analysis of your simulation data to fit your needs.

Benefits of the pipeline approach
---------------------------------

A key advantage of the pipeline system is its *non-destructive* nature. Any modifications you apply remain
adjustable — modifiers can be edited, reordered, added, or removed at any time.
The original dataset remains unchanged, allowing for flexible experimentation.

Whenever you modify the pipeline, OVITO automatically recalculates the output and
updates the visualization in real time. This dynamic approach is similar to workflows in
modern photo editing and 3D modeling software.

Additionally, once you've set up a processing pipeline that suits your needs,
you can apply it to multiple structures, enabling efficient batch processing of
simulation trajectories.

.. _usage.modification_pipeline.pipeline_listbox:

Pipeline editor
---------------

The *pipeline editor* is the main interface for managing data processing in OVITO.
It displays the current pipeline and allows you to:

  - Insert new modifiers
  - Edit modifier parameters
  - Reorder or remove modifiers

.. image:: /images/usage/pipeline/pipeline_editor.*
  :width: 40%
  :align: right

The editor consists of three sections:

Visual elements
  Graphical representations of data generated by the pipeline (discussed below)

Modifications
  The current sequence of modifiers in the pipeline

Data source
  The input data (typically an external simulation file)

When you first import a dataset, the pipeline contains no modifiers yet, and the *Modifications* section is hidden.
Selecting an item in the pipeline editor opens a corresponding parameter panel where you can adjust its settings.

To add a modifier, use the :guilabel:`Add modification...` widget above the pipeline editor.
The new modifier is inserted above the currently selected pipeline item.
Note that the pipeline follows a *bottom-up* order — modifiers at the bottom act first on the data.
For example, in the screenshot, the pipeline first computes displacement vectors,
then applies color coding, and finally slices the dataset.

Modifiers can be temporarily disabled using the checkbox next to them.
To permanently remove a modifier, use the *Delete Modifier* button in the toolbar.
You can reorder modifiers in the pipeline using drag-and-drop or the up/down arrow buttons.

Keep in mind that the order in which modifiers are applied to the data matters in many cases.

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

.. _usage.modification_pipeline.display:

Visual elements
---------------

The pipeline processes various types of data, such as particle positions, bond topology, and simulation cell geometry.
Some modifiers add new data, like displacement vectors computed from particle trajectories.

The processed data must then be visually represented in OVITO's viewports. This is handled by *visual elements*.

:ref:`Visual elements <visual_elements>` are automatically generated by the pipeline and appear in the top section
of the pipeline editor. Each element has adjustable settings for controlling its appearance. You can toggle visibility
in the viewports and rendered images using the checkbox next to each visual element.

.. _usage.modification_particle_selection:

Transient pipeline states and particle selections
-------------------------------------------------

Some modifiers, such as :ref:`particles.modifiers.delete_selected`, operate only on selected particles or bonds.
Selection state is determined by the ``Selection`` property associated with particles (see :ref:`previous section <usage.particle_properties>`),
and several modifiers allow you to create a new selection based on different criteria.

Selection occurs dynamically within the pipeline. A modifier first selects a subset of particles,
and subsequent modifiers can act on that selection. The selection persists until another modifier replaces
it further down the pipeline.

This approach enables sequential operations on different particle groups. For example:

  1. Use the :ref:`particles.modifiers.select_particle_type` modifier to select a specific type of particles.
  2. Apply the :ref:`particles.modifiers.assign_color` modifier to color them.
  3. Select another particle type using a second :ref:`particles.modifiers.select_particle_type` modifier.
  4. Assign a different color to the new selection using another :ref:`particles.modifiers.assign_color` modifier.

Since visualization reflects only the final pipeline output, the interactive viewports show the *final* selection state of
particles (highlighted in red). To inspect intermediate stages (transient pipeline states), you can temporarily disable
subsequent modifiers in the pipeline editor.
