clabel

Label contour plot elevation

Syntax

clabel(C,h)

clabel(C,h,v)

clabel(C,h,'manual')

t = clabel(C,h,'manual')

clabel(C)

clabel(C,v)

clabel(C,'manual')

tl = clabel(___)

clabel(___,Name,Value)

Description

clabel(C,h) labels the current contour plot with rotated text inserted into each contour line. The contour lines must be long enough to fit the label, otherwise clabel does not insert a label. If you do not have the contour matrix C, then replace C with [].

clabel(C,h,v) labels the contour levels specified by vector v.

clabel(C,h,'manual') labels the locations you select with the mouse. Click the mouse or press the space bar to label the contour closest to the center of the crosshair. Press the Return key while the cursor is within the figure window to terminate labeling.

t = clabel(C,h,'manual') returns the text objects created.

clabel(C) labels contours with '+' symbols and upright text.

clabel(C,v) adds upright labels to the contour levels specified by the vector, v.

clabel(C,'manual') adds upright labels at the locations you select with the mouse. Click the mouse or press the space bar to label the contour closest to the center of the crosshair. Press the Return key while the cursor is within the figure window to terminate labeling.

tl = clabel(___) returns the text and line objects created. Use any of the input argument combinations in the previous syntaxes that do not include the contour object h.

clabel(___,Name,Value) modifies the label appearance using one or more Name,Value pair arguments. Use any of the input argument combinations in the previous syntaxes. For example, 'FontSize',14 sets the font size to 14 points.

Examples

Label Contour Plot Levels

Create a contour plot and obtain the contour matrix, C, and the contour object, h. Then, label the contour plot.

[x,y,z] = peaks;
[C,h] = contour(x,y,z);   
clabel(C,h)

Label Specific Contour Levels

Label only the contours with contour levels 2 or 6.

[x,y,z] = peaks;
[C,h] = contour(x,y,z);
v = [2,6];
clabel(C,h,v)

Set Contour Label Properties

Set the font size of the labels to 15 points and set the color to red using Name,Value pair arguments.

[x,y,z] = peaks;
[C,h] = contour(x,y,z);
clabel(C,h,'FontSize',15,'Color','red')

Set additional properties by reissuing the clabel command. For example, set the font weight to bold and change the color to blue.

clabel(C,h,'FontWeight','bold','Color','blue')

Set the font size back to the default size using the 'default' keyword.

clabel(C,h,'FontSize','default')

Label Contour Plot with Vertical Text

Create a contour plot and return the contour matrix, C. Then, label the contours.

[x,y,z] = peaks;
C = contour(x,y,z);  
clabel(C)

Input Arguments

C — Contour matrix

two-row matrix

Contour matrix returned by the contour, contour3, or contourf function. C contains the data that defines the contour lines. For more information on the contour matrix, see ContourMatrix.

Note

If you pass the contour object h to the clabel function, then you can replace C with []. For example, use clabel([],h).

h — Contour object

contour object

Contour object returned by the contour, contour3, or contourf function.

v — Contour level values

vector

Contour level values, specified as a row or column vector of individual values.

Example: [0 10 20]

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.

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

Example: clabel(C,h,'Color','red','FontSize',12) specifies red, 12-point labels.

clabel supports the LabelSpacing property plus a subset of text properties.

LabelSpacing — Space between labels

scalar

Space between labels, specified as a scalar value in point units.

Note

Use this option with either the clabel(C,h) or clabel(C,h,v) syntax. Other syntaxes do not support this option.

Example: clabel(C,h,'LabelSpacing',100)

Color — Text color

RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

Text color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of [0 0 0] corresponds to black.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: 'blue'

Example: [0 0 1]

Example: '#0000FF'

EdgeColor — Color of text box outline

'none' (default) | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

Color of text box outline, specified as 'none', an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: clabel(C,h,'EdgeColor','k')

BackgroundColor — Background color

'none' (default) | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

Color of text box background, specified as 'none', an RGB triplet, hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: clabel(C,h,'BackgroundColor','g')

FontSize — Font size

10 (default) | scalar value greater than 0

Font size, specified as a scalar value greater than 0. By default, the font size uses point units. One point equals 1/72 inch. However, some syntaxes allow you to change the font units using the FontUnits property.

Example: clabel(C,h,'FontSize',15)

FontName — Font name

supported font name | "FixedWidth"

Font name, specified as a supported font name or "FixedWidth". To display and print text properly, you must choose a font that your system supports. The default font depends on your operating system and locale.

To use a fixed-width font that looks good in any locale, use "FixedWidth". The fixed-width font relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

FontAngle — Character slant

'normal' (default) | 'italic'

Character slant, specified as 'normal' or 'italic'.

Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

FontWeight — Character thickness

'normal' (default) | 'bold'

Character thickness, specified as 'normal' or 'bold'.

MATLAB^® uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold weight. Therefore, specifying a bold font weight can still result in the normal font weight.

FontUnits — Font size units

'points' (default) | 'inches' | 'centimeters' | 'characters' | 'normalized' | 'pixels'

Font size units, specified as one of the values in this table.

Units	Description
'points'	Points. One point equals 1/72 inch.
'inches'	Inches.
'centimeters'	Centimeters.
'characters'	Based on the default system font character size. Character width = width of letter x. Character height = distance between the baselines of two lines of text.
'normalized'	Interpret font size as a fraction of the axes height. If you resize the axes, the font size modifies accordingly. For example, if the FontSize is 0.1 in normalized units, then the text is 1/10 of the axes height.
'pixels'	Pixels. On Windows® and Macintosh systems, the size of a pixel is 1/96th of an inch. This size is independent of your system resolution. On Linux® systems, the size of a pixel is determined by your system resolution.

If you set both the font size and the font units in one function call, you must set the FontUnits property first so that the axes correctly interprets the specified font size.

Note

The clabel(C,h) and clabel(C,h,v) syntaxes do not support this option. They always use the default value of points.

Example: clabel(C,'FontUnits','normalized')

Rotation — Text orientation

0 (default) | scalar

Text orientation, specified as a scalar value in degrees. The default rotation of 0 degrees makes the text horizontal. For vertical text, set this property to 90 or -90. Positive values rotate the text counterclockwise. Negative values rotate the text clockwise.

Note

The clabel(C,h) and clabel(C,h,v) syntaxes do not support this option. Instead, they insert rotated text into the contour lines, with each label rotated to match the local orientation of the corresponding line.

Example: clabel(C,'Rotation',90)

Interpreter — Interpretation of text characters

'tex' (default) | 'latex' | 'none'

Interpretation of text characters, specified as one of these values:

• 'tex' — Display text using TeX markup.

• 'latex' — Display text using LaTeX markup.

• 'none' — Display literal characters.

Since the labels are numeric text, the effect of this property is limited to subtle changes in the font style and weight.

Example: clabel(C,h,'Interpreter','latex')

LineStyle — Line style of text box outline

'-' (default) | '--' | ':' | '-.' | 'none'

Line style of text box outline, specified as one of the line styles in this table.

Line Style	Description	Resulting Line
"-"	Solid line
"--"	Dashed line
":"	Dotted line
"-."	Dash-dotted line
"none"	No line	No line

Example: clabel(C,h,'LineStyle','--')

LineWidth — Width of text box outline

0.5 (default) | scalar

Width of text box outline, specified as a scalar value in point units. One point equals 1/72 inch.

Example: clabel(C,h,'LineWidth',1)

Margin — Space around text within the text box

3 (default) | scalar

The space around the text within the text box, specified as scalar value in point units.

MATLAB uses the Extent property value plus the Margin property value to determine the size of the text box.

Example: clabel(C,h,'Margin',4)

Output Arguments

t — Text objects

vector

Text objects, returned as a vector. The String properties of the text objects contain the contour values displayed.

tl — Text and line objects

vector

Text and line objects, returned as a vector. The String properties of the text objects contain the contour values displayed. The line objects correspond to the '+' symbols.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The clabel function supports GPU array input with these usage notes and limitations:

• This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• This function operates on distributed arrays, but executes in the client MATLAB.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2025a: FontSmoothing property has no effect

The FontSmoothing property has no effect and will be removed in a future release. You can set or get the value of this property without warning, but all text is smooth regardless of the property value. This property removal was announced in R2022a.

R2023b: Setting Color name-value argument also sets LabelColor of Contour object

If you set the Color name-value argument when you call the clabel function, the LabelColor property of the Contour object updates to the specified color value.