[doc] colorbar() page overhauled
[scilab.git] / scilab / modules / graphics / help / en_US / color_management / colorbar.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) 2019 - Samuel GOUGEON
5  *
6  * This file is hereby licensed under the terms of the GNU GPL v2.0,
7  * pursuant to article 5.3.4 of the CeCILL v.2.1.
8  * This file was originally licensed under the terms of the CeCILL v2.1,
9  * and continues to be available under such terms.
10  * For more information, see the COPYING file which you should have received
11  * along with this program.
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
16           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
17           xml:lang="en" xml:id="colorbar">
18     <refnamediv>
19         <refname>colorbar</refname>
20         <refpurpose>draws a vertical color bar</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             colorbar
26             colorbar(umin, umax)
27             colorbar(umin, umax, colminmax)
28             colorbar(umin, umax, -1)
29             colorbar( , , [fmin fmax])
30             colorbar(.., Cformat)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection role="parameters">
34         <title>Arguments</title>
35         <para>
36             <itemizedlist>
37                 <listitem>
38                     Let U be the Z values of the plot for which a colorbar scale is needed, %inf, -%inf and %nan values being ignored.
39                 </listitem>
40                 <listitem>
41                     Let minU and maxU be the minimum and the maximum of U values.
42                 </listitem>
43                 <listitem>
44                     Let Nc be the Number of colors in the current color map:
45                     <literal>Nc = size(gcf().color_map,1)</literal>.
46                 </listitem>
47             </itemizedlist>
48         </para>
49         <variablelist>
50             <varlistentry>
51                 <term>umin</term>
52                 <listitem>
53                     <para>
54                         U's lowest data value covered by the colorbar.
55                     </para>
56                     <para>
57                         Using <literal>-%inf</literal> sets <literal>umin = min(U)</literal>.
58                     </para>
59                     <para>
60                         When underlaying plotted data exist in the current axes,
61                         <literal>umin</literal> may be skipped -- using colorbar(,..) --
62                         in order to extract and implicitly use min(U).
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>umax</term>
68                 <listitem>
69                     <para>
70                         U's biggest data value covered by the colorbar.
71                     </para>
72                     <para>
73                         Using <literal>%inf</literal> sets <literal>umax = max(U)</literal>.
74                     </para>
75                     <para>
76                         When underlaying plotted data exist in the current axes,
77                         <literal>umax</literal> may be skipped -- using colorbar(.., ,..) --
78                         in order to extract and implicitly use max(U).
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>colminmax</term>
84                 <listitem>
85                     <para>
86                         <literal>colminmax</literal> aims to provide the range of colors
87                         that will be spanned on the colorbar, and that will correspond
88                         to the data bounds provided through <literal>umin</literal> and
89                         <literal>umax</literal>.
90                     </para>
91                     <para>
92                         It is an implicit or explicit vector
93                         <literal>[colmin, colmax]</literal>
94                         being indices of bounding colors. The color of index
95                         <literal>colmin</literal> in the current colormap will
96                         represent the <literal>umin</literal> data value. Similarly,
97                         the color of index <literal>colmax</literal> will represent
98                         <literal>umax</literal>, with
99                         <literal>1 &lt; colmin &lt; colmax &lt; Nc</literal>.
100                     </para>
101                     <para>Default setting: <literal>[1,Nc]</literal></para>
102                     <para>
103                         Fractional bounds may also be specified, as well as using the special
104                         value <literal>colminmax=-1</literal>. Please see the description
105                         section for more details.
106                     </para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>Cformat</term>
111                 <listitem>
112                     <para>
113                         word providing a C-format formatting the display of graduated values along the colorbar. The formatting syntaxes are described in
114                         <link linkend="printf_conversion">this page</link>.
115                     </para>
116                 </listitem>
117             </varlistentry>
118         </variablelist>
119     </refsection>
120     <refsection>
121         <title>Description</title>
122         <para>
123             <literal>colorbar(…)</literal> draws a vertical color bar on the right side of
124             the current axes. The width of the targetted axes is priorly narrowed by 15%.
125             The freed room is used for the color bar, that is made of its own axes.
126         </para>
127         <para>
128             <literal>umin</literal> and <literal>umax</literal> set the data bounds scaling
129             the color bar at its bottom and top.
130         </para>
131         <para>
132             <literal>colminmax</literal> set the color range mapping the
133             <literal>[umin,umax]</literal> range, and used to fill the color bar.
134         </para>
135         <para>
136             When the current axes embeds an object of graphical type among
137             {"Matplot" "Fec" "Fac3d" "Plot3d" "Grayplot"} and its related U data,
138             it is possible to skip <literal>umin</literal> or/and <literal>umax</literal> values.
139             <literal>min(U)</literal> or/and <literal>max(U)</literal> are then retrieved
140             from data and used to set the color bar. For a "Matplot" object, the case
141             .image_type=="index" is specifically processed.
142         </para>
143         <note>
144             Just after calling <literal>colorbar(…)</literal>,
145             <literal>colbar = gcf().children(1)</literal> as well as
146             <literal>gce().parent</literal> return the graphical handle of the color bar.
147         </note>
148         <para>
149             The possible syntaxes are the following:
150         </para>
151         <para><emphasis role="bold">colorbar()</emphasis></para>
152         <para>
153             sets umin=minU and umax=maxU.
154             <itemizedlist>
155                 <listitem>
156                     For a Matplot.image_type="index", sets colminmax = [minU maxU].
157                 </listitem>
158                 <listitem>
159                     Otherwise, sets colminmax = [1 Nc]
160                 </listitem>
161             </itemizedlist>
162         </para>
163         <para><emphasis role="bold">colorbar(umin, umax, , Format)</emphasis></para>
164         <para>
165             sets <literal>colminmax=[1, Nc]</literal>.
166         </para>
167         <para><emphasis role="bold">colorbar(umin, umax, -1)</emphasis></para>
168         <para>
169             sets <literal>colmin</literal> and <literal>colmax</literal>
170             such that "[colmin,colmax]/[1,Nc]" maps the "[umin,umax]/[minU,maxU]"
171             "ratio".
172         </para>
173         <para><emphasis role="bold">colorbar(,, [colmin colmax])</emphasis></para>
174         <para>
175             with integers such that <literal>1 colmin &lt; colmax Nc</literal>.
176             Conversely to the previous one, this syntax sets
177             <literal>umin</literal> and <literal>umax</literal>
178             such that "[umin,umax]/[minU,maxU]" maps "[colmin,colmax]/[1,Nc]"
179             ratio.
180         </para>
181         <para><emphasis role="bold">colorbar(,, [fmin fmax])</emphasis></para>
182         <para>
183             The previous syntax <literal>colorbar(,,[colmin colmax])</literal> needs to know the colormap range to specify <literal>colmin</literal>
184             and <literal>colmax</literal> conveniently. This is not very
185             handy when we just want to target a fractional part of the colormap
186             whatever is its actual length. <literal>fmin</literal> and
187             <literal>fmax</literal> with <literal>0 ≤ fmin &lt; fmax ≤ 1</literal>
188             allow such a more robust specification.
189         </para>
190         <para>
191             This syntax sets
192             <itemizedlist>
193                 <listitem>
194                     <literal>umin</literal> and <literal>umax</literal> such that the relative range "[umin umax]/[min(U) max(U]" maps "[fmin, fmax]".
195                 </listitem>
196                 <listitem>
197                     <literal>[colmin colmax]</literal> such that the relative range
198                     "[colmin,colmax]/[1,Nc]" maps <literal>[fmin,fmax]</literal>.
199                 </listitem>
200             </itemizedlist>
201         </para>
202         <para><emphasis role="bold">colorbar(-%inf, %inf, ..)</emphasis></para>
203         <para>
204             sets umin = minU, umax = maxU. Each one may be set to the U bound independently.
205         </para>
206     </refsection>
207     <refsection>
208         <title>Examples</title>
209         <refsect3>
210             <title>Example #1</title>
211             without underlaying U data :
212             Direct umin and umax specifications. General colorbar() behavior.
213         <programlisting role="example"><![CDATA[
214 clf reset                           // clears and resets the figure
215 gcf().color_map = jetcolormap(100); // sets its color map
216 subplot(1,2,2), plotframe([0 0 1 1])// fake axes on the right
217 subplot(1,2,1)                      // Now the default current axes
218 ax0 = gca();                        //  is on the half left
219 ax0.axes_bounds(3)  //  Here is its initial width
220
221 // The axes is clear. There is no plotted data.
222 // We explicitely create a colorbar from scratch:
223 colorbar(-2, 8, [1 100])    // It is inserted on the right
224
225 // The current (empty) axes is still the same:
226 gca() == ax0
227
228 // But its width has been shrunk (by -15%) to set the
229 // colorbar on its right side.
230 gca().axes_bounds
231
232 // gce() returns the handle of the colored area, and
233 // gce().parent is the handle to the axes defining the color bar
234 colbar1 = gce().parent;
235 colbar1.type
236 colbar1 == gcf().children(1)  // Another way to retrieve the handle
237 // This handle allows to postprocess and customize the colorbar.
238 ylabel(colbar1, "Temperature [°C]") // Let's add a label
239 title("°C")                         // or as title
240 colbar1.title.font_size = 3;   // .. with a bigger font
241 // Beware: xlabel(), ylabel() title() moves the focus to the bar.
242 sca(ax0); // Reset the focus to ax0 before going on
243
244 // Now plot a frame in the empty axes:
245 plotframe([0 0 1 1])
246
247 // Then add some other color bars, still for the current axes
248 colorbar(-2, 5, [1 70])
249 // Set the labelsin magenta
250 gcf().children(1).font_color = color("red");
251
252 // The current axes is shrunk. The bar's width is decreased accordingly.
253
254 // A last one: top half of the colormap, with another data scale:
255 colorbar(0, 1.5, [0.5 1])  // colminmax = [fmin fmax]
256 // Let decrease its font size:
257 colbar3 = gcf().children(1);
258 set(colbar3, "fractional_font","on","font_size", 0.5);
259 // And vertically extend the bar, to match ax0's height
260 colbar3.axes_bounds([2 4]) = ax0.axes_bounds([2 4]);
261 colbar3.margins([3 4]) = ax0.margins([3 4]);
262
263 // Color bars are automatically redrawn and regraduated
264 // when resizing the figure. Try it!
265      ]]></programlisting>
266         <scilab:image>
267             clf reset                           // clears and resets the figure
268             gcf().color_map = jetcolormap(100); // sets its color map
269             gcf().figure_size = [730 420];
270             subplot(1,2,2), plotframe([0 0 1 1])// fake axes on the right
271             subplot(1,2,1)                      // Now the default current axes
272             ax0 = gca();                        //  is on the half left
273             ax0.axes_bounds(3)  //  Here is its initial width
274
275             // The axes is clear. There is no plotted data.
276             // We explicitely create a colorbar from scratch:
277             colorbar(-2, 8, [1 100])    // It is inserted on the right
278
279             // The current (empty) axes is still the same:
280             gca() == ax0
281
282             // But its width has been shrunk (by -15%) to set the
283             // colorbar on its right side.
284             gca().axes_bounds
285
286             // gce() returns the handle of the colored area, and
287             // gce().parent is the handle to the axes defining the color bar
288             colbar1 = gce().parent;
289             colbar1.type
290             colbar1 == gcf().children(1)  // Another way to retrieve the handle
291             // This handle allows to postprocess and customize the colorbar.
292             ylabel(colbar1, "Temperature [°C]") // Let's add a label
293             title("°C")                         // or as title
294             colbar1.title.font_size = 3;   // .. with a bigger font
295             // Beware: xlabel(), ylabel() title() moves the focus to the bar.
296             sca(ax0); // Reset the focus to ax0 before going on
297
298             // Now plot a frame in the empty axes:
299             plotframe([0 0 1 1])
300
301             // Then add some other color bars, still for the current axes
302             colorbar(-2, 5, [1 70])
303             // Set the labelsin magenta
304             gcf().children(1).font_color = color("red");
305
306             // The current axes is shrunk. The bar's width is decreased accordingly.
307
308             // A last one: top half of the colormap, with another data scale:
309             colorbar(0, 1.5, [0.5 1])  // colminmax = [fmin fmax]
310             // Let decrease its font size:
311             colbar3 = gcf().children(1);
312             set(colbar3, "fractional_font","on","font_size", 0.5);
313             // And vertically extend the bar, to match ax0's height
314             colbar3.axes_bounds([2 4]) = ax0.axes_bounds([2 4]);
315             colbar3.margins([3 4]) = ax0.margins([3 4]);
316
317             // Color bars are automatically redrawn and regraduated
318             // when resizing the figure. Try it!
319         </scilab:image>
320         <screen><![CDATA[
321 --> ax0.axes_bounds(3)  //  Here is its initial width
322  ans  =
323    0.5
324
325 --> ...
326 --> // The current (empty) axes is still the same:
327 --> gca() == ax0
328  ans  =
329   T
330
331 --> ...
332 --> // But its width has been shrunk (by -15%) ...
333 --> gca().axes_bounds
334  ans  =
335    0.   0.   0.425   1.
336
337 --> ...
338 --> // gce().parent is the handle to the axes defining the color bar
339 --> colbar1 = gce().parent;
340 --> colbar1.type
341  ans  =
342  Axes
343
344 --> colbar1 == gcf().children(1) // Another way to retrieve the handle
345  ans  =
346   T
347 ]]></screen>
348         </refsect3>
349         <!--===================================================-->
350         <refsect3>
351             <title>Example #2 : Matplot</title>
352             <para>
353                 <emphasis role="bold">After Matplot()</emphasis> here used with the default colormap.
354             </para>
355             <programlisting role="example"><![CDATA[
356 clf reset   // Default colormap used
357 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
358 subplot(2,2,1)
359 Matplot([1 2 3; 4 5 7]);
360 colorbar   // [1 7] graduations covered by colors #[1 7].
361            // Ticks on middles of colored blocks
362
363 // 2) Matplot: Default colminmax = [1 Nc]
364 subplot(2,2,2)
365 Matplot([1 2 3;4 5 7]);
366 colorbar(1,7)   // [1 7] covered with the whole colormap.
367                 // "1" at the very bottom. "7" at the very top.
368
369 // 3) Matplot: another colors range, with explicit colminmax
370 subplot(2,2,3)
371 Matplot([1 2 3;4 5 7])
372 colorbar(3,7, [3 7])
373 // Ticks 2.5-7.5 expected:
374 //  - integer values ticked at the middle of colors blocks
375 //  - other .5 values ticked at the blocks separations
376             ]]></programlisting>
377             <scilab:image>
378 clf reset   // Default colormap used
379 gcf().axes_size = [770 620];
380 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
381 subplot(2,2,1)
382 Matplot([1 2 3; 4 5 7]);
383 colorbar   // [1 7] graduations covered by colors #[1 7].
384            // Ticks on middles of colored blocks
385
386 // 2) Matplot: Default colminmax = [1 Nc]
387 subplot(2,2,2)
388 Matplot([1 2 3;4 5 7]);
389 colorbar(1,7)   // [1 7] covered with the whole colormap.
390                 // "1" at the very bottom. "7" at the very top.
391
392 // 3) Matplot: another colors range, with explicit colminmax
393 subplot(2,2,3)
394 Matplot([1 2 3;4 5 7])
395 colorbar(3,7, [3 7])
396 // Ticks 2.5-7.5 expected:
397 //  - integer values ticked at the middle of colors blocks
398 //  - other .5 values ticked at the blocks separations
399             </scilab:image>
400         </refsect3>
401         <!--===================================================-->
402         <refsect3>
403             <title>Example #3: After Sgrayplot()</title>
404             <para>
405                 U data are available from the underlaying Fec object.
406                 Then <literal>umin</literal> and <literal>umax</literal> may be implicit.
407                 Here we use a small number of colors, showing that a given [umin umax] data
408                 range (here implicitly [-1, 1], is exactly covered by chosen colors.
409             </para>
410             <programlisting role="example"><![CDATA[
411 x = linspace(0,1,81);
412 z = cos(2*%pi*x)'*sin(2*%pi*x);
413 n = 10;
414 clf
415 gcf().color_map = jetcolormap(n);
416 Sgrayplot(x, x, z);
417 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
418 gce().children.children(1:2:$-1).foreground=-1; // contours in black
419
420 colorbar
421 // Default umin = minU, umax = maxU, colminmax = [1 Nc]
422 // * "-1" tick at the very bottom of the scale
423 // * "1" tick at the very top
424 // * Nice subticks, at blocks middles & blocks limits
425 // * The contours levels must be at the right levels on the color bar
426             ]]></programlisting>
427             <scilab:image>
428 x = linspace(0,1,81);
429 z = cos(2*%pi*x)'*sin(2*%pi*x);
430 n = 10;
431 clf
432 gcf().color_map = jetcolormap(n);
433 Sgrayplot(x, x, z);
434 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
435 gce().children.children(1:2:$-1).foreground=-1; // contours in black
436 colorbar
437 gcf().axes_size = [760 450];
438             </scilab:image>
439             <para>
440                 <emphasis role="bold">Partial colors range: 8 colors used over 20</emphasis>:
441             </para>
442             <programlisting role="example"><![CDATA[
443 x = linspace(0,1,81);
444 z = cos(2*%pi*x)'*sin(2*%pi*x);
445 n = 8;
446 clf reset
447 gcf().color_map = jetcolormap(20);
448 gcf().axes_size = [770 320];
449
450 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
451 subplot(1,2,1)
452 Sgrayplot(x, x, z,colminmax=[3 n+2]);
453 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
454 colorbar(-%inf,%inf,[3 n+2]);
455 // * The contours levels must be at the right levels on the color bar
456
457 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
458 subplot(1,2,2)
459 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
460 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
461 colorbar(-0.6, 0.8,[5 11]);
462             ]]></programlisting>
463             <scilab:image><![CDATA[
464 x = linspace(0,1,81);
465 z = cos(2*%pi*x)'*sin(2*%pi*x);
466 n = 8;
467 clf reset
468 gcf().color_map = jetcolormap(20);
469 gcf().axes_size = [770 320];
470
471 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
472 subplot(1,2,1)
473 Sgrayplot(x, x, z,colminmax=[3 n+2]);
474 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
475 colorbar(-%inf,%inf,[3 n+2]);
476 // * The contours levels must be at the right levels on the color bar
477
478 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
479 subplot(1,2,2)
480 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
481 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
482 colorbar(-0.6, 0.8,[5 11]);
483             ]]></scilab:image>
484         </refsect3>
485         <!--===================================================-->
486         <refsect3>
487             <title>Example #4: for a Fac3d object</title>
488             <para> After plot3d1() or surf():
489             <programlisting role="example"><![CDATA[
490 function [zz, zz1] = plotSphere()
491     r = 0.3;
492     orig = [1.5 0 0];
493     deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
494          "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
495          "z=r*sin(alp)+orig(3)*ones(tet)"]);
496     [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
497     [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
498     cc  = (xx+zz+2)*32;
499     cc1 = (xx1-orig(1)+zz1/r+2)*32;
500     plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
501 endfunction
502
503 clf reset
504 gcf().color_map = jetcolormap(120);  // 120 colors available
505 gcf().axes_size = [670, 560];
506
507 // For these 4 plots of a sphere of radius 0.3,
508 //  the color-value relationship is the same.
509
510 // 3.0) Implicit min(u), max(u), on the whole color map
511 subplot(2,2,1)
512 plotSphere();
513 colorbar;               // graduations on [-0.3 0.3]
514
515 // 3.1) Selection of a data range. Color range set accordingly
516 subplot(2,2,2)
517 plotSphere();
518 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
519
520 // 3.2) Selection of a colormap interval. umin & umax set accordingly
521 subplot(2,2,3)
522 plotSphere();
523 colorbar(,,[60 120]);  // graduations on [0, 0.3]
524
525 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
526 subplot(2,2,4)
527 plotSphere();
528 colorbar(,,[0 0.5]);  // graduations on [-0.3, 0]
529             ]]></programlisting>
530             <scilab:image><![CDATA[
531 function [zz, zz1] = plotSphere()
532     r = 0.3;
533     orig = [1.5 0 0];
534     deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
535          "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
536          "z=r*sin(alp)+orig(3)*ones(tet)"]);
537     [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
538     [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
539     cc  = (xx+zz+2)*32;
540     cc1 = (xx1-orig(1)+zz1/r+2)*32;
541     plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
542 endfunction
543
544 clf reset
545 gcf().color_map = jetcolormap(100);  // 100 colors available
546 gcf().axes_size = [670, 560];
547
548 // For these 4 plots of a sphere of radius 0.3,
549 //  the color-value relationship is the same.
550
551 // 3.0) Implicit min(u), max(u), on the whole color map
552 subplot(2,2,1)
553 plotSphere();
554 colorbar;               // graduations on [-0.3 0.3]
555
556 // 3.1) Selection of a data range. Color range set accordingly
557 subplot(2,2,2)
558 plotSphere();
559 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
560
561 // 3.2) Selection of a colormap interval. umin & umax set accordingly
562 subplot(2,2,3)
563 plotSphere();
564 colorbar(,,[50 100]);  // graduations on [0, 0.3]
565
566 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
567 subplot(2,2,4)
568 plotSphere();
569 colorbar(,,[0 0.5]);  // graduations on [-0.3, 0]
570             ]]></scilab:image>
571             </para>
572         </refsect3>
573         <refsect3>
574             <title>Example #5 : Plot3d object</title>
575             <para> After plot3d() or surf():</para>
576             <para>
577                 <programlisting role="example"><![CDATA[
578 function plotSample()
579     t=[-4:0.1:4];
580     plot3d(t,t,sin(t)'*cos(t));
581     e = gce();
582     e.color_flag = 1;
583     e.color_mode = -2;
584 endfunction
585
586 clf
587 gcf().color_map = rainbowcolormap(200);
588 gcf().axes_size = [800 300];
589
590 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
591 subplot(1,2,1)
592 plotSample();
593 colorbar;
594
595 // 5.2) Consistent U/colors fractional selection (top 40%)
596 subplot(1,2,2)
597 plotSample();
598 colorbar(,,[0.6 1]);
599
600 gcf().children([2 4]).rotation_angles = [55 45];
601                 ]]></programlisting>
602             <scilab:image><![CDATA[
603 function plotSample()
604     t=[-4:0.1:4];
605     plot3d(t,t,sin(t)'*cos(t));
606     e = gce();
607     e.color_flag = 1;
608     e.color_mode = -2;
609 endfunction
610
611 clf
612 gcf().color_map = rainbowcolormap(200);
613 gcf().axes_size = [800 300];
614
615 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
616 subplot(1,2,1)
617 plotSample();
618 colorbar;
619
620 // 5.2) Consistent U/colors fractional selection
621 subplot(1,2,2)
622 plotSample();
623 colorbar(,,[0.6 1]);
624
625 gcf().children([2 4]).rotation_angles = [55 45];
626             ]]></scilab:image>
627             </para>
628         </refsect3>
629         <refsect3>
630             <title>Example #6: Demo</title>
631             <para>
632                 <programlisting role="example">
633 exec("SCI/modules/graphics/demos/colormap/colormaps.dem.sce",-1)
634                 </programlisting>
635             </para>
636         </refsect3>
637     </refsection>
638     <refsection role="see also">
639         <title>See also</title>
640         <simplelist type="inline">
641             <member>
642                 <link linkend="colormap">colormap</link>
643             </member>
644             <member>
645                 <link linkend="Matplot">Matplot</link>
646             </member>
647             <member>
648                 <link linkend="Sgrayplot">Sgrayplot</link>
649             </member>
650             <member>
651                 <link linkend="surf">surf</link>
652             </member>
653             <member>
654                 <link linkend="printf_conversion">Cformat rules</link>
655             </member>
656         </simplelist>
657     </refsection>
658     <refsection role="history">
659         <title>History</title>
660         <revhistory>
661             <revision>
662                 <revnumber>6.0.2</revnumber>
663                 <revdescription>
664                     <itemizedlist>
665                         <listitem>
666                             colorbar() syntax added.
667                         </listitem>
668                         <listitem>
669                             implicit umin or/and umax values can now be infered either from actual
670                             U data values, or from colminmax and the colormap size.
671                         </listitem>
672                         <listitem>
673                             colminmax bounds can now be specified as fractions of the colormap size.
674                         </listitem>
675                         <listitem>
676                             umin=-%inf and umax=%inf semantics are now available.
677                         </listitem>
678                     </itemizedlist>
679                 </revdescription>
680             </revision>
681         </revhistory>
682     </refsection>
683 </refentry>