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 <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>.
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 < colmax ≤ Nc</literal>.
102 <para>Default setting: <literal>[1,Nc]</literal></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.
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"} 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>,
147 <literal>colbar = gcf().children(1)</literal> as well as
148 <literal>gce().parent</literal> return the graphical handle of the color bar.
151 The possible syntaxes are the following:
153 <para><emphasis role="bold">colorbar()</emphasis></para>
155 sets umin=minU and umax=maxU.
158 For a Matplot.image_type="index", sets colminmax = [minU maxU].
161 Otherwise, sets colminmax = [1 Nc]
165 <para><emphasis role="bold">colorbar(umin, umax, , Format)</emphasis></para>
167 sets <literal>colminmax=[1, Nc]</literal>.
169 <para><emphasis role="bold">colorbar(umin, umax, -1)</emphasis></para>
171 sets <literal>colmin</literal> and <literal>colmax</literal>
172 such that "[colmin,colmax]/[1,Nc]" maps the "[umin,umax]/[minU,maxU]"
175 <para><emphasis role="bold">colorbar(,, [colmin colmax])</emphasis></para>
177 with integers such that <literal>1 ≤ colmin < 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]"
183 <para><emphasis role="bold">colorbar(,, [fmin fmax])</emphasis></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 < fmax ≤ 1</literal>
191 allow such a more robust specification.
197 <literal>umin</literal> and <literal>umax</literal> such that the relative
198 range "[umin umax]/[min(U) max(U]" maps "[fmin, fmax]".
201 <literal>[colmin colmax]</literal> such that the relative range
202 "[colmin,colmax]/[1,Nc]" maps <literal>[fmin,fmax]</literal>.
206 <para><emphasis role="bold">colorbar(-%inf, %inf, ..)</emphasis></para>
208 sets umin = minU, umax = maxU. Each one may be set to the U bound independently.
212 <title>Examples</title>
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
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
229 // The current (empty) axes is still the same:
232 // But its width has been shrunk (by -15%) to set the
233 // colorbar on its right side.
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;
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
248 // Now plot a frame in the empty axes:
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");
256 // The current axes is shrunk. The bar's width is decreased accordingly.
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]);
267 // Color bars are automatically redrawn and regraduated
268 // when resizing the figure. Try it!
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
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
283 // The current (empty) axes is still the same:
286 // But its width has been shrunk (by -15%) to set the
287 // colorbar on its right side.
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;
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
302 // Now plot a frame in the empty axes:
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");
310 // The current axes is shrunk. The bar's width is decreased accordingly.
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]);
321 // Color bars are automatically redrawn and regraduated
322 // when resizing the figure. Try it!
325 --> ax0.axes_bounds(3) // Here is its initial width
330 --> // The current (empty) axes is still the same:
336 --> // But its width has been shrunk (by -15%) ...
337 --> gca().axes_bounds
342 --> // gce().parent is the handle to the axes defining the color bar
343 --> colbar1 = gce().parent;
348 --> colbar1 == gcf().children(1) // Another way to retrieve the handle
353 <!--===================================================-->
355 <title>Example #2 : Matplot</title>
357 <emphasis role="bold">After Matplot()</emphasis> here used with the default colormap.
359 <programlisting role="example"><![CDATA[
360 clf reset // Default colormap used
361 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
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
367 // 2) Matplot: Default colminmax = [1 Nc]
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.
373 // 3) Matplot: another colors range, with explicit colminmax
375 Matplot([1 2 3;4 5 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
382 clf reset // Default colormap used
383 gcf().axes_size = [770 620];
384 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
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
390 // 2) Matplot: Default colminmax = [1 Nc]
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.
396 // 3) Matplot: another colors range, with explicit colminmax
398 Matplot([1 2 3;4 5 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
405 <!--===================================================-->
407 <title>Example #3: After Sgrayplot()</title>
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.
414 <programlisting role="example"><![CDATA[
415 x = linspace(0,1,81);
416 z = cos(2*%pi*x)'*sin(2*%pi*x);
419 gcf().color_map = jetcolormap(n);
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
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
432 x = linspace(0,1,81);
433 z = cos(2*%pi*x)'*sin(2*%pi*x);
436 gcf().color_map = jetcolormap(n);
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
441 gcf().axes_size = [760 450];
444 <emphasis role="bold">Partial colors range: 8 colors used over 20</emphasis>:
446 <programlisting role="example"><![CDATA[
447 x = linspace(0,1,81);
448 z = cos(2*%pi*x)'*sin(2*%pi*x);
451 gcf().color_map = jetcolormap(20);
452 gcf().axes_size = [770 320];
454 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
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
461 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
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]);
467 <scilab:image><![CDATA[
468 x = linspace(0,1,81);
469 z = cos(2*%pi*x)'*sin(2*%pi*x);
472 gcf().color_map = jetcolormap(20);
473 gcf().axes_size = [770 320];
475 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
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
482 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
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]);
489 <!--===================================================-->
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()
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));
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])
508 gcf().color_map = jetcolormap(120); // 120 colors available
509 gcf().axes_size = [670, 560];
511 // For these 4 plots of a sphere of radius 0.3,
512 // the color-value relationship is the same.
514 // 3.0) Implicit min(u), max(u), on the whole color map
517 colorbar; // graduations on [-0.3 0.3]
519 // 3.1) Selection of a data range. Color range set accordingly
522 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
524 // 3.2) Selection of a colormap interval. umin & umax set accordingly
527 colorbar(,,[60 120]); // graduations on [0, 0.3]
529 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
532 colorbar(,,[0 0.5]); // graduations on [-0.3, 0]
534 <scilab:image><![CDATA[
535 function [zz, zz1] = plotSphere()
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));
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])
549 gcf().color_map = jetcolormap(100); // 100 colors available
550 gcf().axes_size = [670, 560];
552 // For these 4 plots of a sphere of radius 0.3,
553 // the color-value relationship is the same.
555 // 3.0) Implicit min(u), max(u), on the whole color map
558 colorbar; // graduations on [-0.3 0.3]
560 // 3.1) Selection of a data range. Color range set accordingly
563 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
565 // 3.2) Selection of a colormap interval. umin & umax set accordingly
568 colorbar(,,[50 100]); // graduations on [0, 0.3]
570 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
573 colorbar(,,[0 0.5]); // graduations on [-0.3, 0]
578 <title>Example #5 : Plot3d object</title>
579 <para> After plot3d() or surf():</para>
581 <programlisting role="example"><![CDATA[
582 function plotSample()
584 plot3d(t,t,sin(t)'*cos(t));
591 gcf().color_map = rainbowcolormap(200);
592 gcf().axes_size = [800 300];
594 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
599 // 5.2) Consistent U/colors fractional selection (top 40%)
604 gcf().children([2 4]).rotation_angles = [55 45];
606 <scilab:image><![CDATA[
607 function plotSample()
609 plot3d(t,t,sin(t)'*cos(t));
616 gcf().color_map = rainbowcolormap(200);
617 gcf().axes_size = [800 300];
619 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
624 // 5.2) Consistent U/colors fractional selection
629 gcf().children([2 4]).rotation_angles = [55 45];
634 <title>Example #6: Demo</title>
636 <programlisting role="example">
637 exec("SCI/modules/graphics/demos/colormap/colormaps.dem.sce",-1)
642 <refsection role="see also">
643 <title>See also</title>
644 <simplelist type="inline">
646 <link linkend="colormap">colormap</link>
649 <link linkend="Matplot">Matplot</link>
652 <link linkend="Sgrayplot">Sgrayplot</link>
655 <link linkend="surf">surf</link>
658 <link linkend="printf_conversion">Cformat rules</link>
662 <refsection role="history">
663 <title>History</title>
666 <revnumber>6.0.2</revnumber>
670 colorbar() syntax added.
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.
677 colminmax bounds can now be specified as fractions of the colormap size.
680 umin=-%inf and umax=%inf semantics are now available.