mapshow - Display map data without projection

Syntax

mapshow(x,y) mapshow(x,y, ..., 'DisplayType', displaytype, ...) mapshow(x,y,z, ..., 'DisplayType', displaytype, ...) mapshow(Z,R, ..., 'DisplayType', displaytype,...) mapshow(x,y,I) mapshow(x,y,BW) mapshow(x,y,A,cmap) mapshow(x,y,RGB) mapshow(I,R) mapshow(BW,R) mapshow(RGB,R) mapshow(A,cmap,R) mapshow(s) mapshow(s,...,'SymbolSpec',symspec, ...) mapshow(filename) mapshow(..., param1, val1, param2, val2, ...) mapshow(ax, ...) mapshow(..., 'Parent', ax, ...) h = mapshow(...)

Description

mapshow(x,y) or mapshow(x,y, ..., 'DisplayType', displaytype, ...) displays the coordinate vectors x and y. x and y can contain embedded NaNs, delimiting individual lines or polygon parts. displaytype can be 'point', 'line', or 'polygon' and defaults to 'line'.

mapshow(x,y,z, ..., 'DisplayType', displaytype, ...) displays a geolocated data grid. x and y are M-by-N coordinate arrays, z is an M-by-N array of class double, and displaytype is 'surface', 'mesh', 'texturemap', or 'contour'. z can contain NaN values.

mapshow(Z,R, ..., 'DisplayType', displaytype,...) displays a regular data grid, Z. Z is class double and displaytype can be 'surface', 'mesh', 'texturemap', or 'contour'. R is a referencing matrix that relates the subscripts of Z to map coordinates. If DisplayType is 'texturemap', mapshow constructs a surface with ZData values set to 0.

mapshow(x,y,I), mapshow(x,y,BW), mapshow(x,y,A,cmap), and mapshow(x,y,RGB) display a geolocated image as a texturemap on a zero-elevation surface. x and y are geolocation arrays in map coordinates; I is a grayscale image, BW is a logical image, A is an indexed image with colormap cmap, or rgb is a truecolor image. x, y, and the image array must match in size. If specified, DisplayType must be set to 'image'. Examples of geolocated images include a color composite from a satellite swath or an image originally referenced to a different coordinate system.

mapshow(I,R), mapshow(BW,R), mapshow(RGB,R), and mapshow(A,cmap,R) display an image georeferenced to map coordinates through the referencing matrix R. It constructs an image object if the display geometry permits; otherwise, the image is shown as a texturemap on a zero-elevation surface. If specified, 'DisplayType' must be set to 'image'.

mapshow(s) or mapshow(s,...,'SymbolSpec',symspec, ...) display the vector geographic features stored in the geographic data structure s as points, multipoints, lines, or polygons according to the Geometry field of s. If s includes X and Y fields, then they are used directly to plot features in map coordinates. If Lat and Lon fields are present in s instead, the coordinates are projected using the Plate Carree projection and a warning is issued. symspec specifies the symbolization rules used for the vector data through a structure returned by makesymbolspec.

If s is a geostruct (has Lat and Lon fields), it may be more appropriate to use geoshow to display them. You can project latitude and longitude coordinate values to map coordinates by displaying with geoshow on a map axes.

mapshow(filename) displays data from filename, according to the type of file format. The DisplayType parameter is automatically set according to the following table:

Format	DisplayType
Shapefile	`'point'`, `'line'`, or `'polygon'`
GeoTIFF	`'image'`
TIFF/JPEG/PNG with a world file	`'image'`
ARC ASCII GRID	`'surface'` (can be overridden)
SDTS raster	`'surface'` (can be overridden)

mapshow(..., param1, val1, param2, val2, ...) specifies parameter/value pairs that modify the type of display or set MATLAB graphics properties. Parameter names can be abbreviated and are not case-sensitive. Refer to the MATLAB Graphics documentation on line, patch, image, surface, mesh, and contour Handle Graphics object properties for a complete description of these properties and their values.

mapshow(ax, ...) and mapshow(..., 'Parent', ax, ...) set the axes parent to ax.

h = mapshow(...) returns a handle to a MATLAB graphics object or, in the case of polygons, a modified patch object. If a mapstruct or shapefile name is input, mapshow returns the handle to an hggroup object with one child per feature in the mapstruct or shapefile. In the case of a polygon mapstruct or shapefile, each child is a modified patch object; otherwise it is a line object.

Parameters

Parameters for mapshow include

DisplayType: The DisplayType parameter specifies the type of graphic display for the data. The value must be consistent with the type of data being displayed, as shown in the following table:
Data Type
Value

vector
'point', 'line', or 'polygon'

image
'image'

grid
'surface', 'mesh', 'texturemap', or 'contour'
SymbolSpec: The SymbolSpec parameter specifies the symbolization rules used for vector data through a structure returned by makesymbolspec. It is used only for vector data.
When both SymbolSpec and one or more graphics properties are specified, the graphics properties will override any settings in the symbolspec structure.
To change the default symbolization rule for a property name/property value pair in the symbolspec, prefix the word 'Default' to the graphics property name (listed in the preceding table).

Data Type	Value
`vector`	`'point'`, `'line'`, or `'polygon'`
`image`	`'image'`
`grid`	`'surface'`, `'mesh'`, `'texturemap'`, or `'contour'`

If PropertyN is 'SymbolSpec', then ValueN must be symspec. symspec should conform to the structure returned by makesymbolspec.

When you use 'SymbolSpec'/symspec and other property name/property value pairs together, the property name/property value pairs override any settings in symspec.

Note If you display a polygon, do not set 'EdgeColor' to either 'flat' or 'interp'. This combination may result in a warning.

Graphics Properties

In addition to specifying a parent axes, you can set any appropriate property for a point, line, and polygon DisplayType, as follows:

DisplayType	Properties
`'line'`	Any MATLAB line property
`'point'`	Any MATLAB line marker property
`'polygon'`	Any MATLAB patch property

See the MATLAB Graphics documentation for line, patch, image, and surface properties for complete descriptions of these properties and their values.

Remarks

You can use mapshow to display vector data in an axesm figure. However, you should not subsequently change the map projection using setm.

mapshow adds graphics to the current axes (it does not clear it first), enabling you to create multiple raster and vector map layers. If you do not want mapshow to draw on top of an existing map, create a new figure or subplot before calling it.

Examples

Example 1

Overlay Boston roads on an orthophoto. You need to convert Boston road vectors to units of survey feet before overlaying them on the image. Note that mapshow draws a new layer in the axes rather than replacing its contents:

figure
mapshow boston.tif
axis image off

% The orthophoto is in survey feet, the roads are in meters;
% convert the road units to feet before overlaying them.
S = shaperead('boston_roads.shp');
surveyFeetPerMeter = unitsratio('sf','meter');
x = surveyFeetPerMeter * [S.X];
y = surveyFeetPerMeter * [S.Y]; 
mapshow(x,y)

Example 2

Display Boston roads and change the line style:

roads = shaperead('boston_roads.shp');
figure
mapshow(roads,'LineStyle',':');

Example 3

Display the Boston roads shapes using a symbolspec:

% Create a SymbolSpec to color local roads:
%   (ADMIN_TYPE=0) cyan, state roads (ADMIN_TYPE=3) red. 
% Hide very minor roads (CLASS=6). 
% Make all roads that are major or larger (CLASS=1-4) 
%   have a LineWidth of 2. 
roadspec = makesymbolspec('Line',...
                          {'ADMIN_TYPE',0,'Color','cyan'}, ...
                          {'ADMIN_TYPE',3,'Color','red'},...
                          {'CLASS',6,'Visible','off'},...
                          {'CLASS',[1 4],'LineWidth',2});
figure
mapshow('boston_roads.shp','SymbolSpec',roadspec);

Example 4

Override default properties in combination with a symbolspec.

roadspec = makesymbolspec('Line',...
                         {'Default', 'Color', 'yellow'}, ...
                         {'ADMIN_TYPE',0,'Color','c'}, ...
                         {'ADMIN_TYPE',3,'Color','r'},...
                         {'CLASS',6,'Visible','off'},...
                         {'CLASS',[1 4],'LineWidth',2});
figure
mapshow('boston_roads.shp', 'Color', 'black', ...
'SymbolSpec', roadspec);

Example 5

Override default properties of the line with a symbolspec:

roadspec = makesymbolspec('Line',...
                         {'Default', 'Color', 'black'}, ...
                         {'ADMIN_TYPE',0,'Color','c'}, ...
                         {'ADMIN_TYPE',3,'Color','r'},...
                         {'CLASS',6,'Visible','off'},...
                         {'CLASS',[1 4],'LineWidth',2});
figure
mapshow('boston_roads.shp','SymbolSpec',roadspec);

Example 6

Display an orthophoto of Concord, MA, including a pond with three large islands:

[ortho, cmap] = imread('concord_ortho_w.tif');
R = worldfileread('concord_ortho_w.tfw');
figure
mapshow(ortho, cmap, R)

% Overlay a polygon representing the same pond 
% (feature 14 in the concord_hydro_area shapefile).  
% Note that the islands are visible in the orthophoto 
% through three "holes" in the pond polygon. 
pond = shaperead('concord_hydro_area.shp', 'RecordNumbers', 14);
mapshow(pond, 'FaceColor', [0.3 0.5 1], 'EdgeColor', 'black')
% Overlay roads in the same figure.
mapshow('concord_roads.shp', 'Color', 'red', 'LineWidth', 1);

Example 7

Read and view the Mount Washington SDTS DEM terrain data three different ways:

[Z, R] = sdtsdemread('9129CATD.DDF');

% View the Mount Washington terrain data as a mesh.
figure
mapshow(Z, R, 'DisplayType', 'mesh');
colormap(demcmap(Z))

% View the Mount Washington terrain data as a surface.
figure
mapshow(Z, R, 'DisplayType', 'surface');
colormap(demcmap(Z))

% View as a 3-D surface.
view(3);
axis normal

Example 8

Display the grid and contour lines of Mount Washington and Mount Dartmouth.

% Read the terrain data files.
[Z_W, R_W] = arcgridread('MtWashington-ft.grd');
[Z_D, R_D] = arcgridread('MountDartmouth-ft.grd');

% Display the terrain data as a texture map.
figure
hold on
h1 = mapshow(Z_W, R_W, 'DisplayType', 'texturemap');
h2 = mapshow(Z_D, R_D, 'DisplayType', 'texturemap');
set([h1, h2],'FaceColor','flat');

% Overlay black contour lines with labels onto the texturemap.
mapshow(Z_W, R_W, 'DisplayType', 'contour', ...
    'LineColor','black', 'ShowText', 'on');
mapshow(Z_D, R_D, 'DisplayType', 'contour', ...
    'LineColor','black', 'ShowText', 'on');

% Set the colormap appropriate to terrain elevation.
colormap(demcmap(Z_W))