* Bug 16638 fixed: getcolor() rendering debugged
[scilab.git] / scilab / modules / graphics / help / en_US / color_management / colormap.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2021 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="colormap">
20     <refnamediv>
21         <refname>colormap</refname>
22         <refpurpose>using colormaps</refpurpose>
23     </refnamediv>
24     <refsection>
25         <title>Description</title>
26         <para>
27             A colormap <literal>cmap</literal> is defined by a m x 3 matrix of Red, Green and Blue
28             colors intensities in the [0,1] interval. m is the number of colors defined in the colormap.
29             The color number i is given in the ith row as a 3-uple <literal>cmap(i,1)</literal>,
30             <literal>cmap(i,2)</literal>, <literal>cmap(i,3)</literal>. For a given colormap,
31             this index i identifies the color.
32         </para>
33         <para>
34             The default factory colormap defines 32 colors. You can
35             change the colormap of a figure by using <literal>f.color_map=cmap</literal>
36             where <literal>f</literal> is the handle of the figure.
37         </para>
38         <para>
39             Each color in the colormap has an index you have to use to specify color in most plot
40             functions. To see the indices, use function <link linkend="getcolor">getcolor</link>.
41         </para>
42         <para>
43             A set of functions from <link linkend="autumncolormap">autumncolormap(n)</link>
44             to <link linkend="wintercolormap">wintercolormap(n)</link> provide swatches that can be
45             set to colormaps. They are illustrated here-below.
46         </para>
47         <para>
48             The colormap of the current figure can be retrieved with <literal>cmap = gcf().color_map</literal>.
49         </para>
50         <para>
51             The current default colormap can be retrieved with <literal>cmap = gdf().color_map</literal>.
52         </para>
53         <para>
54             The factory default colormap can be retrieved with <literal>cmap = sdf().color_map</literal>.
55         </para>
56     </refsection>
57     <refsection>
58         <title>Sample</title>
59         <scilab:image localized="true">
60             cm = ["autumn" "bone" "cool" "copper" "gray" "hot" "hsv" "jet" "ocean" ..
61                   "parula" "pink" "rainbow" "spring" "summer" "white" "winter"];
62
63             ncm = size(cm,"*");
64             indices = [];
65             cmap = [];
66             for i = 0:ncm-1
67                 indices = [indices ; (1:100)+i*100];
68                 execstr("cols = "+cm(i+1)+"colormap(100);");
69                 cmap = [cmap ; cols];
70             end
71             f = gcf();
72             clf
73             f.color_map = cmap;
74             Matplot(indices)
75
76             xgrid([color("grey50") -1]);
77             gca().grid_position = "foreground";
78
79             title(_("Available swatches: #colormap(100)"), "fontsize", 4);
80             xlabel(_("Colors indices in [1,100]"), "fontsize", 3);
81             gca().y_ticks = tlist(["ticks" "locations" "labels"],16:-1:1,cm);
82             set(gca(), "font_size", 2, "sub_ticks",[4 0], "margins", [0.12 0.05 0.08 0.08]);
83
84             gcf().axes_size = [650 650];
85         </scilab:image>
86     </refsection>
87     <refsection>
88         <title>Examples</title>
89         <programlisting role="example"><![CDATA[
90 n = 64;
91 r = linspace(0,1,n)';
92 g = linspace(1,0,n)';
93 b = ones(r);
94 cmap = [r g b];
95 f = gcf(); f.color_map = cmap;
96 plot3d1()
97 f.color_map = gdf().color_map; // restores to the default colormap
98      ]]></programlisting>
99         <para/>
100         <programlisting role="example"><![CDATA[
101 gdf().color_map
102      ]]></programlisting>
103         <screen><![CDATA[
104 --> gdf().color_map
105  ans  =
106    0.          0.          0.
107    0.          0.          1.
108    0.          1.          0.
109    0.          1.          1.
110    1.          0.          0.
111    1.          0.          1.
112    1.          1.          0.
113    1.          1.          1.
114    0.          0.          0.5647059
115    0.          0.          0.6901961
116    0.          0.          0.8156863
117    0.5294118   0.8078431   1.
118    0.          0.5647059   0.
119    0.          0.6901961   0.
120    0.          0.8156863   0.
121    0.          0.5647059   0.5647059
122    0.          0.6901961   0.6901961
123    0.          0.8156863   0.8156863
124    0.5647059   0.          0.
125    0.6901961   0.          0.
126    0.8156863   0.          0.
127    0.5647059   0.          0.5647059
128    0.6901961   0.          0.6901961
129    0.8156863   0.          0.8156863
130    0.5019608   0.1882353   0.
131    0.627451    0.2509804   0.
132    0.7529412   0.3764706   0.
133    1.          0.5019608   0.5019608
134    1.          0.627451    0.627451
135    1.          0.7529412   0.7529412
136    1.          0.8784314   0.8784314
137    1.          0.8431373   0.
138 ]]></screen>
139     </refsection>
140     <refsection role="see also">
141         <title>See also</title>
142         <simplelist type="inline">
143             <member>
144                 <link linkend="autumncolormap">autumncolormap</link>
145             </member>
146             <member>
147                 <link linkend="bonecolormap">bonecolormap</link>
148             </member>
149             <member>
150                 <link linkend="coolcolormap">coolcolormap</link>
151             </member>
152             <member>
153                 <link linkend="coppercolormap">coppercolormap</link>
154             </member>
155             <member>
156                 <link linkend="graycolormap">graycolormap</link>
157             </member>
158             <member>
159                 <link linkend="hotcolormap">hotcolormap</link>
160             </member>
161             <member>
162                 <link linkend="hsvcolormap">hsvcolormap</link>
163             </member>
164             <member>
165                 <link linkend="jetcolormap">jetcolormap</link>
166             </member>
167             <member>
168                 <link linkend="oceancolormap">oceancolormap</link>
169             </member>
170             <member>
171                 <link linkend="parulacolormap">parulacolormap</link>
172             </member>
173             <member>
174                 <link linkend="pinkcolormap">pinkcolormap</link>
175             </member>
176             <member>
177                 <link linkend="rainbowcolormap">rainbowcolormap</link>
178             </member>
179             <member>
180                 <link linkend="springcolormap">springcolormap</link>
181             </member>
182             <member>
183                 <link linkend="summercolormap">summercolormap</link>
184             </member>
185             <member>
186                 <link linkend="whitecolormap">whitecolormap</link>
187             </member>
188             <member>
189                 <link linkend="wintercolormap">wintercolormap</link>
190             </member>
191             <member>
192                 <link linkend="color">color</link>
193             </member>
194             <member>
195                 <link linkend="getcolor">getcolor</link>
196             </member>
197             <member>
198                 <link linkend="colordef">colordef</link>
199             </member>
200         </simplelist>
201     </refsection>
202 </refentry>