<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2021 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:lang="en" xml:id="colormaps">
    <refnamediv>
        <refname>Using colormaps</refname>
        <refpurpose>Using colormaps in graphics.</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            A colormap <literal>cmap</literal> is defined by a m x 3 matrix of Red, Green and Blue
            colors intensities in the [0,1] interval. m is the number of colors defined in the colormap.
            The color number i is given in the ith row as a 3-uple <literal>cmap(i,1)</literal>,
            <literal>cmap(i,2)</literal>, <literal>cmap(i,3)</literal>. For a given colormap,
            this index i identifies the color.
        </para>
        <para>
            The default colormap contains 32 colors. You can
            change the colormap of a figure by using <literal>f.color_map=cmap</literal>
            where <literal>f</literal> is the handle of the figure.
        </para>
        <para>
            Each color in the colormap has an index you have to use to specify color in most plot
            functions. To see the indices, use function <link linkend="getcolor">getcolor</link>.
        </para>
        <para>
            A set of pre-defined colormaps is provided with Scilab. They are illustrated here-below.
        </para>
        <para>
            The colormap of the current figure can be retrieved with <literal>cmap = gcf().color_map</literal>.
        </para>
        <para>
            The current default colormap can be retrieved with <literal>cmap = gdf().color_map</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Sample</title>
        <scilab:image localized="true">
            cm = ["autumn" "bone" "cool" "copper" "gray" "hot" "hsv" "jet" "ocean" ..
                  "parula" "pink" "rainbow" "spring" "summer" "white" "winter", ..
                  "blues", "BrBG", "BuGn", "BuPu", ..
                  "coolwarm", ..
                  "GnBu", "greens", "greys", ..
                  "oranges", "OrRd", ..
                  "PiYG", "PRGn", "PuBu", "PuBuGn", "PuOr", "PuRd", "purples", ..
                  "RdBu", "RdGy", "RdPu", "RdYlBu", "RdYlGn", "reds", ..
                  "spectral", ...
                  "YlGn", "YlGnBu", "YlOrBr", "YlOrRd"];

            ncm = size(cm,"*");
            indices = [];
            cmap = [];
            for i = 0:ncm-1
                indices = [indices ; (1:128)+i*128];
                execstr("cols = "+cm(i+1)+"(128);");
                cmap = [cmap ; cols];
            end

            f = gcf();
            clf

            f.color_map = cmap;
            Matplot(indices)

            xgrid([color("grey50") -1]);
            gca().grid_position = "foreground";

            title(_("Available colormaps"), "fontsize", 4);
            xlabel(_("Colors indices in [1, 128]"), "fontsize", 3);
            gca().y_ticks = tlist(["ticks" "locations" "labels"],ncm:-1:1,cm);
            set(gca(), "font_size", 2, "sub_ticks",[4 0], "margins", [0.12 0.05 0.08 0.08]);

            gcf().axes_size = [800 800];
        </scilab:image>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
n = 64;
r = linspace(0,1,n)';
g = linspace(1,0,n)';
b = ones(r);
cmap = [r g b];
f = gcf(); f.color_map = cmap;
plot3d1()
f.color_map = gdf().color_map; // restores to the default colormap
     ]]></programlisting>
        <para/>
        <programlisting role="example"><![CDATA[
gdf().color_map
     ]]></programlisting>
        <screen><![CDATA[
--> gdf().color_map
 ans  =
   0.          0.          0.
   0.          0.          1.
   0.          1.          0.
   0.          1.          1.
   1.          0.          0.
   1.          0.          1.
   1.          1.          0.
   1.          1.          1.
   0.          0.          0.5647059
   0.          0.          0.6901961
   0.          0.          0.8156863
   0.5294118   0.8078431   1.
   0.          0.5647059   0.
   0.          0.6901961   0.
   0.          0.8156863   0.
   0.          0.5647059   0.5647059
   0.          0.6901961   0.6901961
   0.          0.8156863   0.8156863
   0.5647059   0.          0.
   0.6901961   0.          0.
   0.8156863   0.          0.
   0.5647059   0.          0.5647059
   0.6901961   0.          0.6901961
   0.8156863   0.          0.8156863
   0.5019608   0.1882353   0.
   0.627451    0.2509804   0.
   0.7529412   0.3764706   0.
   1.          0.5019608   0.5019608
   1.          0.627451    0.627451
   1.          0.7529412   0.7529412
   1.          0.8784314   0.8784314
   1.          0.8431373   0.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="autumn">autumn</link>
            </member>
            <member>
                <link linkend="bone">bone</link>
            </member>
            <member>
                <link linkend="cool">cool</link>
            </member>
            <member>
                <link linkend="copper">copper</link>
            </member>
            <member>
                <link linkend="gray">gray</link>
            </member>
            <member>
                <link linkend="hot">hot</link>
            </member>
            <member>
                <link linkend="hsv">hsv</link>
            </member>
            <member>
                <link linkend="jet">jet</link>
            </member>
            <member>
                <link linkend="ocean">ocean</link>
            </member>
            <member>
                <link linkend="parula">parula</link>
            </member>
            <member>
                <link linkend="pink">pink</link>
            </member>
            <member>
                <link linkend="rainbow">rainbow</link>
            </member>
            <member>
                <link linkend="spring">spring</link>
            </member>
            <member>
                <link linkend="summer">summer</link>
            </member>
            <member>
                <link linkend="white">white</link>
            </member>
            <member>
                <link linkend="winter">winter</link>
            </member>
            <member>
                <link linkend="color">color</link>
            </member>
            <member>
                <link linkend="getcolor">getcolor</link>
            </member>
            <member>
                <link linkend="colordef">colordef</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
