contourm

Project 2-D contour plot of map data

Syntax

contourm(Z,R)

contourm(lat,lon,Z)

contourm(___,n)

contourm(___,V)

contourm(___,linetype)

contourm(___,Name,Value)

C = contourm(___)

[C,h] = contourm(___)

Description

contourm(Z,R) creates a contour plot of the regular data grid Z with geographic reference R.

contourm(lat,lon,Z) displays a contour plot of the geolocated data grid, Z with geolocation defined by lat and lon.

contourm(___,n) draws n contour levels.

contourm(___,V) draws contours at the levels specified by V.

contourm(___,linetype) specifies the line style and color for the contours.

contourm(___,Name,Value) allows you to set optional parameters. Parameter names can be abbreviated, and case does not matter. In addition, any of the following hggroup properties can be specified: 'HandleVisibility', 'Parent', 'Tag', 'UserData', and 'Visible'.

C = contourm(___) returns a standard contour matrix C, with the first row representing longitude data and the second row representing latitude data.

[C,h] = contourm(___) returns the contour matrix and the handle to the contour patches drawn onto the current axes. The handle is of type hggroup.

Examples

Display Contours for EGM96 Geoid Heights

Get geoid heights and a geographic postings reference object from the EGM96 geoid model.

[N,R] = egm96geoid;

Create a contour plot of the geoid data. Add axis labels and a legend.

[c,h] = contourm(N,R,'LevelStep',20,'ShowText','on');
xlabel('Longitude')
ylabel('Latitude')
clegendm(c,h,-1)

Display Contour Geoid Heights for Area Including Korea

Contour geoid heights for an area including Korea with a backdrop of terrain elevations and bathymetry.

Get elevation and geoid height data for an area around the Korean peninsula.

load korea5c
N = egm96geoid(korea5cR);

Create a map axes object with appropriate limits. Then, display the elevation data. Apply a colormap.

figure
worldmap(korea5cR.LatitudeLimits,korea5cR.LongitudeLimits)
geoshow(korea5c,korea5cR,'DisplayType','texturemap')
demcmap(korea5c)

Display contours of the geoid values from -100 to 100 in increments of 5.

[c,h] = contourm(N,korea5cR,-100:5:100,'k');

Add red labels with white backgrounds to the contours.

t = clabelm(c,h);
set(t,'Color','r')
set(t,'BackgroundColor','white')
set(t,'FontWeight','bold')

Input Arguments

Z — Regular or geolocated data grid

M-by-N matrix

Regular or geolocated data grid, specified as an M-by-N matrix.

If the grid contains regions with missing data, set the corresponding elements of Z to NaN. Contour lines terminate when entering such areas. Similarly, if you use 'Fill','on' or call contourfm, such null-data areas will not be filled. If you use the syntax contourm(lat,lon,Z,...), however, lat and lon must have finite, non-NaN values everywhere. In this case, set Z to NaN in null data areas, but make sure the corresponding elements of lat and lon have finite values that specify actual locations on the Earth.

R — Geographic reference

geographic raster reference object | vector | matrix

Geographic reference, specified as one of the following. For more information about referencing vectors and matrices, see Georeferenced Raster Data.

Type	Description
Geographic raster reference object	GeographicCellsReference or GeographicPostingsReference geographic raster reference object. The RasterSize property must be consistent with the size of the data grid, size(Z).
Vector	1-by-3 numeric vector with elements: [cells/degree northern_latitude_limit western_longitude_limit]
Matrix	3-by-2 numeric matrix that transforms raster row and column indices to or from geographic coordinates according to: [lon lat] = [row col 1] * R R defines a (non-rotational, non-skewed) relationship in which each column of the data grid falls along a meridian and each row falls along a parallel. For more information about referencing vectors and matrices, see Georeferenced Raster Data. If the current axis is a map axis, the coordinates of Z are projected using the projection structure from the axis. The contours are drawn at their corresponding Z level.

lat, lon — Geolocation array

M-by-N matrix | M-element vector

Geolocation array with latitude or longitude coordinates, specified as a matrix of the same size as Z, or a vector with length matching the number of rows in Z.

n — Number of contour levels

numeric scalar

Number of contour levels, specified as a numeric scalar.

V — Value of contour levels

numeric vector

Value of contour levels, specified as a numeric vector with length greater than or equal to two. Use V = [v v] to compute a single contour at level v.

linetype — Line style and color

character vector | string

Line style and color, specified as a character vector or string containing symbols. The symbols can appear in any order. You do not need to specify both characteristics (line style and color).

Example: '--r' is a red dashed line

Line Style	Description	Resulting Line
'-'	Solid line
'--'	Dashed line
':'	Dotted line
'-.'	Dash-dotted line

Color Name	Short Name	Appearance
'red'	'r'
'green'	'g'
'blue'	'b'
'cyan'	'c'
'magenta'	'm'
'yellow'	'y'
'black'	'k'
'white'	'w'

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: 'LabelSpacing',72

Fill — Color areas between contour lines

'off' (default) | 'on'

Color areas between contour lines, specified as the comma-separated pair consisting of 'Fill' and 'off' or 'on'. By default contourm draws a line (which may have multiple parts) for each contour level. If you set Fill to 'on', then contourm colors the polygonal regions between the lines, selecting a distinct color for each contour interval from the colormap of the figure in which the contours are drawn. Setting Fill to 'on' is almost the same as calling contourfm; the only difference is that contourfm also sets LineColor to black by default.

LabelSpacing — Spacing between labels

numeric scalar

Spacing between labels on each contour line, specified as the comma-separated pair consisting of 'LabelSpacing' and a numeric scalar. When you display contour line labels either by calling clabelm or by specifying 'ShowText','on', the labels by default are spaced 144 points (2 inches) apart on each line. You can specify the spacing by setting LabelSpacing to a value in points. If the length of an individual contour line is less than the specified value, only one contour label is displayed on that line.

LevelList — Values at which contour lines are drawn

numeric vector

Values at which contour lines are drawn, specified as the comma-separated pair consisting of 'LevelList' and a numeric vector. This property uses a row vector of increasing values to specify the levels at which contour lines are drawn.

LevelStep — Spacing of contour lines

positive real scalar

Spacing of contour lines, specified as the comma-separated pair consisting of 'LevelStep' and a numeric scalar. The contourm function draws contour lines at regular intervals determined by the value of LevelStep, unless the optional third argument, n (number of contour levels) or V (vector specifying contour levels) is provided. If n or V is used in combination with the LevelStep parameter, then the LevelStep parameter is ignored. If n, V, and the LevelStep parameter are all omitted, contourm selects a uniform step automatically.

LineColor — Contour line colors

'flat' (default) | RGB triplet | 'r' | 'g' | 'b' | 'none' | ...

Contour line colors, specified as the comma-separated pair consisting of 'LineColor' and 'flat', a color name, a short name, an RGB triplet, or 'none'. The default value of 'flat' selects a distinct color for lines at each contour level from the colormap of the figure in which the contours are drawn. The value 'none' applies no color to the lines.

For a custom color, specify an RGB triplet. 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].

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

Color Name	Short Name	RGB Triplet	Appearance
'red'	'r'	[1 0 0]
'green'	'g'	[0 1 0]
'blue'	'b'	[0 0 1]
'cyan'	'c'	[0 1 1]
'magenta'	'm'	[1 0 1]
'yellow'	'y'	[1 1 0]
'black'	'k'	[0 0 0]
'white'	'w'	[1 1 1]

LineStyle — Line style for contour lines

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

Line style for contour lines, specified as the comma-separated pair consisting of 'LineStyle' and '-' (solid), '--' (dashed), ':' (dotted), '-.' (dash-dot), or 'none'. The specifiers work the same as for line objects in MATLAB^® graphics.

LineWidth — Width of contour lines in points

0.5 (default) | numeric scalar

Width of contour lines in points, specified as the comma-separated pair consisting of 'LineWidth' and a numeric scalar. 1 point = 1/72 inch.

ShowText — Flag to display labels on contour lines

'off' (default) | 'on'

Flag to display labels on contour lines, specified as the comma-separated pair consisting of 'ShowText' and 'off' or 'on'. If you set ShowText to 'on', contourm displays text labels on each contour line indicating the value of the corresponding contour level. Another way to add labels to your contour lines is to call clabelm after calling contourm.

Output Arguments

C — Contour matrix

numeric matrix

Standard contour matrix, returned as a matrix with two rows. The first row represents longitude data and the second row represents latitude data.

h — Handle of contour patches

hggroup

Handle to the contour patches drawn onto the current axes, returned as an hggroup.

Tips

• You have three ways to control the number of contour levels that display in your map:

  1. Set the number of contour levels by specifying the scalar n in the syntax contourm(Z,R,n) or contourm(lat,lon,Z,n).

  2. Use the vector V to specify the levels at which contours are drawn with the syntax contourm(Z,R,V) or contourm(lat,lon,Z,V).

  3. Choose regular intervals at which the contours are drawn by setting the LevelStep parameter.

  If you do not use any of the above methods to set your contour levels, the contourm function displays around five contour levels.

Version History

Introduced before R2006a