Scilab Home page | Wiki | Bug tracker | Forge | Mailing list archives | ATOMS | File exchange
Please login or create an account
Change language to: English - Português - 日本語 - Русский
Aide de Scilab >> Graphiques > Couleurs > colorbar


draws a vertical color bar


colorbar(umin, umax)
colorbar(umin, umax, colminmax)
colorbar(umin, umax, -1)
colorbar( , , [fmin fmax])
colorbar(.., Cformat)


  • Let U be the Z values of the plot for which a colorbar scale is needed, %inf, -%inf and %nan values being ignored.
  • Let minU and maxU be the minimum and the maximum of U values.
  • Let Nc be the Number of colors in the current color map: Nc = size(gcf().color_map,1).


U's lowest data value covered by the colorbar.

Using -%inf sets umin = min(U).

When underlaying plotted data exist in the current axes, umin may be skipped -- using colorbar(,..) -- in order to extract and implicitly use min(U).


U's biggest data value covered by the colorbar.

Using %inf sets umax = max(U).

When underlaying plotted data exist in the current axes, umax may be skipped -- using colorbar(.., ,..) -- in order to extract and implicitly use max(U).


colminmax aims to provide the range of colors that will be spanned on the colorbar, and that will correspond to the data bounds provided through umin and umax.

It is an implicit or explicit vector [colmin, colmax] being indices of bounding colors. The color of index colmin in the current colormap will represent the umin data value. Similarly, the color of index colmax will represent umax, with 1 < colmin < colmax < Nc.

Default setting: [1,Nc]

Fractional bounds may also be specified, as well as using the special value colminmax=-1. Please see the description section for more details.


word providing a C-format formatting the display of graduated values along the colorbar. The formatting syntaxes are described in this page.


colorbar(…) draws a vertical color bar on the right side of the current axes. The width of the targetted axes is priorly narrowed by 15%. The freed room is used for the color bar, that is made of its own axes.

umin and umax set the data bounds scaling the color bar at its bottom and top.

colminmax set the color range mapping the [umin,umax] range, and used to fill the color bar.

When the current axes embeds an object of graphical type among {"Matplot" "Fec" "Fac3d" "Plot3d" "Grayplot"} and its related U data, it is possible to skip umin or/and umax values. min(U) or/and max(U) are then retrieved from data and used to set the color bar. For a "Matplot" object, the case .image_type=="index" is specifically processed.

Just after calling colorbar(…), colbar = gcf().children(1) as well as gce().parent return the graphical handle of the color bar.

The possible syntaxes are the following:


sets umin=minU and umax=maxU.

  • For a Matplot.image_type="index", sets colminmax = [minU maxU].
  • Otherwise, sets colminmax = [1 Nc]

colorbar(umin, umax, , Format)

sets colminmax=[1, Nc].

colorbar(umin, umax, -1)

sets colmin and colmax such that "[colmin,colmax]/[1,Nc]" maps the "[umin,umax]/[minU,maxU]" "ratio".

colorbar(,, [colmin colmax])

with integers such that 1 colmin < colmax Nc. Conversely to the previous one, this syntax sets umin and umax such that "[umin,umax]/[minU,maxU]" maps "[colmin,colmax]/[1,Nc]" ratio.

colorbar(,, [fmin fmax])

The previous syntax colorbar(,,[colmin colmax]) needs to know the colormap range to specify colmin and colmax conveniently. This is not very handy when we just want to target a fractional part of the colormap whatever is its actual length. fmin and fmax with 0 ≤ fmin < fmax ≤ 1 allow such a more robust specification.

This syntax sets

  • umin and umax such that the relative range "[umin umax]/[min(U) max(U]" maps "[fmin, fmax]".
  • [colmin colmax] such that the relative range "[colmin,colmax]/[1,Nc]" maps [fmin,fmax].

colorbar(-%inf, %inf, ..)

sets umin = minU, umax = maxU. Each one may be set to the U bound independently.


Example #1
without underlaying U data : Direct umin and umax specifications. General colorbar() behavior.
clf reset                           // clears and resets the figure
gcf().color_map = jetcolormap(100); // sets its color map
subplot(1,2,2), plotframe([0 0 1 1])// fake axes on the right
subplot(1,2,1)                      // Now the default current axes
ax0 = gca();                        //  is on the half left
ax0.axes_bounds(3)  //  Here is its initial width

// The axes is clear. There is no plotted data.
// We explicitely create a colorbar from scratch:
colorbar(-2, 8, [1 100])    // It is inserted on the right

// The current (empty) axes is still the same:
gca() == ax0

// But its width has been shrunk (by -15%) to set the
// colorbar on its right side.

// gce() returns the handle of the colored area, and
// gce().parent is the handle to the axes defining the color bar
colbar1 = gce().parent;
colbar1 == gcf().children(1)  // Another way to retrieve the handle
// This handle allows to postprocess and customize the colorbar.
ylabel(colbar1, "Temperature [°C]") // Let's add a label
title("°C")                         // or as title
colbar1.title.font_size = 3;   // .. with a bigger font
// Beware: xlabel(), ylabel() title() moves the focus to the bar.
sca(ax0); // Reset the focus to ax0 before going on

// Now plot a frame in the empty axes:
plotframe([0 0 1 1])

// Then add some other color bars, still for the current axes
colorbar(-2, 5, [1 70])
// Set the labelsin magenta
gcf().children(1).font_color = color("red");

// The current axes is shrunk. The bar's width is decreased accordingly.

// A last one: top half of the colormap, with another data scale:
colorbar(0, 1.5, [0.5 1])  // colminmax = [fmin fmax]
// Let decrease its font size:
colbar3 = gcf().children(1);
set(colbar3, "fractional_font","on","font_size", 0.5);
// And vertically extend the bar, to match ax0's height
colbar3.axes_bounds([2 4]) = ax0.axes_bounds([2 4]);
colbar3.margins([3 4]) = ax0.margins([3 4]);

// Color bars are automatically redrawn and regraduated
// when resizing the figure. Try it!
--> ax0.axes_bounds(3)  //  Here is its initial width
 ans  =

--> ...
--> // The current (empty) axes is still the same:
--> gca() == ax0
 ans  =

--> ...
--> // But its width has been shrunk (by -15%) ...
--> gca().axes_bounds
 ans  =
   0.   0.   0.425   1.

--> ...
--> // gce().parent is the handle to the axes defining the color bar
--> colbar1 = gce().parent;
--> colbar1.type
 ans  =

--> colbar1 == gcf().children(1) // Another way to retrieve the handle
 ans  =
Example #2 : Matplot

After Matplot() here used with the default colormap.

clf reset   // Default colormap used
// 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
Matplot([1 2 3; 4 5 7]);
colorbar   // [1 7] graduations covered by colors #[1 7].
           // Ticks on middles of colored blocks

// 2) Matplot: Default colminmax = [1 Nc]
Matplot([1 2 3;4 5 7]);
colorbar(1,7)   // [1 7] covered with the whole colormap.
                // "1" at the very bottom. "7" at the very top.

// 3) Matplot: another colors range, with explicit colminmax
Matplot([1 2 3;4 5 7])
colorbar(3,7, [3 7])
// Ticks 2.5-7.5 expected:
//  - integer values ticked at the middle of colors blocks
//  - other .5 values ticked at the blocks separations
Example #3: After Sgrayplot()

U data are available from the underlaying Fec object. Then umin and umax may be implicit. Here we use a small number of colors, showing that a given [umin umax] data range (here implicitly [-1, 1], is exactly covered by chosen colors.

x = linspace(0,1,81);
z = cos(2*%pi*x)'*sin(2*%pi*x);
n = 10;
gcf().color_map = jetcolormap(n);
Sgrayplot(x, x, z);
contour(x,x,z,[-0.8 -0.6 -0.4 -0.2 0 0.2 0.4 0.6 0.8]);
gce().children.children(1:2:$-1).foreground=-1; // contours in black

// Default umin = minU, umax = maxU, colminmax = [1 Nc]
// * "-1" tick at the very bottom of the scale
// * "1" tick at the very top
// * Nice subticks, at blocks middles & blocks limits
// * The contours levels must be at the right levels on the color bar

Partial colors range: 8 colors used over 20:

x = linspace(0,1,81);
z = cos(2*%pi*x)'*sin(2*%pi*x);
n = 8;
clf reset
gcf().color_map = jetcolormap(20);
gcf().axes_size = [770 320];

// 3.2) umin=minU and umax=maxU, covered by a subrange of colors
Sgrayplot(x, x, z,colminmax=[3 n+2]);
contour(x,x,z,[-0.75 -0.5 -0.25 0 0.25 0.5 0.75]);
colorbar(-%inf,%inf,[3 n+2]);
// * The contours levels must be at the right levels on the color bar

// 3.3) Explicit umin and umax, with saturation for z values out of [umin, umax]:
Sgrayplot(x, x, z, zminmax = [-0.6 0.8], colminmax = [5 11]);
contour(x,x,z,[-0.6 -0.4 -0.2 0.2 0.4 0.6]);
colorbar(-0.6, 0.8,[5 11]);
Example #4: for a Fac3d object

After plot3d1() or surf():

function [zz, zz1]=plotSphere()
    r = 0.3;
    orig = [1.5 0 0];
    [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
    [xx1,yy1,zz1] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
    cc  = (xx+zz+2)*32;
    cc1 = (xx1-orig(1)+zz1/r+2)*32;
    plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])

clf reset
gcf().color_map = jetcolormap(120);  // 120 colors available
gcf().axes_size = [670, 560];

// For these 4 plots of a sphere of radius 0.3,
//  the color-value relationship is the same.

// 3.0) Implicit min(u), max(u), on the whole color map
colorbar;               // graduations on [-0.3 0.3]

// 3.1) Selection of a data range. Color range set accordingly
colorbar(0.0, 0.15, -1);// graduations on [0, 0.15]

// 3.2) Selection of a colormap interval. umin & umax set accordingly
colorbar(,,[60 120]);  // graduations on [0, 0.3]

// 3.3) Selection of a colormap relative part. umin & umax set accordingly
colorbar(,,[0 0.5]);  // graduations on [-0.3, 0]

Example #5 : Plot3d object

After plot3d() or surf():

function plotSample()
    e = gce();
    e.color_flag = 1;
    e.color_mode = -2;

gcf().color_map = rainbowcolormap(200);
gcf().axes_size = [800 300];

// 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap

// 5.2) Consistent U/colors fractional selection (top 40%)
colorbar(,,[0.6 1]);

gcf().children([2 4]).rotation_angles = [55 45];

Example #6: Demo


See also

  • colormap — using colormaps
  • Matplot — 2D plot of a matrix using colors
  • Sgrayplot — smooth 2D plot of a surface using colors
  • surf — 3D surface plot
  • Cformat rules — mprintf, msprintf, mfprintf conversion specifications


  • colorbar() syntax added.
  • implicit umin or/and umax values can now be infered either from actual U data values, or from colminmax and the colormap size.
  • colminmax bounds can now be specified as fractions of the colormap size.
  • umin=-%inf and umax=%inf semantics are now available.
Scilab Enterprises
Copyright (c) 2011-2017 (Scilab Enterprises)
Copyright (c) 1989-2012 (INRIA)
Copyright (c) 1989-2007 (ENPC)
with contributors
Last updated:
Thu Feb 14 14:59:58 CET 2019