Displaying Vector Data with Mapping Toolbox Functions :: Creating and Viewing Maps (Mapping Toolbox™)

Displaying Vector Data with Mapping Toolbox Functions

On this page…
Programming and Scripting Map Construction Displaying Vector Data as Points and Lines Displaying Vector Maps as Lines or Patches

On this page…

Programming and Scripting Map Construction

Displaying Vector Data as Points and Lines

Displaying Vector Maps as Lines or Patches

Programming and Scripting Map Construction

Although mapview, maptool, and other Mapping Toolbox GUIs are convenient and quick tools for making maps, most mapping applications require additional effort. By using and combining Mapping Toolbox and MATLAB functions, you can create and customize more elaborate maps interactively by entering commands in the Command Window or by writing M-code in functions and scripts. This section describes how to use the principal mapping functions for displaying vector geospatial data. The following section describes displaying raster map data.

Displaying Vector Data as Points and Lines

Mapping Toolbox vector map display of line objects works much like MATLAB line display functions. Mapping Toolbox line graphics functions have MATLAB analogs, the names of which can usually be determined by appending an m to the MATLAB function name. For instance, the Mapping Toolbox version of plot is plotm. The main difference between the two classes of functions comes from the need for Mapping Toolbox functions to work with geographic coordinates and map projections.

The following table lists the available Mapping Toolbox line display functions.

Function	Used For
`contourm`	Contour plot of map data
`contour3m`	Contour plot of map data in 3-D space
`geoshow`	High-level function to plot points, lines, patches, grids, and georeferenced images in geocoordinates
`linem`	Draws line objects projected on map axes
`mapshow`	High-level function to plot points, lines, patches, grids, and georeferenced images in plane coordinates
`plotm`	Clears figure and draws line objects projected on map axes
`plot3m`	Projects lines on map axes in 3-D space

The following exercise shows how some of these functions work:

Set up a map axes and frame:

load coast
axesm mollweid
framem('FEdgeColor','blue','FLineWidth',0.5)

Plot the coast vector data using plotm. Just as with plot, you can specify line property names and values in the command.
```
plotm(lat,long,'LineWidth',1,'Color','blue')
```
Sometimes vector data represents specific points. Suppose you have variables representing the locations of Cairo (30ºN,32ºE), Rio de Janeiro (23ºS,43ºW), and Perth (32ºS,116ºE), and you want to plot them as markers only, without connecting line segments.

Define the three city geographic locations and plot symbols at them:

citylats = [30 -23 -32]; citylongs = [32 -43 116];
plotm(citylats,citylongs,'r*')

In addition to these sorts of "permanent" geographic data, you can also display calculated vector data. Calculate and plot a great circle track from Cairo to Rio de Janeiro, and a rhumb line track from Cairo to Perth:

[gclat,gclong] = track2('gc',citylats(1),citylongs(1),...
                             citylats(2),citylongs(2));
[rhlat,rhlong] = track2('rh',citylats(1),citylongs(1),...
                             citylats(3),citylongs(3));
plotm(gclat,gclong,'m-'); plotm(rhlat,rhlong,'m-')

Note You can also use geoshow (for data in geographic coordinates) or mapshow (for data in projected coordinates) to create such maps, either in a map axes or in a regular axes. Both functions accept either vectors of coordinates or geographic data structures as input data.

For more information, see Mapping Toolbox Geographic Data Structures, which includes examples of creating geostructs and displaying their contents in How to Construct Geostructs and Mapstructs.

Displaying Vector Maps as Lines or Patches

Vector map data that is properly formatted (i.e., as closed polygons) can be displayed as patches, or filled-in polygons. In addition, it and other vector data can be displayed as lines.

Note The Mapping Toolbox patch display functions differ from their MATLAB equivalents by allowing you to display patch vector data that uses NaNs to separate closed regions.

Vector map data for lines or polygons can be represented by simple coordinate arrays, geostructs, or mapstructs. This example illustrates the use of coordinate arrays for both line and polygon features as well as a geostruct containing line features.

The conus (conterminous U.S.) MAT-file nicely illustrates how polygon data is structured, manipulated, and displayed. Use who to see what it contains before loading it.
```
who -file conus.mat

Your variables are:
description  gtlakelon    statelat     uslat
gtlakelat    source       statelon     uslon

load conus
```
The variables uslat and uslon together describe three polygons (separated by NaNs), the largest of which represents the outline of the conterminous United States. The two smaller polygons represent Long Island, NY, and Martha's Vineyard, an island off Massachusetts. The variables gtlakelat and gtlakelon describe three polygons (separated by NaNs) for the Great Lakes. The variables statelat and statelon contain line-segment data (separated by NaNs) for the borders between states, which is not formatted for patch display.
Verify that line and polygon data contains NaNs (hence multiple objects) by typing a command similar to find(isnan(vector)):
```
find(isnan(gtlakelon)) %or gtlakelat
ans =

         883
        1058
        1229
```
The find command returns three values indicating that the gtlakelon (or gtlakelat) geographic coordinate arrays contain three polygons representing one or a group of Great Lakes.

Read the worldrivers shapefile for the region that covers the conterminous United States. This data, stored as a geographic data structure, is useful for illustrating lines.

uslatlim = [min(uslat) max(uslat)]
uslatlim =

   25.1200   49.3800

uslonlim = [min(uslon) max(uslon)]
uslonlim =

 -124.7200  -66.9700

rivers = shaperead('worldrivers', 'UseGeoCoords', true, ...
    'BoundingBox', [uslonlim', uslatlim'])
rivers = 

23x1 struct array with fields:
    Geometry
    BoundingBox
    Lon
    Lat
    Name

The struct rivers is a geographic data structure having five fields. Note that the Geometry field specifies whether the data is stored as a 'Point', 'MultiPoint', 'Line', or a 'Polygon':
```
rivers(1).Geometry

ans =
    Line
```
For further details on Mapping Toolbox geographic data structures, see Understanding Vector Geodata and Understanding Raster Geodata.

Now you can set up a map axes to display the state coordinates. As conic projections are appropriate for mapping the entire United States, create a map axes object using an Albers equal-area conic projection ('eqaconic'). Specifying map limits that contain the region of interest automatically centers the projection on an appropriate longitude; the frame encloses just the mapping area, not the entire globe. As a general rule, you should specify map limits that extend slightly outside your area of interest (worldmap and usamap do this for you).

Note Conic projections need two standard parallels (latitudes at which scale distortion is zero). A good rule is to set the standard parallels at one-sixth of the way from both latitude extremes. Or, to use default latitudes for the standard parallels, simply provide an empty matrix in the call to axesm.

The three options that follow demonstrate how you can set map latitude and longitude limits to axesm:

Obtain default latitudes by providing an empty matrix as the standard parallels:

figure
axesm('MapProjection','eqaconic', 'MapParallels',[],...
      'MapLatLimit',[23 52], 'MapLonLimit',[-130 -62])

If you do not know what latitude and longitude limits are appropriate for your map, as a starting point you could use the exact ones that the geostruct contains. Using them eliminates white space around the map:
```
axesm('MapProjection','eqaconic', 'MapParallels',[],...
      'MapLatLimit',uslatlim, 'MapLonLimit',uslonlim)
```

If you want to add white space around the map, you can do so as follows (here, 2 degrees are added):

axesm('MapProjection', 'eqaconic', 'MapParallels', [], ...
      'MapLatLimit', uslatlim + [-2 2], ...
      'MapLonLimit', uslonlim + [-2 2])

Turn on the map frame, the map grid, and the meridian and parallel labels:
```
axis off; framem; gridm; mlabel; plabel
```
The empty map looks like this.
When geographic data is displayed, some layers can hide others. You can control the visibility of your map layers by varying the order in which you display them. For example, some U.S. state boundaries follow major rivers, so display the rivers last to avoid obscuring the rivers with the boundaries.
The coordinate array pairs (uslat, uslon), (gtlakelat, gtlakelon), and (statelat, statelon) simply contain sequences of NaN-separated map segments, and their geometric interpretation is ambiguous. In order to display them appropriately as either patches or lines with geoshow, you need to use the DisplayType parameter. In contrast, DisplayType is not needed when you map data from a geostruct like rivers.
1. Plot a patch to display the area occupied by the conterminous United States; use the geoshow function with a 'polygon' DisplayType:
```
geoshow(uslat,uslon, 'DisplayType','polygon','FaceColor',...
    [1 .5 .3], 'EdgeColor','none')
```
2. Plot the Great Lakes on top of the land area, using geoshow again:
```
geoshow(gtlakelat,gtlakelon, 'DisplayType','polygon',...
    'FaceColor','cyan', 'EdgeColor','none')
```
3. Plot the line segment data showing state boundaries, using geoshow with a 'line' DisplayType:
```
geoshow(statelat,statelon,'DisplayType','line','Color','k')
```
4. Finally, use geoshow to plot the river network. Note that you can omit DisplayType:
```
geoshow(rivers, 'Color', 'blue')
```

Summary of Polygon Mapping Functions

The following table lists the available Mapping Toolbox patch polygon display functions.

Function	Used For
`fillm`	Filled 2-D map polygons
`fill3m`	Filled 3-D map polygons in 3-D space
`geoshow`	Display map latitude and longitude data in 2-D
`mapshow`	Display map data without projection in 2-D
`patchm`	Patch objects projected on map axes
`patchesm`	Patches projected as individual objects on map axes

The fillm function makes use of the low-level function patchm. The toolbox provides another patch drawing function called patchesm. The optimal use of either depends on the application and user preferences. The patchm function creates one displayed object and returns one handle for a patch, which can contain multiple faces that do not necessarily connect. Mapping Toolbox data arrays contain NaNs to separate unconnected patch faces, unlike MATLAB patch display functions, which cannot handle NaN-delimited data for patches. The patchesm function, on the other hand, treats each face as a separate object and returns an array containing a handle for each patch. In general, patchm requires more memory but is faster than patchesm. The patchesm function is useful if you need to manipulate the appearance of individual patches (as thematic maps often require).

The geoshow and mapshow functions provide a superset of functionality for displaying unprojected and projected geodata, respectively, in two dimensions. These functions accept geographic data structures (geostructs and mapstructs) and coordinate vector arrays, but can also directly read shapefiles and geolocated raster files. With them, you can map polygon data, controlling rendering by constructing symbolspecs, data structures that you can construct with the makesymbolspec function. You can easily construct symbolspecs for point and line data as well as polygon data to control its display in geoshow, mapshow, and mapview.

Reprojectability of Maps with Vector Data. If you want to be able to change the projection of a map on the fly, you should not use geoshow. Some display functions, such as patchm , fillm, displaym, and linem, enable you to reproject vector map data, but geoshow does not. That is, when you change a map axes projection, with setm for example, vector map symbology that was created with geoshow will not be transformed. Gridded data rendered with geoshow (when DisplayType is surface, texturemap, or contour), however, can be reprojected.

Controlling Map Frames and Grids

Displaying Data Grids

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit