<?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.color_coding"
         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>Color coding</title>

  <para>
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/color_coding_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
  
    This modifier colors particles, bonds, or vector arrows based on one of their properties. It can be used to visualize
    per-particle or per-bond scalar quantities.
  </para>
  
  <para>
    The input property values are first mapped and clamped to the unit interval [0,1] according to the
    <emphasis>Start value</emphasis> and <emphasis>End value</emphasis>
    parameters of the modifier. The normalized values are then mapped to a corresponding color using the selected 
    color gradient map and assigned to the particles or bonds.
  </para>

  <para>
    The <guibutton>Adjust range</guibutton> button resets the <emphasis>Start value</emphasis> and
    <emphasis>End value</emphasis> parameters to the minimum and maximum values
    of the selected input property. This ensures that no clamping occurs
    when values are mapped to a color. The <guibutton>Reverse range</guibutton> button
    swaps the <emphasis>Start value</emphasis> and <emphasis>End
    value</emphasis> parameters to effectively reverse the color scale.
  </para>

  <simplesect>
    <title>Custom color maps</title>
    <para>
      The modifier provides a set of predefined color maps that you can choose from. If you want to define your
      own color scale, select <guilabel>Load custom color map...</guilabel> from the gradient list box. 
      The program will then ask you to pick an image file which contains the colors of you custom color map. 
      With this feature you can import arbitrary color maps into OVITO by preparing a
      corresponding image with an external image editor. OVITO uses the colors along one row of 
      pixels of the image to generate a user-defined color map. Here are two example color map images:
        <screenshot><mediaobject><imageobject>
          <imagedata fileref="images/modifiers/color_coding_custom_map.png" format="PNG" />
        </imageobject></mediaobject></screenshot>
        <screenshot><mediaobject><imageobject>
          <imagedata fileref="images/modifiers/color_coding_custom_map2.png" format="PNG" />
        </imageobject></mediaobject></screenshot>
    </para>
  </simplesect>

  <simplesect>
    <title>Color legend</title>
    <para>
       You can insert a color legend into rendered images and videos by adding a 
       <link linkend="viewport_overlays"><guilabel>Color legend</guilabel></link> overlay to the active viewport.
    </para>
  </simplesect>


  <simplesect>
    <title>Parameters</title>

    <variablelist>

      <varlistentry>
        <term>Operate on</term>
        <listitem>
          <para>Controls whether the modifier assigns colors to particles, bonds or vector arrows.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Property</term>
        <listitem>
          <para>The input particle or bond property to be used for color mapping.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Color gradient</term>
        <listitem>
          <para>The type of color map to use.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Start &amp; end value</term>
        <listitem>
          <para>Controls the source range for the linear mapping of property values to the [0,1] unit interval.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Color only selected particles/bonds</term>
        <listitem>
          <para>This option restricts the assignment of colors to selected particles or bonds. 
          The existing colors of unselected particles or bonds will be preserved.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Keep selection</term>
        <listitem>
          <para>OVITO uses a red color by default to highlight selected particles in the interactive viewports.
  Since this highlighting would mask the actual color assigned by this
  modifier, the modifier clears the current selection by default. 
  If you need to preserve the current selection for further use down the pipeline, activate this option.</para>
        </listitem>
      </varlistentry>

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