<?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.affine_transformation"
         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>Affine transformation</title>

  <para>
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/affine_transformation_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    Applies an affine transformation to the particle positions and/or
    the simulation cell. The transformation is either specified as a 3x3
    matrix and an additional translation vector or by prescribing a 
    target simulation cell to which the particles are mapped.
  </para>
  
  <para>
    Given the 3x3 transformation matrix <inlineequation><mathphrase><emphasis>M</emphasis></mathphrase></inlineequation> 
    and the translation vector <inlineequation><mathphrase><emphasis>t</emphasis></mathphrase></inlineequation>,
    the new position <inlineequation><mathphrase><emphasis>x'</emphasis></mathphrase></inlineequation> of
    a particle at the old position <inlineequation><mathphrase><emphasis>x</emphasis></mathphrase></inlineequation>
    is computed as
    <inlineequation><mathphrase><emphasis>x'</emphasis> = <emphasis>M</emphasis>&#x22C5;<emphasis>x</emphasis> + <emphasis>t</emphasis></mathphrase></inlineequation>.
    Vectors are column vectors in this notation.
  </para>
  
  <para>
    The <guibutton>Enter rotation</guibutton> button opens a utility that lets you enter a rotation
    axis and an angle. It computes the corresponding transformation matrix for you.
  </para>

  <simplesect>
    <title>Parameters</title>
    
    <variablelist>
      <varlistentry>
        <term>Transform simulation cell</term>

        <listitem>
          <para>Selects whether the transformation is applied to the simulation cell.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Transform particles</term>

        <listitem>
          <para>Selects whether the transformation is applied to the
          particle coordinates. You can select which particles are affected by the
          modifier: All particles or only the selected ones.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Transform surface mesh</term>

        <listitem>
          <para>Selects whether the transformation is applied to the surface mesh (if one exists).
          Surface meshes are typically created with the <link linkend="particles.modifiers.construct_surface_mesh">Construct surface mesh</link> modifier.</para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term>Transformation matrix - Rotate/Scale/Shear</term>

        <listitem>
          <para>The 3x3 matrix specifying the affine transformation.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Transformation matrix - Translation</term>

        <listitem>
          <para>The translation that is added after multiplying a particle position with the matrix.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Transform to target box</term>

        <listitem>
          <para>The three vectors that define the target simulation cell. The
          modifier will automatically calculate the transformation matrix based on this target cell shape and 
          the input simulation cell.</para>
        </listitem>
      </varlistentry>

    </variablelist>
  </simplesect>
</section>
