geoshow - Display map latitude and longitude data

Syntax

geoshow(lat,lon) geoshow(lat,lon, ..., 'DisplayType', displaytype, ...) geoshow(lat,lon,Z, ..., 'DisplayType', displaytype, ...) geoshow(Z,R, ..., 'DisplayType', displaytype,...), geoshow(lat,lon,I),geoshow(lat,lon,BW),geoshow(lat,lon,X,cmap), geoshow(lat,lon,RGB), geoshow(...'DisplayType', ...) geoshow(I,R),geoshow(BW,R),geoshow(RGB,R),geoshow(A,CMAP,R), geoshow(... `DisplayType', ...) geoshow(s) geoshow(s, ..., `SymbolSpec', symspec) geoshow(filename) geoshow(ax, ...) geoshow(..., 'Parent', ax, ...) h = geoshow(...) geoshow(..., param1, val1, param2, val2, ...)

Description

geoshow(lat,lon) or geoshow(lat,lon, ..., 'DisplayType', displaytype, ...) project and display the latitude and longitude vectors, lat and lon, using the projection stored in the axes. If there is no projection, the latitudes and longitudes are projected using a default Plate Carree projection. lat and lon must be of equal lentgth, and may contain embedded NaNs, delimiting individual lines or polygon parts. DisplayType can be 'point', 'line', or 'polygon', and defaults to 'line'.

geoshow(lat,lon,Z, ..., 'DisplayType', displaytype, ...), projects and displays a geolocated data grid. lat and lon are M-by-N latitude-longitude arrays and Z is an M-by-N array of class double. lat, lon, and Z may contain NaN values. DisplayType must be set to 'surface', 'mesh', 'texturemap', or 'contour'.

geoshow(Z,R, ..., 'DisplayType', displaytype,...), projects and displays a regular data grid. Z is a 2-D array of class double. R is either a 1-by-3 vector containing elements:

[cells/degree northern_latitude_limit western_longitude_limit]

or a 3-by-2 referencing matrix that transforms raster row and column indices to or from geographic coordinates according to:

[lon lat] = [row col 1] * R

If R is a referencing matrix, it must define 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 the section Understanding Raster Geodata in the User's Guide.

DisplayType must be set to 'surface', 'mesh', 'texturemap', or 'contour'. If DisplayType is 'texturemap', geoshow constructs a surface with ZData values set to 0.

geoshow(lat,lon,I),geoshow(lat,lon,BW),geoshow(lat,lon,X,cmap), geoshow(lat,lon,RGB), or geoshow(...'DisplayType', ...) projects and display a geolocated image as a texturemap on a zero-elevation surface. lat and lon are latitude-longitude geolocation arrays and I is a grayscale image, BW is a logical image, X is an indexed image with colormap cmap, or RGB is a truecolor image. lat, lon, 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.

geoshow(I,R),geoshow(BW,R),geoshow(RGB,R),geoshow(A,CMAP,R), or geoshow(... `DisplayType', ...) project and display an image georeferenced to latitude-longitude through the referencing matrix R. The image is shown as a texturemap on a zero-elevation surface. If specified, DisplayType must be set to 'image'.

geoshow(s) or geoshow(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 Lat and Lon fields, then the coordinate values are projected to map coordinates. If s includes X and Y fields they are plotted as (preprojected) map coordinates and a warning is issued. symspec is a structure returned by makesymbolspec that specifies the symbolization rules to be used for displaying vector data.

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

Format	DisplayType
Shape file	`'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)

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

h = geoshow(...) returns a handle to a MATLAB graphics object or, in the case of polygons, a modified patch object. If a geostruct or shapefile name is input, geoshow returns the handle to an hggroup object with one child per feature in the geostruct or shapefile, excluding any features that are completely trimmed away. In the case of a polygon geostruct or shapefile, each child is a modified patch object; otherwise it is a line object.

geoshow(..., param1, val1, param2, val2, ...) specifies parameter/value pairs that modify the type of display or set MATLAB graphics properties. Refer to the MATLAB Graphics documentation for line, patch, image, surface, mesh, and contour properties for full descriptions of these object properties and their values.

Parameters

Parameter names can be abbreviated and are case insensitive. Parameters 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(s)

Vector
'point', 'multipoint', '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 stored in geographic data structures.
In cases where both SymbolSpec and one or more graphics properties are specified, the graphics properties 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). See Example 2 below.

Data Type	Value(s)
Vector	`'point'`, `'multipoint'`, `'line'`, or `'polygon'`
Image	`'image'`
Grid	`'surface'`, `'mesh'`, `'texturemap'`, or `'contour'`

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 Reference documentation for line, patch, image, and surface properties for complete descriptions of these properties and their values.

Remarks

geoshow is often used to display vector geodata previously read from shapefiles using shaperead. When calling shaperead to read files that contain coordinates in latitude and longitude, be sure to specify the shaperead argument pair 'UseGeoCoords',true; if you do not include this argument (or specify 'UseGeoCoords',false), shaperead will create a mapstruct, with coordinate fields labelled X and Y instead of Lon and Lat, causing geoshow to assume that the geostruct is in fact a mapstruct containing projected coordinates. In such cases, geoshow warns and calls mapshow to display the geostruct data without projecting it.

When projecting data onto a map axes, geoshow uses the projection stored with the map axes. When displaying on a regular axes, it constructs a default Plate Carrée projection with a scale factor of 180/pi, enabling direct readout of coordinates in degrees.

Note When you display vector data in a map axes using geoshow, you should not subsequently change the map projection using setm. You can, however, change the projection with setm for raster data. For more information, see Changing Map Projections when Using geoshow.

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

geoshow can generally be substituted for displaym. However, there are limitations where display of specific objects is concerned. See the remarks under updategeostruct for further information.

Examples

Example 1

Display world land areas using a default Plate Carree projection:

figure
geoshow('landareas.shp', 'FaceColor', [0.5 1.0 0.5]);

Example 2

Override the symbolspec default rule:

% Create a worldmap of North America
figure
worldmap('na');

% Read the USA high resolution data
states = shaperead('usastatehi', 'UseGeoCoords', true);

% Create a symbolspec to make Alaska and Hawaii polygons red.
symspec = makesymbolspec('Polygon', ...
   {'Name', 'Alaska', 'FaceColor', 'red'}, ...
   {'Name', 'Hawaii', 'FaceColor', 'red'});

% Display all the other states in blue.
geoshow(states, 'SymbolSpec', symspec, ...
   'DefaultFaceColor', 'blue', ...
   'DefaultEdgeColor', 'black');

Example 3

Create a worldmap of Korea and display the korea data grid as a texture map:

load korea
figure;
worldmap(map, refvec)

% Display the Korean data grid as a texture map. 
geoshow(gca,map,refvec,'DisplayType','texturemap');
colormap(demcmap(map))

% Display the land area boundary as black lines.
S = shaperead('landareas','UseGeoCoords',true);
geoshow([S.Lat], [S.Lon],'Color','black');

Example 4

Display the EGM96 geoid heights, masking out land areas:

load geoid
% Create a figure with an Eckert projection.
figure
axesm eckert4; 
framem; gridm;
axis off

% Display the geoid as a texture map. 
geoshow(geoid, geoidrefvec, 'DisplayType', 'texturemap');

% Create a colorbar and title.
hcb = colorbar('horiz');
set(get(hcb,'Xlabel'),'String','EGM96 Geoid Heights in Meters.')

% Mask out all the land.
geoshow('landareas.shp', 'FaceColor', 'black');

Example 5

Display the EGM96 geoid heights as a 3-D surface using the Eckert IV projection:

load geoid

% Create the figure with an Eckert projection.
figure
axesm eckert4; 
axis off

% Display the geoid as a surface. 
h=geoshow(geoid, geoidrefvec, 'DisplayType','surface');

% Add light and material.
light; material(0.6*[ 1 1 1]);

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

Example 6

Display the moon albedo image projected using Plate Carree and in an orthographic projection.

load moonalb

% Projection not specified -- uses Plate Carree
figure
geoshow(moonalb,moonalbrefvec)

% Orthographic projection
figure
axesm ortho 
geoshow(moonalb, moonalbrefvec, 'DisplayType', 'texturemap')
colormap(gray(256))
axis off

Example 7

Read and display the San Francisco South 24K DEM data:

filenames = gunzip('sanfranciscos.dem.gz', tempdir); 
demFilename = filenames{1}; 

% Read every point of the 1:24,000 DEM file. 
[lat, lon,Z] = usgs24kdem(demFilename,2); 

% Delete the temporary gunzipped file. 
delete(demFilename); 

% Move all points at sea level to -1 to color them blue. 
Z(Z==0) = -1;

% Compute the latitude and longitude limits for the DEM. 
latlim = [min(lat(:)) max(lat(:))];
lonlim = [min(lon(:)) max(lon(:))];

% Display the DEM values as a texture map. 
figure
usamap(latlim, lonlim)
geoshow(lat, lon, Z, 'DisplayType','texturemap')
demcmap(Z)
daspectm('m',1)
% Overlay black contour lines onto the texturemap.
geoshow(lat, lon, Z, 'DisplayType', 'contour', ...
  'LineColor', 'black');

% View the DEM values in 3-D.
figure
usamap(latlim, lonlim)
geoshow(lat, lon, Z, 'DisplayType', 'surface')
demcmap(Z)
daspectm('m',1)
view(3)