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, -%inf and %nan values being ignored.
41 Let minU and maxU be the minimum and the maximum of U values.
44 Let Nc be the Number of colors in the current color map:
45 <literal>Nc = size(gcf().color_map,1)</literal>.
54 U's lowest data value covered by the colorbar.
57 Using <literal>-%inf</literal> sets <literal>umin = min(U)</literal>.
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).
70 U's biggest data value covered by the colorbar.
73 Using <literal>%inf</literal> sets <literal>umax = max(U)</literal>.
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).
83 <term>colminmax</term>
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>.
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 < colmin < colmax < Nc</literal>.
101 <para>Default setting: <literal>[1,Nc]</literal></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.
113 word providing a C-format formatting the display of graduated values
114 along the colorbar. The formatting syntaxes are described in the
115 <link linkend="printf_conversion">printf_conversion</link> page.
122 <title>Description</title>
124 <literal>colorbar(…)</literal> draws a vertical color bar on the right side of
125 the current axes. The width of the targetted axes is priorly narrowed by 15%.
126 The freed room is used for the color bar, that is made of its own axes.
129 <literal>umin</literal> and <literal>umax</literal> set the data bounds scaling
130 the color bar at its bottom and top.
133 <literal>colminmax</literal> set the color range mapping the
134 <literal>[umin,umax]</literal> range, and used to fill the color bar.
137 When the current axes embeds an object of graphical type among
138 {"Matplot" "Fec" "Fac3d" "Plot3d" "Grayplot"} and its related U data,
139 it is possible to skip <literal>umin</literal> or/and <literal>umax</literal> values.
140 <literal>min(U)</literal> or/and <literal>max(U)</literal> are then retrieved
141 from data and used to set the color bar. For a "Matplot" object, the case
142 .image_type=="index" is specifically processed.
145 Just after calling <literal>colorbar(…)</literal>,
146 <literal>colbar = gcf().children(1)</literal> as well as
147 <literal>gce().parent</literal> return 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>.
177 Conversely to the previous one, this syntax sets
178 <literal>umin</literal> and <literal>umax</literal>
179 such that "[umin,umax]/[minU,maxU]" maps "[colmin,colmax]/[1,Nc]"
182 <para><emphasis role="bold">colorbar(,, [fmin fmax])</emphasis></para>
184 The previous syntax <literal>colorbar(,,[colmin colmax])</literal> needs to know the colormap range to specify <literal>colmin</literal>
185 and <literal>colmax</literal> conveniently. This is not very
186 handy when we just want to target a fractional part of the colormap
187 whatever is its actual length. <literal>fmin</literal> and
188 <literal>fmax</literal> with <literal>0 ≤ fmin < fmax ≤ 1</literal>
189 allow such a more robust specification.
195 <literal>umin</literal> and <literal>umax</literal> such that the relative range "[umin umax]/[min(U) max(U]" maps "[fmin, fmax]".
198 <literal>[colmin colmax]</literal> such that the relative range
199 "[colmin,colmax]/[1,Nc]" maps <literal>[fmin,fmax]</literal>.
203 <para><emphasis role="bold">colorbar(-%inf, %inf, ..)</emphasis></para>
205 sets umin = minU, umax = maxU. Each one may be set to the U bound independently.
209 <title>Examples</title>
211 <title>Example #1</title>
212 without underlaying U data :
213 Direct umin and umax specifications. General colorbar() behavior.
214 <programlisting role="example"><![CDATA[
215 clf reset // clears and resets the figure
216 gcf().color_map = jetcolormap(100); // sets its color map
217 subplot(1,2,2), plotframe([0 0 1 1])// fake axes on the right
218 subplot(1,2,1) // Now the default current axes
219 ax0 = gca(); // is on the half left
220 ax0.axes_bounds(3) // Here is its initial width
222 // The axes is clear. There is no plotted data.
223 // We explicitely create a colorbar from scratch:
224 colorbar(-2, 8, [1 100]) // It is inserted on the right
226 // The current (empty) axes is still the same:
229 // But its width has been shrunk (by -15%) to set the
230 // colorbar on its right side.
233 // gce() returns the handle of the colored area, and
234 // gce().parent is the handle to the axes defining the color bar
235 colbar1 = gce().parent;
237 colbar1 == gcf().children(1) // Another way to retrieve the handle
238 // This handle allows to postprocess and customize the colorbar.
239 ylabel(colbar1, "Temperature [°C]") // Let's add a label
240 title("°C") // or as title
241 colbar1.title.font_size = 3; // .. with a bigger font
242 // Beware: xlabel(), ylabel() title() moves the focus to the bar.
243 sca(ax0); // Reset the focus to ax0 before going on
245 // Now plot a frame in the empty axes:
248 // Then add some other color bars, still for the current axes
249 colorbar(-2, 5, [1 70])
250 // Set the labelsin magenta
251 gcf().children(1).font_color = color("red");
253 // The current axes is shrunk. The bar's width is decreased accordingly.
255 // A last one: top half of the colormap, with another data scale:
256 colorbar(0, 1.5, [0.5 1]) // colminmax = [fmin fmax]
257 // Let decrease its font size:
258 colbar3 = gcf().children(1);
259 set(colbar3, "fractional_font","on","font_size", 0.5);
260 // And vertically extend the bar, to match ax0's height
261 colbar3.axes_bounds([2 4]) = ax0.axes_bounds([2 4]);
262 colbar3.margins([3 4]) = ax0.margins([3 4]);
264 // Color bars are automatically redrawn and regraduated
265 // when resizing the figure. Try it!
268 clf reset // clears and resets the figure
269 gcf().color_map = jetcolormap(100); // sets its color map
270 gcf().figure_size = [730 420];
271 subplot(1,2,2), plotframe([0 0 1 1])// fake axes on the right
272 subplot(1,2,1) // Now the default current axes
273 ax0 = gca(); // is on the half left
274 ax0.axes_bounds(3) // Here is its initial width
276 // The axes is clear. There is no plotted data.
277 // We explicitely create a colorbar from scratch:
278 colorbar(-2, 8, [1 100]) // It is inserted on the right
280 // The current (empty) axes is still the same:
283 // But its width has been shrunk (by -15%) to set the
284 // colorbar on its right side.
287 // gce() returns the handle of the colored area, and
288 // gce().parent is the handle to the axes defining the color bar
289 colbar1 = gce().parent;
291 colbar1 == gcf().children(1) // Another way to retrieve the handle
292 // This handle allows to postprocess and customize the colorbar.
293 ylabel(colbar1, "Temperature [°C]") // Let's add a label
294 title("°C") // or as title
295 colbar1.title.font_size = 3; // .. with a bigger font
296 // Beware: xlabel(), ylabel() title() moves the focus to the bar.
297 sca(ax0); // Reset the focus to ax0 before going on
299 // Now plot a frame in the empty axes:
302 // Then add some other color bars, still for the current axes
303 colorbar(-2, 5, [1 70])
304 // Set the labelsin magenta
305 gcf().children(1).font_color = color("red");
307 // The current axes is shrunk. The bar's width is decreased accordingly.
309 // A last one: top half of the colormap, with another data scale:
310 colorbar(0, 1.5, [0.5 1]) // colminmax = [fmin fmax]
311 // Let decrease its font size:
312 colbar3 = gcf().children(1);
313 set(colbar3, "fractional_font","on","font_size", 0.5);
314 // And vertically extend the bar, to match ax0's height
315 colbar3.axes_bounds([2 4]) = ax0.axes_bounds([2 4]);
316 colbar3.margins([3 4]) = ax0.margins([3 4]);
318 // Color bars are automatically redrawn and regraduated
319 // when resizing the figure. Try it!
322 --> ax0.axes_bounds(3) // Here is its initial width
327 --> // The current (empty) axes is still the same:
333 --> // But its width has been shrunk (by -15%) ...
334 --> gca().axes_bounds
339 --> // gce().parent is the handle to the axes defining the color bar
340 --> colbar1 = gce().parent;
345 --> colbar1 == gcf().children(1) // Another way to retrieve the handle
350 <!--===================================================-->
352 <title>Example #2 : Matplot</title>
354 <emphasis role="bold">After Matplot()</emphasis> here used with the default colormap.
356 <programlisting role="example"><![CDATA[
357 clf reset // Default colormap used
358 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
360 Matplot([1 2 3; 4 5 7]);
361 colorbar // [1 7] graduations covered by colors #[1 7].
362 // Ticks on middles of colored blocks
364 // 2) Matplot: Default colminmax = [1 Nc]
366 Matplot([1 2 3;4 5 7]);
367 colorbar(1,7) // [1 7] covered with the whole colormap.
368 // "1" at the very bottom. "7" at the very top.
370 // 3) Matplot: another colors range, with explicit colminmax
372 Matplot([1 2 3;4 5 7])
374 // Ticks 2.5-7.5 expected:
375 // - integer values ticked at the middle of colors blocks
376 // - other .5 values ticked at the blocks separations
379 clf reset // Default colormap used
380 gcf().axes_size = [770 620];
381 // 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
383 Matplot([1 2 3; 4 5 7]);
384 colorbar // [1 7] graduations covered by colors #[1 7].
385 // Ticks on middles of colored blocks
387 // 2) Matplot: Default colminmax = [1 Nc]
389 Matplot([1 2 3;4 5 7]);
390 colorbar(1,7) // [1 7] covered with the whole colormap.
391 // "1" at the very bottom. "7" at the very top.
393 // 3) Matplot: another colors range, with explicit colminmax
395 Matplot([1 2 3;4 5 7])
397 // Ticks 2.5-7.5 expected:
398 // - integer values ticked at the middle of colors blocks
399 // - other .5 values ticked at the blocks separations
402 <!--===================================================-->
404 <title>Example #3: After Sgrayplot()</title>
406 U data are available from the underlaying Fec object.
407 Then <literal>umin</literal> and <literal>umax</literal> may be implicit.
408 Here we use a small number of colors, showing that a given [umin umax] data
409 range (here implicitly [-1, 1], is exactly covered by chosen colors.
411 <programlisting role="example"><![CDATA[
412 x = linspace(0,1,81);
413 z = cos(2*%pi*x)'*sin(2*%pi*x);
416 gcf().color_map = jetcolormap(n);
418 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
419 gce().children.children(1:2:$-1).foreground=-1; // contours in black
422 // Default umin = minU, umax = maxU, colminmax = [1 Nc]
423 // * "-1" tick at the very bottom of the scale
424 // * "1" tick at the very top
425 // * Nice subticks, at blocks middles & blocks limits
426 // * The contours levels must be at the right levels on the color bar
429 x = linspace(0,1,81);
430 z = cos(2*%pi*x)'*sin(2*%pi*x);
433 gcf().color_map = jetcolormap(n);
435 contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
436 gce().children.children(1:2:$-1).foreground=-1; // contours in black
438 gcf().axes_size = [760 450];
441 <emphasis role="bold">Partial colors range: 8 colors used over 20</emphasis>:
443 <programlisting role="example"><![CDATA[
444 x = linspace(0,1,81);
445 z = cos(2*%pi*x)'*sin(2*%pi*x);
448 gcf().color_map = jetcolormap(20);
449 gcf().axes_size = [770 320];
451 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
453 Sgrayplot(x, x, z,colminmax=[3 n+2]);
454 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
455 colorbar(-%inf,%inf,[3 n+2]);
456 // * The contours levels must be at the right levels on the color bar
458 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
460 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
461 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
462 colorbar(-0.6, 0.8,[5 11]);
464 <scilab:image><![CDATA[
465 x = linspace(0,1,81);
466 z = cos(2*%pi*x)'*sin(2*%pi*x);
469 gcf().color_map = jetcolormap(20);
470 gcf().axes_size = [770 320];
472 // 3.2) umin=minU and umax=maxU, covered by a subrange of colors
474 Sgrayplot(x, x, z,colminmax=[3 n+2]);
475 contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
476 colorbar(-%inf,%inf,[3 n+2]);
477 // * The contours levels must be at the right levels on the color bar
479 // 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
481 Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
482 contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
483 colorbar(-0.6, 0.8,[5 11]);
486 <!--===================================================-->
488 <title>Example #4: for a Fac3d object</title>
489 <para> After plot3d1() or surf():
490 <programlisting role="example"><![CDATA[
491 function [zz, zz1] = plotSphere()
494 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
495 "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
496 "z=r*sin(alp)+orig(3)*ones(tet)"]);
497 [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
498 [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
500 cc1 = (xx1-orig(1)+zz1/r+2)*32;
501 plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
505 gcf().color_map = jetcolormap(120); // 120 colors available
506 gcf().axes_size = [670, 560];
508 // For these 4 plots of a sphere of radius 0.3,
509 // the color-value relationship is the same.
511 // 3.0) Implicit min(u), max(u), on the whole color map
514 colorbar; // graduations on [-0.3 0.3]
516 // 3.1) Selection of a data range. Color range set accordingly
519 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
521 // 3.2) Selection of a colormap interval. umin & umax set accordingly
524 colorbar(,,[60 120]); // graduations on [0, 0.3]
526 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
529 colorbar(,,[0 0.5]); // graduations on [-0.3, 0]
531 <scilab:image><![CDATA[
532 function [zz, zz1] = plotSphere()
535 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
536 "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
537 "z=r*sin(alp)+orig(3)*ones(tet)"]);
538 [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
539 [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
541 cc1 = (xx1-orig(1)+zz1/r+2)*32;
542 plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
546 gcf().color_map = jetcolormap(100); // 100 colors available
547 gcf().axes_size = [670, 560];
549 // For these 4 plots of a sphere of radius 0.3,
550 // the color-value relationship is the same.
552 // 3.0) Implicit min(u), max(u), on the whole color map
555 colorbar; // graduations on [-0.3 0.3]
557 // 3.1) Selection of a data range. Color range set accordingly
560 colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]
562 // 3.2) Selection of a colormap interval. umin & umax set accordingly
565 colorbar(,,[50 100]); // graduations on [0, 0.3]
567 // 3.3) Selection of a colormap relative part. umin & umax set accordingly
570 colorbar(,,[0 0.5]); // graduations on [-0.3, 0]
575 <title>Example #5 : Plot3d object</title>
576 <para> After plot3d() or surf():</para>
578 <programlisting role="example"><![CDATA[
579 function plotSample()
581 plot3d(t,t,sin(t)'*cos(t));
588 gcf().color_map = rainbowcolormap(200);
589 gcf().axes_size = [800 300];
591 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
596 // 5.2) Consistent U/colors fractional selection (top 40%)
601 gcf().children([2 4]).rotation_angles = [55 45];
603 <scilab:image><![CDATA[
604 function plotSample()
606 plot3d(t,t,sin(t)'*cos(t));
613 gcf().color_map = rainbowcolormap(200);
614 gcf().axes_size = [800 300];
616 // 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
621 // 5.2) Consistent U/colors fractional selection
626 gcf().children([2 4]).rotation_angles = [55 45];
631 <title>Example #6: Demo</title>
633 <programlisting role="example">
634 exec("SCI/modules/graphics/demos/colormap/colormaps.dem.sce",-1)
639 <refsection role="see also">
640 <title>See also</title>
641 <simplelist type="inline">
643 <link linkend="colormap">colormap</link>
646 <link linkend="Matplot">Matplot</link>
649 <link linkend="Sgrayplot">Sgrayplot</link>
652 <link linkend="surf">surf</link>
655 <link linkend="printf_conversion">Cformat rules</link>
659 <refsection role="history">
660 <title>History</title>
663 <revnumber>6.0.2</revnumber>
667 colorbar() syntax added.
670 implicit umin or/and umax values can now be infered either from actual
671 U data values, or from colminmax and the colormap size.
674 colminmax bounds can now be specified as fractions of the colormap size.
677 umin=-%inf and umax=%inf semantics are now available.