1 <?xml version="1.0" encoding="UTF-8"?>
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2019 - Samuel GOUGEON
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.
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">
19 <refname>colorbar</refname>
20 <refpurpose>draws a vertical color bar</refpurpose>
27 colorbar(umin, umax, colminmax)
28 colorbar(umin, umax, -1)
29 colorbar( , , [fmin fmax])
33 <refsection role="parameters">
34 <title>Arguments</title>
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.
42 Let minU and maxU be the minimum and the maximum of U values.
45 Let Nc be the Number of colors in the current color map:
46 <literal>Nc = size(gcf().color_map,1)</literal>.
55 U's lowest data value covered by the colorbar.
58 Using <literal>-%inf</literal> sets <literal>umin = min(U)</literal>.
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).
71 U's biggest data value covered by the colorbar.
74 Using <literal>%inf</literal> sets <literal>umax = max(U)</literal>.
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).
84 <term>colminmax</term>
87 implicit or explicit vector <literal>[colmin, colmax]</literal> specifying
88 the range of colors that span on the colorbar, corresponding to the
89 <literal>[umin, umax]</literal> chosen data bounds.
92 <literal>colmin</literal> and <literal>colmax</literal> are indices
93 of colors in the current colormap, with
94 <literal>1 ≤ colmin < colmax ≤ Nc</literal>.
96 <para>Default setting: <literal>[1,Nc]</literal></para>
98 The dollar $ symbol can be used, standing for Nc.
99 For example, <literal>colminmax=[1 $/2]</literal> will use the first half
100 of the colormap, and <literal>colminmax=[$/2+1, $]</literal> will use the
104 Fractional bounds <literal>[fmin, fmax]</literal> may also be specified,
105 as well as using the special value <literal>colminmax=-1</literal>.
106 Please see the description section for more details.
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.
123 <title>Description</title>
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.
130 <literal>umin</literal> and <literal>umax</literal> set the data bounds scaling
131 the color bar at its bottom and top.
134 <literal>colminmax</literal> set the color range mapping the
135 <literal>[umin,umax]</literal> range, and used to fill the color bar.
138 When the current axes embeds an object of graphical type among
139 {"Matplot" "Fec" "Fac3d" "Plot3d" "Grayplot" "Champ"} 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.
146 Just after calling <literal>colorbar(…)</literal>, <literal>gce()</literal> returns
147 the graphical handle of the color bar.
150 The possible syntaxes are the following:
152 <para><emphasis role="bold">colorbar()</emphasis></para>
154 sets umin=minU and umax=maxU.
157 For a Matplot.image_type="index", sets colminmax = [minU maxU].
160 Otherwise, sets colminmax = [1 Nc]
164 <para><emphasis role="bold">colorbar(umin, umax, , Format)</emphasis></para>
166 sets <literal>colminmax=[1, Nc]</literal>.
168 <para><emphasis role="bold">colorbar(umin, umax, -1)</emphasis></para>
170 sets <literal>colmin</literal> and <literal>colmax</literal>
171 such that "[colmin,colmax]/[1,Nc]" maps the "[umin,umax]/[minU,maxU]"
174 <para><emphasis role="bold">colorbar(,, [colmin colmax])</emphasis></para>
176 with integers such that <literal>1 ≤ colmin < colmax ≤ Nc</literal> or using
177 <literal>$</literal> standing for <literal>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]".
182 <para><emphasis role="bold">colorbar(,, [fmin fmax])</emphasis></para>
184 with <literal>0 ≤ fmin < fmax ≤ 1</literal>, uses actual colors bounds
185 <literal>1+[fmin fmax]*(Nc-1)</literal>, and uses proportional
186 <literal>umin</literal> and <literal>umax</literal> accordingly,
187 such that the relative range "[umin umax]/[min(U) max(U]" maps "[fmin, fmax]".
189 <para><emphasis role="bold">colorbar(-%inf, %inf, ..)</emphasis></para>
191 sets umin = minU, umax = maxU. Each one may be set to the U bound independently.
195 <title>Examples</title>
197 <title>Example #1</title>
199 Without underlaying U data :
200 Direct umin and umax specifications.
202 <programlisting role="example"><![CDATA[
203 clf reset // clears and resets the figure
204 gcf().color_map = jetcolormap(100); // sets its color map
208 subplot(1,2,1) // Now the default current axes
209 ax0 = gca(); // is on the half left
210 ax0.axes_bounds(3) // Here is its initial width
212 // The axes is clear. There is no plotted data.
213 // We explicitely create a colorbar from scratch:
214 colorbar(-2, 8, [1 100]) // It is inserted on the right
216 // The current (empty) axes is still the same:
219 // But its width has been shrunk (by -15%) to set the
220 // colorbar on its right side.
223 // gce() returns the handle of the color bar, to postprocess and customize it.
226 ylabel(colbar1, "Temperature [°C]") // Let's add a label
227 title("°C") // or as title
228 colbar1.title.font_size = 3; // .. with a bigger font
229 // Beware: xlabel(), ylabel() title() moves the focus to the bar.
230 sca(ax0); // Reset the focus to ax0 before going on
232 // Now plot a frame in the empty axes:
235 // Then add some other color bars, still for the current axes
236 colorbar(-2, 5, [1 70])
237 // Set the labels in red
238 gce().font_color = color("red");
240 // The current axes is shrunk. The bar's width is decreased accordingly.
244 subplot(1,2,2), plotframe([0 0 1 1])
246 // top half of the colormap, with another data scale:
247 colorbar(0, 1.5, [$/2+1 $])
249 // Color bar post-processing
251 // decrease its font size:
252 set(colbar3, "fractional_font","on","font_size", 0.5);
253 // vertically extend the bar, to match the axes height:
254 colbar3.axes_bounds([2 4]) = ax1.axes_bounds([2 4]);
255 colbar3.margins([3 4]) = ax1.margins([3 4]);
256 // reverse its graduations top-down:
257 colbar3.axes_reverse(2) = "on";
258 // put its graduations on the left side:
259 colbar3.y_location = "left";
261 // Color bars are automatically redrawn and regraduated
262 // when resizing the figure. Try it!
265 ➞ Customized color bar style:
268 clf reset // clears and resets the figure
269 gcf().color_map = jetcolormap(100); // sets its color map
273 subplot(1,2,1) // Now the default current axes
274 ax0 = gca(); // is on the half left
275 ax0.axes_bounds(3) // Here is its initial width
277 // The axes is clear. There is no plotted data.
278 // We explicitely create a colorbar from scratch:
279 colorbar(-2, 8, [1 100]) // It is inserted on the right
281 // The current (empty) axes is still the same:
284 // But its width has been shrunk (by -15%) to set the
285 // colorbar on its right side.
288 // gce() returns the handle of the color bar, to postprocess and customize it.
291 ylabel(colbar1, "Temperature [°C]") // Let's add a label
292 title("°C") // or as title
293 colbar1.title.font_size = 3; // .. with a bigger font
294 // Beware: xlabel(), ylabel() title() moves the focus to the bar.
295 sca(ax0); // Reset the focus to ax0 before going on
297 // Now plot a frame in the empty axes:
300 // Then add some other color bars, still for the current axes
301 colorbar(-2, 5, [1 70])
302 // Set the labels in red
303 gce().font_color = color("red");
305 // The current axes is shrunk. The bar's width is decreased accordingly.
309 subplot(1,2,2), plotframe([0 0 1 1])
311 // top half of the colormap, with another data scale:
312 colorbar(0, 1.5, [$/2+1 $])
314 // Color bar post-processing
316 // decrease its font size:
317 set(colbar3, "fractional_font","on","font_size", 0.5);
318 // vertically extend the bar, to match the axes height:
319 colbar3.axes_bounds([2 4]) = ax1.axes_bounds([2 4]);
320 colbar3.margins([3 4]) = ax1.margins([3 4]);
321 // reverse its graduations top-down:
322 colbar3.axes_reverse(2) = "on";
323 // put its graduations on the left side:
324 colbar3.y_location = "left";
326 // Color bars are automatically redrawn and regraduated
327 // when resizing the figure. Try it!
329 gcf().axes_size = [770 440];
332 --> ax0.axes_bounds(3) // Here is its initial width
337 --> // The current (empty) axes is still the same:
343 --> // But its width has been shrunk (by -15%) ...
344 --> gca().axes_bounds
349 --> // gce() returns the handle of the color bar
355 --> colbar1 == gcf().children(1) // Another way to retrieve the handle
360 <!--===================================================-->
362 <title>Example #2 : Matplot</title>
364 <emphasis role="bold">After Matplot()</emphasis> here used with the default colormap.
366 <programlisting role="example"><![CDATA[
367 clf reset // Default colormap used
368 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
370 Matplot([1 2 3; 4 5 7]);
371 colorbar // [1 7] graduations covered by colors #[1 7].
372 // Ticks on middles of colored blocks
374 // 2) Matplot: Default colminmax = [1 Nc]
376 Matplot([1 2 3;4 5 7]);
377 colorbar(1,7) // [1 7] covered with the whole colormap.
378 // "1" at the very bottom. "7" at the very top.
380 // 3) Matplot: another colors range, with explicit colminmax
382 Matplot([1 2 3;4 5 7])
384 // Ticks 2.5-7.5 expected:
385 // - integer values ticked at the middle of colors blocks
386 // - other .5 values ticked at the blocks separations
389 clf reset // Default colormap used
390 gcf().axes_size = [770 620];
391 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
393 Matplot([1 2 3; 4 5 7]);
394 colorbar // [1 7] graduations covered by colors #[1 7].
395 // Ticks on middles of colored blocks
397 // 2) Matplot: Default colminmax = [1 Nc]
399 Matplot([1 2 3;4 5 7]);
400 colorbar(1,7) // [1 7] covered with the whole colormap.
401 // "1" at the very bottom. "7" at the very top.
403 // 3) Matplot: another colors range, with explicit colminmax
405 Matplot([1 2 3;4 5 7])
407 // Ticks 2.5-7.5 expected:
408 // - integer values ticked at the middle of colors blocks
409 // - other .5 values ticked at the blocks separations
412 <!--===================================================-->
414 <title>Example #3: After Sgrayplot()</title>
416 U data are available from the underlaying Fec object.
417 Then <literal>umin</literal> and <literal>umax</literal> may be implicit.
418 Here we use a small number of colors, showing that a given [umin umax] data
419 range (here implicitly [-1, 1], is exactly covered by chosen colors.
421 <programlisting role="example"><![CDATA[
422 x = linspace(0,1,81);
423 z = cos(2*%pi*x)'*sin(2*%pi*x);
426 gcf().color_map = jetcolormap(n);
428 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
429 gce().children.children(1:2:$-1).foreground=-1; // contours in black
432 // Default umin = minU, umax = maxU, colminmax = [1 Nc]
433 // * "-1" tick at the very bottom of the scale
434 // * "1" tick at the very top
435 // * Nice subticks, at blocks middles & blocks limits
436 // * The contours levels must be at the right levels on the color bar
439 x = linspace(0,1,81);
440 z = cos(2*%pi*x)'*sin(2*%pi*x);
443 gcf().color_map = jetcolormap(n);
445 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
446 gce().children.children(1:2:$-1).foreground=-1; // contours in black
448 gcf().axes_size = [760 450];
451 <emphasis role="bold">Partial colors range: 8 colors used over 20</emphasis>:
453 <programlisting role="example"><![CDATA[
454 x = linspace(0,1,81);
455 z = cos(2*%pi*x)'*sin(2*%pi*x);
458 gcf().color_map = jetcolormap(20);
459 gcf().axes_size = [770 320];
461 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
463 Sgrayplot(x, x, z,colminmax=[3 n+2]);
464 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
465 colorbar(-%inf,%inf,[3 n+2]);
466 // * The contours levels must be at the right levels on the color bar
468 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
470 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
471 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
472 colorbar(-0.6, 0.8,[5 11]);
474 <scilab:image><![CDATA[
475 x = linspace(0,1,81);
476 z = cos(2*%pi*x)'*sin(2*%pi*x);
479 gcf().color_map = jetcolormap(20);
480 gcf().axes_size = [770 320];
482 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
484 Sgrayplot(x, x, z,colminmax=[3 n+2]);
485 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
486 colorbar(-%inf,%inf,[3 n+2]);
487 // * The contours levels must be at the right levels on the color bar
489 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
491 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
492 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
493 colorbar(-0.6, 0.8,[5 11]);
496 <!--===================================================-->
498 <title>Example #4: for a Fac3d object</title>
499 <para> After plot3d1() or surf():
500 <programlisting role="example"><![CDATA[
501 function [zz, zz1] = plotSphere()
504 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
505 "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
506 "z=r*sin(alp)+orig(3)*ones(tet)"]);
507 [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
508 [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
510 cc1 = (xx1-orig(1)+zz1/r+2)*32;
511 plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
515 gcf().color_map = jetcolormap(120); // 120 colors available
516 gcf().axes_size = [670, 560];
518 // For these 4 plots of a sphere of radius 0.3,
519 // the color-value relationship is the same.
521 // 3.0) Implicit min(u), max(u), on the whole color map
524 colorbar; // graduations on [-0.3 0.3]
526 // 3.1) Selection of a data range. Color range set accordingly
529 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
531 // 3.2) Selection of a colormap interval. umin & umax set accordingly
534 colorbar(,,[60 120]); // graduations on [0, 0.3]
536 // 3.3) Selection of the first half of the colormap. umin & umax set accordingly
539 colorbar(,,[1 $/2]); // graduations on [-0.3, 0]
541 <scilab:image><![CDATA[
542 function [zz, zz1] = plotSphere()
545 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
546 "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
547 "z=r*sin(alp)+orig(3)*ones(tet)"]);
548 [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
549 [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
551 cc1 = (xx1-orig(1)+zz1/r+2)*32;
552 plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
556 gcf().color_map = jetcolormap(100); // 100 colors available
557 gcf().axes_size = [670, 560];
559 // For these 4 plots of a sphere of radius 0.3,
560 // the color-value relationship is the same.
562 // 3.0) Implicit min(u), max(u), on the whole color map
565 colorbar; // graduations on [-0.3 0.3]
567 // 3.1) Selection of a data range. Color range set accordingly
570 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
572 // 3.2) Selection of a colormap interval. umin & umax set accordingly
575 colorbar(,,[50 100]); // graduations on [0, 0.3]
577 // 3.3) Selection of the first half of the colormap. umin & umax set accordingly
580 colorbar(,,[1 $/2]); // graduations on [-0.3, 0]
585 <title>Example #5 : Plot3d object</title>
586 <para> After plot3d() or surf():</para>
588 <programlisting role="example"><![CDATA[
589 function plotSample()
591 plot3d(t,t,sin(t)'*cos(t));
598 gcf().color_map = rainbowcolormap(200);
599 gcf().axes_size = [800 300];
601 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
606 // 5.2) Consistent U/colors fractional selection (top 40%)
611 gcf().children([2 4]).rotation_angles = [55 45];
613 <scilab:image><![CDATA[
614 function plotSample()
616 plot3d(t,t,sin(t)'*cos(t));
623 gcf().color_map = rainbowcolormap(200);
624 gcf().axes_size = [800 300];
626 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
631 // 5.2) Consistent U/colors fractional selection
636 gcf().children([2 4]).rotation_angles = [55 45];
641 <title>Example #6: Demo</title>
643 <programlisting role="example">
644 exec("SCI/modules/graphics/demos/colormap/colormaps.dem.sce",-1)
649 <refsection role="see also">
650 <title>See also</title>
651 <simplelist type="inline">
653 <link linkend="colormap">colormap</link>
656 <link linkend="Matplot">Matplot</link>
659 <link linkend="Sgrayplot">Sgrayplot</link>
662 <link linkend="surf">surf</link>
665 <link linkend="champ">champ</link>
668 <link linkend="printf_conversion">Cformat rules</link>
672 <refsection role="history">
673 <title>History</title>
676 <revnumber>6.0.2</revnumber>
680 colorbar() syntax added.
683 implicit umin or/and umax values can now be infered either from actual
684 U data values, or from colminmax and the colormap size.
687 colminmax bounds can now be specified as fractions of the colormap size.
690 umin=-%inf and umax=%inf semantics are now available.
696 <revnumber>6.1.0</revnumber>
700 $ can be used in colminmax.
703 After calling colorbar(), gce() provides the color bar's handle.