<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
		<!ENTITY % darktable_dtd SYSTEM "../../dtd/darktable.dtd">
		%darktable_dtd;
		]>
<sect2 status="final" id="global_color_picker">

  <title>Global color picker</title>

  <indexterm>
    <primary>darkroom panels</primary>
    <secondary>color picker</secondary>
  </indexterm>

  <indexterm>
    <primary>color picker</primary>
  </indexterm>

  <informaltable frame="none">
    <tgroup cols="2" colsep="0" rowsep="0">
      <colspec colwidth="6*"/>
      <colspec colwidth="4*"/>
      <tbody>
        <row>
          <entry>
            <para>
              Using the global color picker you can take color samples from your image, display
              their values in multiple ways and compare colors from different locations. The
              color picker is activated by pressing the
              <inlinegraphic fileref="&icon_module_picker;" scalefit="1" width="3%" align="center" />
              icon. There are multiple parameters for controlling how the color picker works,
              whose settings remain in effect until you leave the darkroom mode.
            </para>
          </entry>
          <entry>
            <graphic fileref="darkroom/images/panel_colorpicker.png" scalefit="1" width="80%" align="center" />
          </entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>

  <para>
    Besides the global color picker described here there are also local color pickers in some of
    the modules (eg. <link linkend="tone_curve"> <emphasis>tone curve</emphasis></link>). Global
    and local color pickers are different. The global color picker works in monitor color space
    and takes samples after the complete pixelpipe has been processed. The local color pickers
    run in the color space of the individual module, which is usually Lab; they reflect the
    input and output data of that specific module within pixelpipe.
  </para>

  <para>
    The global color picker can be run in point or area mode. When in point mode only a small
    spot under your cursor is taken as a sample. In area mode you can draw a rectangle and
    darktable samples the area within that rectangle. The combobox to switch between point and
    area mode can also be used to toggle the mode of local color pickers.
  </para>

  <para>
    If samples are taken in area mode, darktable will calculate mean, min and max color channel
    values. A combobox allows you to select which of those are displayed. For obvious
    statistical reasons mean, min and max are identical for the single sample of point mode.
  </para>

  <para>
    A color swatch representing the sampled point or area is displayed. Numerical values are
    shown as well. As said before global color picker works in monitor RGB color space. You can
    also let darktable translate these numerical values into Lab color space. Beware that Lab
    values are approximated here; depending on monitor color profile there can be some
    deviations from the real values.
  </para>

  <para>
    When the checkbox <quote>restrict histogram to selection</quote> is ticked, only the values
    of your selected area or point are taken into account by the main histogram at the top of
    the right hand panel (see <xref linkend="histogram"/>). This is a way to show which tonal
    values are present in a specific area.
  </para>

  <para>
    The sampled colors in either area or point mode can be <quote>stored</quote> as live samples
    by pressing the <quote>add</quote> button. darktable will then show a color swatch and
    numerical values for each stored sample. You can once again select which numerical value
    (mean, min, max) is to be displayed and if this is to be done in RGB or Lab color space.
  </para>

  <para>
    Newly created live samples are not locked. If you change your image the changes will be
    reflected in your live samples. Use this if you want see how changing parameters effects
    different parts of an image. Clicking on a live sample's color swatch locks it and a lock
    symbol is displayed. Further image changes will then no longer affect the sample. You can
    for example take two live samples from the same location and lock just one of them to
    provide a before and after sample comparison.
  </para>

  <para>
    Live sample locations are indicated in your image if you check option <quote>display sample
    areas on image</quote>.
  </para>

</sect2>