<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="usage.modification_pipeline" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Modification pipeline</title>

  <para>
    The central workflow concept of OVITO is the so-called <emphasis>modification pipeline</emphasis>. 
    It is a user-defined sequence of data manipulation operations (<emphasis>modifiers</emphasis>)
    which have been applied to the simulation data. The results of that processing pipeline are displayed on screen. 
    OVITO provides <link linkend="particles.modifiers">various modifier types</link>, each performing a specific 
    basic task such as selecting, coloring, analyzing, or deleting particles.
    By combining these simple building blocks in a modification pipeline,
    the user can visualize and analyze the simulation data in a very flexible way.
     <screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/pipeline_example.png" format="png" />
     </imageobject></mediaobject></screenshot>
  </para> 
  <para>
    This data pipeline architecture make it possible for you to retroactively change, delete, or amend applied 
    editing actions. The program keeps a copy of the original simulation data in memory and, in addition, the complete list 
    of modifiers applied during the program session. OVITO lets you 
    change parameters of existing data operations, remove operations, or inserting new operations at 
    arbitrary positions in the modification sequence. Upon any such change, the program immediately recalculates the 
    effect and updates the realtime viewports to display the results. This type of non-destructive workflow can also 
    be found in modern photo editing, 3D computer graphics, or scientific data analysis programs from other fields. 
    In OVITO this approach allows you to combine various basic data operations (e.g. for selecting, filtering, transforming, 
    or analyzing particles) to accomplish very complex analysis and visualization tasks.
  </para>

  <simplesect xml:id="usage.modification_pipeline.pipeline_listbox">
    <title>The pipeline editor</title>
    <para>
	    <figure><title>The modification pipeline editor</title><screenshot><mediaobject><imageobject>
	       <imagedata fileref="images/command_panel/pipeline_editor.png" format="PNG" />
	    </imageobject></mediaobject></screenshot></figure>
       The pipeline editor, shown in the screenshot on the right, is the central place where you apply modifiers
       to the simulation data. It displays the current modification pipeline and lets you insert new modifiers, 
       reorder them, or edit their parameters.
    </para>
    <para>   
       After importing a new simulation file in OVITO, the modification pipeline is initially empty, i.e, 
       the imported data is displayed as is. The pipeline editor already contains two sections labeled <guilabel>Display</guilabel> and <guilabel>Input</guilabel>, 
       which are always present. The <guilabel>Display</guilabel> section lists the visualization elements that are currently displayed
       in the viewports, e.g. the simulation box and the particles. If you select an element in the pipeline editor, 
       a corresponding parameter panel is opened below the editor, which allows you to change the settings for the selected element.
    </para>
    <para>
       Elements under the <guilabel>Input</guilabel> section represent the data imported from an external file, which enter the modification
       pipeline. More information will be given below.
    </para>
    <para>
       Above the pipeline editor you find a drop-down box labeled <guilabel>"Add modification..."</guilabel>, which lists the 
       <link linkend="particles.modifiers">available modifiers</link> that can be applied to the data. 
       Picking an entry from that box inserts a new modifier into the modification pipeline. The new modifier 
       will be inserted right above the currently selected pipeline item. Note that the modification pipeline is 
       displayed in bottom-up order as indicated in the screenshot. That means the data source is located at the bottom, 
       and the modifier at the top of the list is always executed last.
    </para>
    <para>
       You can temporarily disable individual modifiers in the modification pipeline by unchecking the box next to them. 
       To permanently remove a modifier from the pipeline, use the <emphasis>Delete Modifier</emphasis> button in the toolbar on the right. 
       The up and down arrow buttons can be used to change the order of modifiers in the pipeline, or you can 
       drag and drop modifiers directly within the list to rearrange them.
    </para>
  </simplesect>

  <simplesect xml:id="usage.modification_pipeline.input">
    <title>The input section</title>
    <para>
      The last section in the pipeline editor, which is labeled <guilabel>Input</guilabel>, represents the data source of the modification pipeline, i.e. the external simulation file.
      Selecting the filename entry opens a <link linkend="scene_objects.file_source">panel</link> in the area below the pipeline editor that 
      shows information regarding the loaded file and allows you to replace the input of the modification pipeline with data from a different file. 
    </para>
    <para>
      Depending on the contents of the loaded input file, the <guilabel>Input</guilabel> section lists additional 
      sub-entries for various parts of the input dataset such as the simulation cell and the list of 
      particle types.
    </para>
  </simplesect>

  <simplesect xml:id="usage.modification_pipeline.display">
    <title>Display objects</title>
    <para>
      So-called <link linkend="display_objects">display objects</link> are responsible for rendering the processed data that
      leaves the modification pipeline. The <guilabel>Display</guilabel> section of the pipeline editor lists these display 
      objects. Particles, for example, are rendered by the <link linkend="display_objects.particles">Particles display object</link>, 
      which provides additional settings that allow you to control the appearance of particles. There's also a display object 
      for the simulation cell, which allows you to change settings like the cell border color. If you add certain modifiers to 
      the pipeline, for example the <link linkend="particles.modifiers.create_bonds">Create Bonds</link> modifier, you may 
      notice that additional entries appear under the <guilabel>Display</guilabel> section of the pipeline editor. 
      That is because these modifiers produce new data elements and inject them into the modification pipeline.
      You can find the list of supported display objects <link linkend="display_objects">here</link>. 
    </para>
    <para>
      You can hide individual elements by unchecking the corresponding box in the pipeline editor. Then they will
      no longer be rendered in the viewports.
    </para>
  </simplesect>

  <simplesect xml:id="usage.modification_particle_selection">
    <title>Particle selection</title>
    <para>
      OVITO provides several modifiers that allow to select a subset of particles (e.g. the <link linkend="particles.modifiers.select_particle_type">Select particle types</link> modifier). 
      Other modifiers, when placed further down the modification pipeline, act only on the selected particles 
      (e.g. the <link linkend="particles.modifiers.delete_selected_particles">Delete selected particles</link> modifier).
      OVITO stores the current selection state in a standard particle property called <literal>Selection</literal>.
      Its value is 1 for particle that are selected, and 0 otherwise. Particle whose <literal>Selection</literal> property
      is nonzero are rendered with a red color in OVITO's interactive viewports to indicate that they are currently selected.
      However, their normal display color is always used when rendering an output image.
    </para>
    <para>
      Like any other particle property, the <literal>Selection</literal> property
      can be changed multiple times within a modification pipeline, for example to select a first group of particles, change their color using
      the <link linkend="particles.modifiers.assign_color">Assign color</link> modifier, then
      select another group of particles,
      and assign a different color to them using a second <link linkend="particles.modifiers.assign_color">Assign color</link> modifier.
      In other words, the selection property of a particle can have different values at different points along the
      modification pipeline. Which selection a modifiers sees depends on where it is placed in the modification pipeline.
      Note that some modifiers like the <link linkend="particles.modifiers.assign_color">Assign color</link> modifier 
      clear the current selection by default to prevent the particles from being rendered in the red selection marker color
      (which would mask the particles' real color assigned by the modifier).
    </para>
  </simplesect>

</section>
