contourfm

Project filled 2-D contour plot of map data

collapse all in page

Syntax

contourfm(Z,R)

contourfm(lat,lon,Z)

contourfm(___,levels)

contourfm(___,LineSpec)

contourfm(___,Name,Value)

C = contourfm(___)

[C,h]
= contourfm(___)

Description

contourfm(Z,R) creates a filled contour plot of the regular data grid Z that is spatially referenced by the geographic raster reference object R.

example

contourfm(lat,lon,Z) creates a filled contour plot of the geolocated data grid Z that is referenced to the latitude-longitude coordinates contained in lat and lon.

contourfm(___,levels) specifies the contour lines to display, in addition to any combination of arguments from the previous syntaxes.

example

contourfm(___,LineSpec) specifies the style and color of the contour lines.

contourfm(___,Name,Value) specifies additional options for the contour plot using one or more name-value arguments.

C = contourfm(___) returns the contour matrix C, which contains the latitude and longitude coordinates of the vertices at each level.

[C,h] = contourfm(___) returns the contour matrix and the contour patches h.

Examples

collapse all

Create Filled Contour Plot

Open Live Script

Create a sample data grid and geographic raster reference object. Then, display the data using a filled contour plot.

Z = peaks;
R = georefcells([-0.1 0],[0 0.1],size(Z));

figure
axesm miller
axis off

contourfm(Z,R)

Figure contains an axes object. The hidden axes object contains 17 objects of type patch, line.

Specify Number of Contour Levels

Open Live Script

Create a sample data grid and geographic raster reference object. Then, display contours at 10 levels of Z.

Z = peaks;
R = georefcells([-0.1 0],[0 0.1],size(Z));

figure
axesm miller
axis off

contourfm(Z,R,10)

Figure contains an axes object. The hidden axes object contains 21 objects of type patch, line.

Specify Contour Levels

Open Live Script

Read global elevation data into the workspace. Crop the data to a region that includes North America.

load topo60c
[Z,R] = geocrop(topo60c,topo60cR,[10 85],[-170 -45]);

Find the minimum and maximum elevations.

min(min(Z))

ans = 
-7258

max(max(Z))

ans = 
3047

Display the data on a map using a filled contour plot. Specify the minimum and maximum contours using values that surround the minimum and maximum elevations, and specify a new contour level every 1000 meters.

worldmap(Z,R)

minL = -8000;
inc = 1000;
maxL = 4000;

levels = minL:inc:maxL;
contourfm(topo60c,topo60cR,levels)

Set the colormap limits and add a color bar.

clim([minL maxL])
c = contourcbar;
c.Ticks = levels;

Figure contains an axes object. The hidden axes object contains 33 objects of type patch, line, text.

Create Filled Contour Plot from Multiple Data Grids

Since R2024a

Open Live Script

Create a filled contour plot from multiple adjacent data grids by merging the grids.

Read elevation data from two DTED files into the workspace. Merge the data by using the mergetiles function.

[Z1,R1] = readgeoraster("w106/n39.dt0",OutputType="double");
[Z2,R2] = readgeoraster("w106/n40.dt0",OutputType="double");
[Z,R] = mergetiles(Z1,R1,Z2,R2);

Create a map of the region. Calculate five evenly-spaced contour levels from the minimum and maximum elevation values. Then, display filled contours using the contour levels.

figure
usamap(Z,R)

minZ = min(Z,[],"all");
maxZ = max(Z,[],"all");
levels = linspace(minZ,maxZ,5);

contourfm(Z,R,levels)

Change the colormap. Add a labeled color bar. Specify the tick labels of the color bar using the contour levels.

colormap summer

c = contourcbar;
c.Label.String = "Elevation (m)";
c.Ticks = levels;

Figure contains an axes object. The hidden axes object contains 21 objects of type patch, line, text.

This example uses modified data from the US Geological Survey.

Input Arguments

collapse all

`Z` — Regular or geolocated data grid
M-by-N matrix

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

The contourfm function does not display contour lines for elements of Z that have values of NaN.

`R` — Spatial reference
`GeographicCellsReference` object | `GeographicPostingsReference` object

Spatial reference for Z, specified as a GeographicCellsReference or GeographicPostingsReference object. The RasterSize property of R must be consistent with size(Z).

`lat` — Latitude coordinates
M-by-N matrix | M-element vector

Latitude coordinates, specified as an M-by-N matrix or an M-element vector.

This argument does not support NaN values. To indicate missing data, set the corresponding element of Z to a value of NaN, instead.

`lon` — Longitude coordinates
M-by-N matrix | M-element vector

Longitude coordinates, specified as an M-by-N matrix or an M-element vector.

This argument does not support NaN values. To indicate missing data, set the corresponding element of Z to a value of NaN, instead.

`levels` — Contour levels
positive integer | numeric vector

Contour levels, specified as a positive integer or a numeric vector.

To display contour lines at n automatically chosen levels, specify this argument as n. The function chooses levels based on the values in Z.
To display contour lines at specific levels, specify this argument as a vector of increasing values.
To display contour lines at a single level, k, specify this argument as a two-element row vector [k k].

`LineSpec` — Line style and color
character vector | string scalar

Line style and color, specified as a character vector or string scalar containing characters and symbols. The characters and symbols can appear in any order. You can specify the line style, line color, or both. Marker symbols such as 'o' are ignored.

Example: '--g' is a green 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.

Example: contourfm(Z,R,ShowText="on") displays the contour line labels.

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

Example: contourfm(Z,R,"ShowText","on") displays the contour line labels.

Note

In addition to the name-value arguments in this section, you can use name-value arguments to specify values for the HandleVisibility, Parent, Tag, UserData, and Visible properties of the Group object returned by this function. For more information about these group object properties, see Group Properties.

`LabelSpacing` — Label spacing
`144` (default) | scalar

Label spacing along the contour lines, specified as a scalar value in points, where one point is 1/72 inch. Use this property to control the number of contour labels along the contour lines. Smaller values produce more labels.

You must specify ShowText as "on" for LabelSpacing to have an effect.

If the length of a contour line is less than LabelSpacing, then the function displays one label on the line.

`LevelList` — Contour levels
row vector of increasing values in `Z`

Contour levels, specified as a row vector of increasing values in Z. By default, the contourfm function chooses values that span the range of values in Z.

`LevelStep` — Spacing between contour lines
positive scalar

Spacing between the contour lines, specified as a positive scalar. For example, specify a value of 2 to display contour lines at increments of 2. By default, the contourfm function determines the spacing based on the values in Z. If you specify both levels and LevelStep, then the function ignores LevelStep.

`LineColor` — Color of contour lines
`"flat"` (default) | RGB triplet | `"r"` | `"g"` | `"b"` | `"none"` | ...

Color of the contour lines, specified as "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
`"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
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

Line style, specified as one of the options listed in this table.

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

`LineWidth` — Line width
`0.5` (default) | positive scalar

Contour line width, specified as a positive scalar in points. One point equals 1/72 inch.

`ShowText` — Contour line labels
`"off"` (default) | `"on"`

Contour line labels, specified as one of these values:

"on" — Display the contour level along the contour lines.
"off" — Do not label the contour lines.

Output Arguments

collapse all

`C` — Contour matrix
matrix with two rows

Contour matrix, returned as a matrix with two rows. This argument contains the data that defines the contour lines. The first row of the matrix contains longitude data and the second row of the matrix contains latitude data.

`h` — Contour patches
`Group` object

Contour patches, returned as a Group object.

Tips

The contourfm function behaves the same as the contourm function, except the contourfm function fills the spaces between the contour lines with color. For each contour interval, the contourfm function selects a distinct color from the colormap for the figure. You can obtain the same result with the contourm function by specifying the Fill name-value argument as "on" and the LineColor name-value argument as "black".

Version History

Introduced before R2006a

expand all

R2024b: `contourfm` does not accept referencing vectors or referencing matrices as input

The contourfm function does not accept referencing vectors or referencing matrices as input. Use a geographic raster reference object, specified as a GeographicCellsReference or GeographicPostingsReference object, as input instead. Reference objects have several advantages over referencing vectors and referencing matrices.

Unlike referencing vectors and referencing matrices, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns.
You can manipulate the limits of geographic rasters associated with reference objects using the geocrop function.
You can manipulate the size and resolution of geographic rasters associated with reference objects using the georesize function.

To update your code, create a geographic reference object.

Create a geographic reference object for a raster of cells by using the georefcells function.
Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.
Convert from a referencing vector to a geographic reference object by using the refvecToGeoRasterReference function.
Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

R2023b: `contourfm` will not accept referencing vectors or referencing matrices as input

When you specify a referencing vector or referencing matrix as input, the contourfm function issues a warning that it will not accept referencing vectors or referencing matrices as input in a future release.

contourfm

Syntax

Description

Examples

Create Filled Contour Plot

Specify Number of Contour Levels

Specify Contour Levels

Create Filled Contour Plot from Multiple Data Grids

Input Arguments

`Z` — Regular or geolocated data grid
M-by-N matrix

`R` — Spatial reference
`GeographicCellsReference` object | `GeographicPostingsReference` object

`lat` — Latitude coordinates
M-by-N matrix | M-element vector

`lon` — Longitude coordinates
M-by-N matrix | M-element vector

`levels` — Contour levels
positive integer | numeric vector

`LineSpec` — Line style and color
character vector | string scalar

Name-Value Arguments

`LabelSpacing` — Label spacing
`144` (default) | scalar

`LevelList` — Contour levels
row vector of increasing values in `Z`

`LevelStep` — Spacing between contour lines
positive scalar

`LineColor` — Color of contour lines
`"flat"` (default) | RGB triplet | `"r"` | `"g"` | `"b"` | `"none"` | ...

`LineStyle` — Line style
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

`LineWidth` — Line width
`0.5` (default) | positive scalar

`ShowText` — Contour line labels
`"off"` (default) | `"on"`

Output Arguments

`C` — Contour matrix
matrix with two rows

`h` — Contour patches
`Group` object

Tips

Version History

R2024b: `contourfm` does not accept referencing vectors or referencing matrices as input

R2023b: `contourfm` will not accept referencing vectors or referencing matrices as input

See Also

Functions

contourfm

Syntax

Description

Examples

Create Filled Contour Plot

Specify Number of Contour Levels

Specify Contour Levels

Create Filled Contour Plot from Multiple Data Grids

Input Arguments

Z — Regular or geolocated data grid M-by-N matrix

R — Spatial reference GeographicCellsReference object | GeographicPostingsReference object

lat — Latitude coordinates M-by-N matrix | M-element vector

lon — Longitude coordinates M-by-N matrix | M-element vector

levels — Contour levels positive integer | numeric vector

LineSpec — Line style and color character vector | string scalar

Name-Value Arguments

LabelSpacing — Label spacing 144 (default) | scalar

LevelList — Contour levels row vector of increasing values in Z

LevelStep — Spacing between contour lines positive scalar

LineColor — Color of contour lines "flat" (default) | RGB triplet | "r" | "g" | "b" | "none" | ...

LineStyle — Line style "-" (default) | "--" | ":" | "-." | "none"

LineWidth — Line width 0.5 (default) | positive scalar

ShowText — Contour line labels "off" (default) | "on"

Output Arguments

C — Contour matrix matrix with two rows

h — Contour patches Group object

Tips

Version History

R2024b: contourfm does not accept referencing vectors or referencing matrices as input

R2023b: contourfm will not accept referencing vectors or referencing matrices as input

See Also

Functions

`Z` — Regular or geolocated data grid
M-by-N matrix

`R` — Spatial reference
`GeographicCellsReference` object | `GeographicPostingsReference` object

`lat` — Latitude coordinates
M-by-N matrix | M-element vector

`lon` — Longitude coordinates
M-by-N matrix | M-element vector

`levels` — Contour levels
positive integer | numeric vector

`LineSpec` — Line style and color
character vector | string scalar

`LabelSpacing` — Label spacing
`144` (default) | scalar

`LevelList` — Contour levels
row vector of increasing values in `Z`

`LevelStep` — Spacing between contour lines
positive scalar

`LineColor` — Color of contour lines
`"flat"` (default) | RGB triplet | `"r"` | `"g"` | `"b"` | `"none"` | ...

`LineStyle` — Line style
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

`LineWidth` — Line width
`0.5` (default) | positive scalar

`ShowText` — Contour line labels
`"off"` (default) | `"on"`

`C` — Contour matrix
matrix with two rows

`h` — Contour patches
`Group` object

R2024b: `contourfm` does not accept referencing vectors or referencing matrices as input

R2023b: `contourfm` will not accept referencing vectors or referencing matrices as input