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