<?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="particles.modifiers.slice"
         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>Slice</title>

  <para>
  
   <informalfigure>
      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row valign="bottom">
              <entry>Input:</entry>
              <entry>Output (slice width = 0):</entry>
              <entry>Output (slice width > 0):</entry>
            </row>
            <row valign="top">
            <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/slice_example_input.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/slice_example_output1.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/slice_example_output2.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
      
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/slice_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
  This modifier deletes all particles located on one side of an infinite cutting plane. 
  Alternatively, the modifier can cut out a slice of particles as shown in the third picture on the right.</para>

  <para>Several buttons in the modifier's parameter panel allow to position and align the slicing plane:</para>

  <para><guibutton>Move plane to simulation box center</guibutton> positions the plane in the 
  center of the simulation cell. The current plane orientation is kept.</para>

  <para><guibutton>Align view direction to plane normal</guibutton> rotates the viewing
  direction of the active viewport such that it is perpendicular to the cutting plane.</para>

  <para><guibutton>Align plane normal to view direction</guibutton> rotates the cutting plan
  such that it is perpendicular to the current viewing direction.</para>

  <para><guibutton>Pick three particles</guibutton> lets the user select three particles
  in the viewport with the mouse. The slicing plane will be repositioned such that it intersects
  all three particles.</para>
  
  <simplesect>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>Distance</term>
        <listitem>
          <para>The (signed) distance of the slicing plane from the coordinate
          system's origin along the direction of the normal vector.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Normal (X,Y,Z)</term>
        <listitem>
          <para>Components of the slicing plane's normal vector. The vector does not
          have to be a unit vector.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Slice width</term>
        <listitem>
          <para>Specifies the width of the slice to cut from the particle
          set. If this parameter is zero, all particles on the positive side of the
          slicing plane are deleted. If the <emphasis>slice width</emphasis>
          parameter is non-zero, all particles whose distance from the slicing
          plane is more than half of the slice width are deleted.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Reverse orientation</term>
        <listitem>
          <para>Effectively flips the slicing plane's orientation. Removes particles on the opposite side of the plane.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Create selection (do not delete)</term>
        <listitem>
          <para>Lets the modifier select particles instead of deleting them.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Apply to selection only</term>
        <listitem>
          <para>Restricts the effect of the modifier to particles that are currently selected.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </simplesect>
</section>
