Main Content

clabel

Label contour plot elevation

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 [].

example

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

example

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.

example

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.

example

Examples

collapse all

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)

Figure contains an axes object. The axes object contains an object of type contour.

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)

Figure contains an axes object. The axes object contains an object of type contour.

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

Figure contains an axes object. The axes object contains an object of type contour.

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

Figure contains an axes object. The axes object contains an object of type contour.

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

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

Figure contains an axes object. The axes object contains an object of type contour.

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)

Figure contains an axes object. The axes object contains 25 objects of type contour, line, text.

Input Arguments

collapse all

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

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

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.

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)

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 hexadecimal color codes.

Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

"none"Not applicableNot applicableNot applicableNo color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB® uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Example: 'blue'

Example: [0 0 1]

Example: '#0000FF'

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 hexadecimal color codes.

Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

"none"Not applicableNot applicableNot applicableNo color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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

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 hexadecimal color codes.

Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

"none"Not applicableNot applicableNot applicableNo color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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

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)

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.

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.

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.

Font smoothing, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

  • 'on' — Apply font smoothing. Reduce the appearance of jaggedness in the text characters to make the text easier to read.

  • 'off' — Do not apply font smoothing.

Example: clabel(C,h,'FontSmoothing','on')

Note

The FontSmoothing name-value argument will have no effect in a future release. Font smoothing will be enabled regardless of the value.

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

UnitsDescription
'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.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

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

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)

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

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

Line StyleDescriptionResulting Line
"-"Solid line

Sample of solid line

"--"Dashed line

Sample of dashed line

":"Dotted line

Sample of dotted line

"-."Dash-dotted line

Sample of dash-dotted line, with alternating dashes and dots

"none"No lineNo line

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

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)

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

collapse all

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

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

Version History

Introduced before R2006a

expand all

See Also

Functions

Properties