geoshow

Display map latitude and longitude data

Syntax

geoshow(lat,lon)

geoshow(S)

geoshow(lat,lon,Z)

geoshow(Z,R)

geoshow(lat,lon,I)

geoshow(lat,lon,X,cmap)

geoshow(I,R)

geoshow(X,cmap,R)

geoshow(filename)

geoshow(___,Name,Value)

geoshow(ax,___)

h = geoshow(___)

Description

geoshow(lat,lon) projects and displays the latitude and longitude vectors lat and lon using the projection stored in the current axesm-based map (previously referred to as map axes). If there is no current axesm-based map, then lat and lon are projected using a default Plate Carrée projection on a set of regular axes.

Note

To display data on an axesm-based map, create a map using the axesm, worldmap, or usamap function before calling geoshow.

By default, geoshow displays lat and lon as lines. You can optionally display the vector data as points, multipoints, or polygons by using the DisplayType name-value pair argument.

geoshow(S) displays the vector geographic features stored in S as points, multipoints, lines, multilines, polygons, or multipolygons according to the geometry of S.

You can optionally specify symbolization rules using the SymbolSpec name-value pair argument.

geoshow(lat,lon,Z) projects and displays the geolocated data grid, Z. In this syntax, lat and lon are M-by-N latitude-longitude arrays. Z is an M-by-N array of class double. You can optionally display the data as a surface, mesh, texture map, or contour by using the DisplayType name-value pair argument.

geoshow(Z,R) projects and displays a regular data grid, Z, with referencing object R. You can optionally display the data as a surface, mesh, texture map, or contour by using the DisplayType name-value pair argument. If DisplayType is 'texturemap', then geoshow constructs a surface with ZData values set to 0.

geoshow(lat,lon,I) and

geoshow(lat,lon,X,cmap) projects and displays a geolocated image as a texture map on a zero-elevation surface. The geolocated image I can be a truecolor, grayscale, or binary image. X is an indexed image with colormap cmap. 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) and

geoshow(X,cmap,R) project and display an image georeferenced to latitude-longitude through the referencing object R. The image is shown as a texture map on a zero-elevation surface.

geoshow(filename) projects and displays data from the file specified according to the type of file format.

geoshow(___,Name,Value) specifies parameters and corresponding values that modify the type of display or set MATLAB^® graphics properties. You can use name,value pairs to set:

• Name,Value arguments

• Any MATLAB Graphics line, patch, and surface properties

• Any Mapping Toolbox™ contour properties

Parameter names can be abbreviated, and case does not matter.

geoshow(ax,___) sets the parent axes to ax.

h = geoshow(___) returns a handle to a MATLAB graphics object.

Examples

Display Regular Data Grid as Texture Map

Load elevation data and a geographic cells reference object for the Korean peninsula. Create a map for the Korean peninsula using worldmap.

load korea5c
worldmap(korea5c,korea5cR)

Display the elevation data as a texture map. Apply a colormap appropriate for elevation data using demcmap.

geoshow(korea5c,korea5cR,'DisplayType','texturemap')
demcmap(korea5c)

Display Polygons on Map Projection

Geocode a world region that contains Africa, Europe, and Asia. The output geospatial table represents the region using a polygon. Get information about the polygon by querying the Shape variable of the table.

land = readgeotable("landareas.shp");
GT = geocode("Africa and Eurasia",land);
GT.Shape

ans = 
  geopolyshape with properties:

              NumRegions: 2
                NumHoles: 22
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Display the polygon on a world map.

worldmap([-45 80],[-25 195]);
geoshow(GT)

Define Face Colors and Set Default Face Colors

Import a shapefile containing USA state polygons as a geospatial table. Create a map using a projection and limits suitable for displaying all 50 states.

states = readgeotable("usastatehi.shp");
figure
worldmap("na")

Create a symbol specification that sets the color of the Alaska and Hawaii polygons to red.

symspec = makesymbolspec("Polygon", ...
   {'Name','Alaska','FaceColor','red'}, ...
   {'Name','Hawaii','FaceColor','red'});

Display all the state polygons. Set the default face color to blue and the default edge color to black.

geoshow(states,"SymbolSpec",symspec, ...
   "DefaultFaceColor","blue", ...
   "DefaultEdgeColor","black");

Create Map and Display NaNs as Transparent

Load elevation data and a geographic cells reference object for the Korean peninsula. Insert a band of null values into the elevation data.

load korea5c
korea5c(80:100,:) = NaN;

Create a map for the Korean peninsula using worldmap. Then, display the elevation data as a surface with transparent null values.

worldmap(korea5c,korea5cR)
geoshow(korea5c,korea5cR,'DisplayType','surface')
demcmap(korea5c)

Display EGM96 Geoid Heights Masking Out Land Areas

Get geoid heights and a geographic postings reference object from the EGM96 geoid model. Then, display the geoid heights as a surface using an Eckert projection. Ensure the surface appears under the land mask by setting the 'CData' name-value pair to the geoid height data and the 'ZData' name-value pair to a matrix of zeros. Display the frame and grid of the map using framem and gridm.

[N,R] = egm96geoid;
axesm eckert4
Z = zeros(R.RasterSize);
geoshow(N,R,'DisplayType','surface','CData',N,'ZData',Z)
framem
gridm

Create a colorbar and add a text description. Then, mask out all the land.

cb = colorbar('southoutside');
cb.Label.String = 'EGM96 Geoid Height in Meters';
geoshow('landareas.shp','FaceColor','black')

Display EGM96 Geoid Heights as 3-D Surface

Get geoid heights and a geographic postings reference object from the EGM96 geoid model. Then, display the geoid heights as a surface using an Eckert projection.

[N,R] = egm96geoid;
axesm eckert4
geoshow(N,R,'DisplayType','surface')

Add light and material. Then, view the map as a 3-D surface.

light
material(0.6*[1 1 1])
axis normal
view(3)

Display Moon Albedo Using Orthographic Projection

Load moon albedo data and a geographic cells reference object.

load moonalb20c

Then, display the data. To do this, create a map and specify its projection as orthographic. Display the data as a texture map using the geoshow function. Then, change the colormap to grayscale and remove the axis lines.

axesm ortho
geoshow(moonalb20c,moonalb20cR,'DisplayType','texturemap')
colormap gray
axis off

Input Arguments

lat, lon — Latitude or longitude data

numeric vector | M-by-N numeric array

Latitude or longitude data, specified as a numeric vector or an M-by-N numeric matrix.

• lat and lon are vectors when used with the syntax geoshow(lat,lon).

• lat and lon are 2-D arrays when used with the geoshow(lat,lon,Z) syntax, the geoshow(lat,lon,I) syntax, or the geoshow(lat,lon,X,cmap) syntax. If lat and lon are matrices, they represent coordinate arrays or a geolocation array in geographic coordinates, and must be the same size as Z, I, or X. If I is an RGB image, lat and lon must be matrices that match the first two dimensions of the image.

lat and lon may contain embedded NaNs to delimit individual lines or polygon parts.

S — Geographic features

geospatial table | geopoint vector | geoshape vector | geographic structure array

Geographic features, specified as one of the following:

• A geospatial table. The Shape variable of the table must contain geopointshape, geolineshape, or geopolyshape objects. The geoshow function does not support geospatial tables containing more than one type of shape object. For more information about geospatial tables, see Create Geospatial Tables.

• A geopoint vector.

• A geoshape vector.

• A geographic structure array (geostruct) with Lat and Lon coordinate fields.

The geoshow function assumes the coordinates are geographic coordinates and projects them to map coordinates.

If you specify a mappoint vector, a mapshape vector, or a map structure array (mapstruct) with X and Y coordinate fields, then the geoshow function display the vertices as pre-projected map coordinates and issues a warning. If you specify a geospatial table containing mappointshape, maplineshape, or mapolyshape objects, then the geoshow function throws an error. In these cases, use the mapshow function instead.

Z — Data grid

M-by-N numeric array

Data grid, specified as an M-by-N numeric array that may contain NaN values. Z is either a georeferenced data grid, or a regular data grid associated with a geographic reference R.

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 that relates the subscripts of Z to geographic coordinates. The RasterSize property must be consistent with the size of the data grid, size(Z). If R is a GeographicPostingsReference object, then the 'image' and 'texturemap' values of DisplayType are not accepted.
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. Nearest-neighbor interpolation is used by default. NaN is returned for points outside the grid limits or for which lat or lon contain NaN. All angles are in units of degrees.

I — Truecolor, grayscale, or binary image

M-by-N-by-3 array | M-by-N array

Truecolor, grayscale, or binary image, specified as an M-by-N-by-3 array for truecolor images, or an M-by-N array for grayscale or binary images. lat and lon must be M-by-N arrays. If specified, 'DisplayType' must be set to 'image'.

X — Indexed image

M-by-N array

Indexed image with color map defined by cmap, specified as an M-by-N array. lat and lon must be M-by-N arrays. If specified, 'DisplayType' must be set to 'image'.

cmap — Color map

c-by-3 matrix

Color map of indexed image X, specified as an c-by-3 numeric matrix. There are c colors in the color map, each represented by a red, green, and blue pixel value.

filename — File name

character vector | string scalar

File name, specified as a string scalar or character vector. geoshow automatically sets the DisplayType parameter according to the format of the data.

Format	DisplayType
Shape file	'point', 'multipoint', '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)

Data Types: char | string

ax — Parent axes

axes object

Parent axes, specified as an axes object.

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: 'DisplayType','point'

SymbolSpec — Symbolization rules

structure

Symbolization rules to be used for displaying vector data, specified as the comma-separated pair consisting of 'SymbolSpec' and 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 Name,Value pair in the SymbolSpec structure, prefix the word 'Default' to the graphics property name.

DisplayType — Display type

'point' | 'multipoint' | 'line' | 'polygon' | 'image' | 'surface' | 'mesh' | 'texturemap' | 'contour'

Type of graphic display for the data, specified as the comma-separated pair consisting of 'DisplayType' and one of the following values.

Data Type	Display Type	Type of Property
Vector	'point'	line marker
	'multipoint'	line marker
	'line'	line
	'polygon'	patch
Image	'image'	surface
Grid	'surface'	surface
	'mesh'	surface
	'texturemap'	surface
	'contour'	contour

Valid values of DisplayType depend on the format of the map data. For example, if the map data is a geolocated image or georeferenced image, then the only valid value of DisplayType is 'image'. Different display types support different geographic data class types:

Display Type	Supported Class Types
Image	logical, uint8, uint16, and double
Surface	single and double
Texture map	All numeric types and logical

Output Arguments

h — Parent axes

handle object | modified patch object

Parent axes, returned as 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.

Tips

• 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, shaperead will create a mapstruct, with coordinate fields labelled X and Y instead of Lon and Lat. In such cases, geoshow assumes that the geostruct is in fact a mapstruct containing projected coordinates, warns, and calls mapshow to display the geostruct data without projecting it.

• If you do not want geoshow to draw on top of an existing map, create a new figure or subplot before calling it.

• When you display vector data in an axesm-based map 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 Change Map Projections When Using geoshow.

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

• When projecting data onto an axesm-based map, geoshow uses the projection stored within the axesm-based map. 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.

• When you pass two points to the geoshow function, the function projects the locations of each point on the map and displays a straight line that connects them, regardless of the map projection or the distance between the points. To display a projected geodesic or rhumbline curve between two points, first insert intermediate points using the track2 function.

• 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.

• When you display raster data in a map using geoshow, columns near the eastern or western edge may fail to display. This is seldom noticeable, except when the raster is very coarse relative to the displayed area. To include additional columns in the display, it might help to:

  • Resize the grid to a finer mesh.

  • Make sure the cell boundaries and map limits align.

  • Expand the map limits.

Version History

Introduced before R2006a

R2024a: Default colors for points, lines, and polygons have changed

When you plot vector data using the geoshow function, the function uses different default colors. This image compares the default colors of points, lines, and polygons in R2024a and R2023b.

R2021b: Display data from geospatial tables

The geoshow function accepts geospatial tables as input.