contourcbar

Color bar for filled contour map display

Syntax

contourcbar

contourcbar(location)

contourcbar(___,Name,Value)

contourcbar(ax,___)

c = contourcbar(___)

contourcbar("off")

contourcbar(ax,"off")

Description

Add Color Bar

contourcbar displays a vertical color bar to the right of the current axes. Color bars display the current colormap and indicate the mapping of data values into the colormap. If the current axes contains a contour object created by the contourm, contourfm, contour3m, or geoshow function, then the contourcbar function breaks the colormap into sections that correspond to the contour levels in the plot. Otherwise, the color bar displays the current colormap.

contourcbar(location) displays the color bar in a specific location, such as "northoutside".

contourcbar(___,Name,Value) modifies the color bar appearance using one or more name-value arguments, in addition to any combination of input arguments from the previous syntaxes. For example, "Direction","reverse" reverses the color scale.

contourcbar(ax,___) adds a color bar to the axes specified by ax. Specify the target axes as the first argument in any of the previous syntaxes.

c = contourcbar(___) returns the ColorBar object.

Remove Color Bar

contourcbar("off") deletes all color bars associated with the current axes.

contourcbar(ax,"off") deletes all color bars associated with the target axes.

Examples

Add Color Bar for Contoured Elevation Data

Create a filled contour plot of elevation and bathymetry data for North America. Specify a new contour level every 1000 meters.

load topo60c
worldmap("north america")
levels = -8000:1000:4000;
contourfm(topo60c,topo60cR,levels)

Set the colormap limits using the minimum and maximum contour levels. Then, add a color bar.

clim([min(levels) max(levels)])
contourcbar

Add Color Bar to Contour Plot with Non-Uniform Levels

Read spatially referenced geoid heights from the EGM96 geoid model. Display the data using a contour plot, specifying non-uniform contour levels.

worldmap world
plabel off
mlabel off

[N,R] = egm96geoid;
levels = [-70 -40 -20 -10 0 10 20 40 70];
contourfm(N,R,levels)

Specify the colormap limits using the minimum and maximum geoid heights. Then, add a labeled colorbar below the contour plot. Change the tick mark locations so they match the contour levels.

clim([min(min(N)) max(max(N))])
cb = contourcbar("southoutside");
cb.XLabel.String = "Geoid Heights in Meters";
cb.Ticks = levels;

Input Arguments

location — Location

"eastoutside" (default) | "north" | "south" | "east" | "west" | "northoutside" | ...

Location of the color bar with respect to the axes, specified as one of the values in this table.

Value	Resulting Location	Resulting Orientation
"north"	Top of axes	Horizontal
"south"	Bottom of axes	Horizontal
"east"	Right side of axes	Vertical
"west"	Left side of axes	Vertical
"northoutside"	Top outside of axes	Horizontal
"southoutside"	Bottom outside of axes	Horizontal
"eastoutside"	Right outside of axes (default)	Vertical
"westoutside"	Left outside of axes	Vertical

If a color bar already exists in the specified location, then an updated color bar replaces the existing one. To ensure that the color bar does not overlap the graph, specify a location with the suffix outside.

You also can set the color bar location using the Location property. For example, contourcbar("Location","northoutside") is the same as contourcbar("northoutside").

Example: contourcbar("westoutside")

ax — Target axes

Axes object

Target axes that contains the associated data visualization, specified as an Axes object. If you do not specify a target axes, then the function affects the current axes.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: contourcbar(FontSize=12,Direction="reverse") sets the font size to 12 and reverses the direction of the color scale

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: contourcbar("FontSize",12,"Direction","reverse") sets the font size to 12 and reverses the direction of the color scale

Note

Use name-value arguments to specify values for the properties of the ColorBar object created by this function. The properties listed here are only a subset. For a complete list, see ColorBar Properties.

Location — Location with respect to the axes

"eastoutside" (default) | "north" | "south" | "east" | "west" | "northoutside" | ...

Location with respect to the axes, specified as one of the values listed in this table.

Value	Resulting Location	Resulting Orientation
"north"	Top of axes	Horizontal
"south"	Bottom of axes	Horizontal
"east"	Right side of axes	Vertical
"west"	Left side of axes	Vertical
"northoutside"	Top outside of axes	Horizontal
"southoutside"	Bottom outside of axes	Horizontal
"eastoutside"	Right outside of axes (default)	Vertical
"westoutside"	Left outside of axes	Vertical
"manual"	Determined by Position property	Vertical

To display the color bar in a location that does not appear in the table, use the Position property to specify a custom location. If you specify the Position property, then MATLAB^® specifies the Location property as "manual". The associated axes does not resize to accommodate the color bar when the Location property is specified as "manual".

TickLabels — Tick mark labels

cell array of character vectors | string array | numeric array | character vector | categorical array

Tick mark labels, specified as a cell array of character vectors, a string array, a numeric array, a character vector, or a categorical array. By default, the color bar labels the tick marks with numeric values. If you specify labels and do not specify enough labels for all the tick marks, then, for the remaining tick marks, MATLAB cycles through the specified labels.

If you specify this property as a categorical array, MATLAB uses the values in the array, not the categories.

Example: {"cold","warm","hot"}

Ticks — Tick mark locations

vector of increasing numeric values

Tick mark locations, specified as a vector of increasing numeric values. The values do not need to be equally spaced. If you do not want tick marks displayed, then set the property to the empty vector, [].

Example: [-1 0 1 2 3 4 5]

Data Types: single | double

Direction — Direction of color scale

"normal" (default) | "reverse"

Direction of the color scale, specified as one of these values:

• "normal" — Display the colormap and labels ascending from bottom to top for a vertical color bar, and ascending from left to right for a horizontal color bar.

• "reverse" — Display the colormap and labels descending from bottom to top for a vertical color bar, and descending from left to right for a horizontal color bar.

FontSize — Font size

positive scalar

Font size, specified as a positive scalar in point units. The default font size depends on the specific operating system and locale.

If you change the axes font size, then MATLAB automatically sets the font size of the color bar to 90% of the axes font size. If you manually set the font size of the color bar, then changing the axes font size does not affect the color bar font.

Tips

• The contourcbar function supports the same syntaxes and options as the colorbar function.

• If the axes contains multiple contour objects created by the contourm, contourfm, contour3m, or geoshow function, then the contourcbar function divides the color bar into sections using the first contour object it finds in the axes.

• To add a text description along the color bar, access the underlying text object using the Label property of the color bar.

  c.Label.String = "My Colorbar Label";
  

  To change the label appearance, such as the font style or color, set other text properties. For a list of properties, see Text Properties. For example, this code changes the font size.

  c.Label.FontSize = 12;

• Adding a color bar might resize the axes to accommodate the color bar.

• If an axes does not exist, then the contourcbar function creates a blank axes and displays a color bar with the default colormap.

Version History

Introduced in R2011b

R2014b: "peer" input is not recommended

Starting in R2014b, contourcbar("peer",ax) is not recommended and might be removed in a future release. Use contourcbar(ax) instead.