Change language to:
English - 日本語 - Português - Русский

Please note that the recommended version of Scilab is 2024.1.0. This page might be outdated.
See the recommended documentation of this function

Aide de Scilab >> Graphiques > Couleurs > colorbar

# colorbar

draws a vertical color bar

### Syntax

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

### Arguments

• 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)`.

umin

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).

umax

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

`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.

Cformat

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

### Description

`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:

colorbar()

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.

### Examples

##### 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.
gca().axes_bounds

// 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.type
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  =
0.5

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

--> ...
--> // 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  =
Axes

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

After Matplot() here used with the default colormap.

```clf reset   // Default colormap used
// 1) Matplot: implicit minU, maxU, colminmax = [umin umax]
subplot(2,2,1)
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]
subplot(2,2,2)
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
subplot(2,2,3)
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;
clf
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

colorbar
// 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
subplot(1,2,1)
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]:
subplot(1,2,2)
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];
deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
"y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
"z=r*sin(alp)+orig(3)*ones(tet)"]);
[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])
endfunction

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
subplot(2,2,1)
plotSphere();
colorbar;               // graduations on [-0.3 0.3]

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

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

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

##### Example #5 : Plot3d object

After plot3d() or surf():

```function plotSample()
t=[-4:0.1:4];
plot3d(t,t,sin(t)'*cos(t));
e = gce();
e.color_flag = 1;
e.color_mode = -2;
endfunction

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

// 5.1) Bar graduated from minU=-1 to maxU=1 with the full colormap
subplot(1,2,1)
plotSample();
colorbar;

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

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

##### Example #6: Demo

`exec("SCI/modules/graphics/demos/colormap/colormaps.dem.sce",-1)`