3-D Maps, Geospatial Data and Projections

using MATLAB
Foster N.
Making Three-Dimensional Maps

Sources of Terrain Data

Digital Terrain Elevation Data from NGA
Digital Elevation Model Files from USGS
Determining What Elevation Data Exists for a Region

Reading Elevation Data Interactively Extracting DEM Data with demdataui

Determining and Visualizing Visibility Across Terrain

Computing Line of Sight with los2

Shading and Lighting Terrain Maps

Lighting a Terrain Map Constructed from a DTED File Lighting a Global Terrain Map with lightm and

lightmui
Surface Relief Shading
Colored Surface Shaded Relief
Relief Mapping with Light Objects

Draping Data on Elevation Maps

Draping Geoid Heights over Topography
Draping Data over Terrain with Different Gridding

Working with the Globe Display

What Is the Globe Display?
The Globe Display Compared with the Orthographic

Projection
Using Opacity and Transparency in Globe Displays Over-the-Horizon 3-D Views Using Camera
Positioning

Functions
Displaying a Rotating Globe

Customizing and Printing Maps

Inset Maps
Graphic Scales
North Arrows
Thematic Maps
What Is a Thematic Map?
Choropleth Maps
Special Thematic Mapping Functions

Using Colormaps and Colorbars Colormap for Terrain Data Contour Colormaps
Colormaps for Political Maps Labeling Colorbars
Editing Colorbars

Printing Maps to Scale

Manipulating Geospatial Data

Manipulating Vector Geodata

Repackaging Vector Objects
Matching Line Segments
Geographic Interpolation of Vectors
Vector Intersections
Calculating Polygon Area
Overlaying Polygons with Set Logic
Cutting Polygons at the Date Line
Building Buffer Zones
Trimming Vector Data to a Rectangular Region Trimming Vector Data to an Arbitrary Region
Simplifying Vector Coordinate Data

Manipulating Raster Geodata Vector-to-Raster Data Conversion Data Grids as Logical Variables Data
Grid Values Along a Path Data Grid Gradient, Slope, and Aspect

Using Map Projections and Coordinate Systems

What Is a Map Projection?

Quantitative Properties of Map Projections

The Three Main Families of Map Projections Unwrapping the Sphere to a Plane
Cylindrical Projections
Conic Projections
Azimuthal Projections

Projection Aspect
The Orientation Vector
Projection Parameters
Projection Characteristics Maps Can Have

Visualizing and Quantifying Projection Distortions Displays of Spatial Error in Maps

Quantifying Map Distortions at Point Locations
Accessing, Computing, and Inverting Map Projection Data
Accessing Projected Coordinate Data
Projecting Coordinates Without a Map Axes
Inverse Map Projection
Coordinate Transformations

Working with the UTM System

What Is the Universal Transverse Mercator System? Understanding UTM Parameters
Setting UTM Parameters with a GUI
Working in UTM Without a Map Axes
Mapping Across UTM Zones

Summary and Guide to Projections

Creating Web Map Service Maps

Introduction to Web Map Service What Web Map Service Servers Provide Basic WMS Terminology

Basic Workflow for Creating WMS Maps Workflow Summary

Creating a Map of Elevation in Europe

Searching the WMS Database Introduction to the WMS Database Finding Temperature Data

Refining Your Search

Refining by Text String
Refining by Geographic Limits

Updating Your Layer

Retrieving Your Map

Ways to Retrieve Your Map
Understanding Coordinate Reference System Codes Retrieving Your Map with wmsread
Setting Optional Parameters
Adding a Legend to Your Map
Retrieving Your Map with WebMapServer.getMap

Modifying Your Request

Setting the Geographic Limits and Time Manually Editing a URL

Overlaying Multiple Layers

Creating a Composite Map of Multiple Layers from One

Server
Combining Layers from One Server with Data from Other
Sources
Draping Topography and Ortho-Imagery Layers over a
Digital Elevation Model Layer
Animating Data Layers
Creating Movie of Terra/MODIS Images
Creating an Animated GIF File
Animating Time-Lapse Radar Observations Displaying Animation of Radar Images over GOES

Backdrop

Retrieving Elevation Data

Merge Elevation Data with Rasterized Vector Data Display a Merged Elevation and Bathymetry Layer

(SRTM30 Plus)
Drape a Landsat Image onto Elevation Data
Saving Favorite Servers Exploring Other Layers from a Server
Writing a KML File
Searching for Layers Outside the Database
Hosting Your Own WMS Server

Common Problems with WMS Servers Connection Errors

Wrong Scale
Problems with Geographic Limits
Problems with Server Changing LayerName Non-EPSG:4326 Coordinate Reference Systems Map Not
Returned
Unsupported WMS Version
Other Unrecoverable Server Errors

Making Three-Dimensional Maps

Sources of Terrain Data on page 5-2
Reading Elevation Data Interactively on page 5-13
Determining and Visualizing Visibility Across Terrain on page 5-19
Shading and Lighting Terrain Maps on page 5-21
Draping Data on Elevation Maps on page 5-38
Working with the Globe Display on page 5-47

Sources of Terrain Data

In this section...
Digital Terrain Elevation Data from NGA on page 5-2 Digital Elevation Model Files from USGS on
page 5-3 Determining What Elevation Data Exists for a Region on page 5-3

Digital Terrain Elevation Data from NGA

Nearly all published terrain elevation data is in the form of data grids. Displaying Data Grids on page
4-70 described basic approaches to rendering surface data grids with Mapping Toolbox functions,
including viewing surfaces in 3-D axes. The following sections describe some common data formats for
terrain data, and how to access and prepare data sets for particular areas of interest.
The Digital Terrain Elevation Data (DTED) Model is a series of gridded elevation models with global
coverage at resolutions of 1 kilometer or finer. DTEDs are products of the U. S. National Geospatial
Intelligence Agency (NGA), formerly the National Imagery and Mapping Agency (NIMA), and before
that, the Defense Mapping Agency (DMA). The data is provided as 1-by-1 degree tiles of elevations on
geographic grids with product-dependent grid spacing. In addition to NGAs own DTEDs, terrain data
from Shuttle Radar Topography Mission (SRTM), a cooperative project between NASA and NGA, are
also available in DTED format, levels 1 and 2 (see below).

The lowest resolution data is the DTED Level 0, with a grid spacing of 30 arc-seconds, or about 1
kilometer. The DTED files are binary. The files have filenames with the extension dtN,where N is the
level of the DTED product. You can find published specifications for DTED at the NGA web site.

NGA also provides higher resolution terrain data files. DTED Level 1 has a resolution of 3 arc-seconds,
or about 100 meters, increasing to 18 arc-seconds near the poles. It was the primary source for the USGS
1:250,000 (1 degree) DEMs. Level 2 DTED files have a minimum resolution of 1 arc-second near the
equator, increasing to 6 arc-seconds near the poles. DTED files are available on from several sources on
CD-ROM, DVD, and on the Internet. Note For information on locating map data for download over the
Internet, see the following documentation at the MathWorks Web site: http://www.mathworks.com/help/
map/finding-geospatial-data.html.

Digital Elevation Model Files from USGS

The United States Geological Survey (USGS) has prepared terrain data grids for the U.S. suitable for use
at scales between 1:24,000 and 1:250,000 and beyond. Some of this data originated from Defense
Mapping Agency DTEDs. Specifications and data quality information are available for these digital
elevation models (DEMs) and other U.S. National Mapping Program geodata from the USGS. USGS no
longer directly distributes 1:24,000 DEMs and other large-scale geodata. U.S. DEM files in SDTS
format are available from private vendors, either for a fee or at no charge, depending on the data sets
involved.

The largest scale USGS DEMs are partitioned to match the USGS 1:24,000 scale map series. The grid
spacing for these elevations models is 30 meters on a Universal Transverse Mercator grid. Each file
covers a 7.5-minute quadrangle. (Note, however, that only a subset of paper quadrangle maps are
projected with UTM, and that USGS vector geodata products might not use this coordinate system.) The
map and data series is available for much of the conterminous United States, Hawaii, and Puerto Rico.

Determining What Elevation Data Exists for a Region

Several Mapping Toolbox functions and a GUI help you identify file names for and manage digital
elevation model data for areas of interest. These tools do not retrieve data from the Internet; however,
they do locate files that lie on the Mapping Toolbox path and indicate the names of data sets that you can
download or order on magnetic media or CD-ROM.

Certain Mapping Toolbox utility functions can describe and import elevation data. The following table
describes functions that read in data, determine what file names might exist for a given area, or return
metadata for elevation grid files. These files are data products packaged by government agencies; with
minor exceptions, the format used for each is unique to that data product, which is why special functions
are required to read them and why their filenames and/or footprints can be knownapriori.

File Type DTED

DEM
DEM24K

ETOPO1c,
ETOPO2v2c,
ETOPO22001, and ETOPO5

GTOPO30
SATBATH
SDTS DEM
TBASE
Description

U.S. Department of Defense Digital Terrain Elevation Data

USGS 1-degree
(3-arc-second
resolution) digital elevation models

USGS 1:24K
(30-meter resolution) digital elevation
models

Earth Topography
1-minute
(ETOPO1c), 2-minute (ETOPO2v2c and ETOPO22001), and 5-minute (ETOPO5)

Tiles of 30-arc-second global elevation

models

Global 2-minute
(4 km) satellite
topography and
bathymetry data

Digital elevation
models in U.S. SDTS format

TerrainBase
topography and
bathymetry binary and ASCII grid files

Function to Read Files

dted
Function to Identify or Summarize Files dteds
usgsdem usgsdems
usgs24kdem N/A
etopo N/A
gtopo30 gtopo30s
satbath N/A
sdtsdemread

(reads
tbase sdtsinfo
metadata from catalog file)

N/A
Note that the names of functions that identify file names are those of their respective file-reading
functions appended with s. These functions determine file names for areas of interest, and have calling
arguments of the form (latlim, lonlim), with which you indicate the latitude and longitude limits for an
area of interest, and all return a list of filenames that provide the elevations required. The southernmost
latitude and the western-most longitude must be the first numbers in latlim and lonlim,respectively.

Using dteds, usgsdems, and gtopo30s to Identify DEM Files Suppose you want to obtain elevation
data for the area around Cape Cod, Massachusetts. You define your area of interest to extend from
41.1N to 43.9N latitude and from 71.9W to 69.1W longitude.

1 To determine which DTED files you need, use the dteds function, which returns a cell array of strings:

dteds([41.1 43.9],[-71.9 -69.1]) ans =

'\DTED\W072\N41.dt0'
'\DTED\W071\N41.dt0'
'\DTED\W070\N41.dt0'
'\DTED\W072\N42.dt0'
'\DTED\W071\N42.dt0'
'\DTED\W070\N42.dt0'
'\DTED\W072\N43.dt0'
'\DTED\W071\N43.dt0'
'\DTED\W070\N43.dt0'

Note three important considerations about using DTED files:

a DTED filenames reflect latitudes only and thus do not uniquely specify a data set; they must be
organized within directories that specify longitudes. When you download level 0 DTEDs, the DTED
folder and its subfolders are transferred as a compressed archive that you must decompress before using.

bSome files that the dteds function identifies do not exist, either because they completely cover water
bodies or have never been created or released by NGA. The dted function that reads the DTEDs handles
missing cells appropriately.

c NGA might or might not continue to make DTED data sets available to the general public online. For
information on availability of terrain data from NGA and other sources, see http://www.mathworks.com/
help/map/finding-geospatial-data.html.
2 To determine the USGS DEM files you need, use the usgsdems function:

usgsdems([41.1 43.9],[-71.9 -69.1]) ans =

'portland-w'
'portland-e'
'bath-w'
'boston-w'
'boston-e'
'providence-w'
'providence-e'
'chatham-w'

Note that, in contrast to the dteds command you executed above, there are eight rather than nine files
listed to cover the 3-by-3-degree region of interest. The cell that consists entirely of ocean has no name
and is thus omitted from the output cell array.

3 To determine the GTOPO30 files you need, use the gtopo30s function:
gtopo30s([41.1 43.9],[-71.9 -69.1]) ans =
'w100n90'

Note The DTED, GTOPO30, and small-scale (low-resolution) USGS DEM grids are in latitude and
longitude. Large-scale (24K) USGS DEMs grids are in UTM coordinates. The usgs24kdem function
automatically unprojects the UTM grids to latitude and longitude; the stdsdemread function does not.

For additional information, see the reference pages for dteds, usgsdems, usgs24kdem,and gtopo30s.

Mapping a Single DTED File with the DTED Function In this exercise, you render DTED level 0
data for a portion of Cape Cod. The 1-by-1 file can be downloaded from NGA or purchased on CD-
ROM. You read and display the elevation data at full resolution as a lighted surface to show both large-
and small-scale variations in the data.

1 Define the area of interest and determine the file to be obtained:

latlim = [ 41.20 41.95]; lonlim = [-70.95 -70.10];
2 To determine which DTED files you need, use the dteds function, which returns a cell array of strings:
dteds(latlim, lonlim) ans =
'dted\w071\n41.dt0'

In this example, only one DTED file is needed, so the answer is a single string. For more information on
the dteds function, see Using dteds, usgsdems, and gtopo30s to Identify DEM Files on page 5-5).

3 Unless you have a CD-ROM containing this file, download it from the source indicated in the
following tech note:
http://www.mathworks.com/help/map/finding-geospatial-data.html
The original data comes as a compressed tar or zip archive that you must expand before using.

4 Use the dted function to create a terrain grid and a referencing vector in the workspace at full
resolution. If more than one DTED file named n41.dt0 exists on the path, your working folder must be
/dted/w071in order to be sure that dted finds the correct file. If the file is not on the path, you are prompted
to navigate to the n41.dt0 file by the dted function:

samplefactor = 1;
[capeterrain, caperef] = dted('n41.dt0', ... samplefactor, latlim, lonlim);
5 Because DTED files contain no bathymetric depths, decrease elevations of zero slightly to render them
with blue when the colormap is reset:
capeterrain(capeterrain == 0) = -1;
6 Use usamap to construct an empty map of axes for the region defined by the latitude and longitude
limits:
figure;
ax = usamap(latlim,lonlim);
7 Read data for the region defined by the latitude and longitude limits from the usastatehi shapefile:
capecoast = shaperead('usastatehi',... 'UseGeoCoords', true,...
'BoundingBox', [lonlim' latlim']);

8 Display coastlines on the map axes that was created with usamap:
geoshow(ax, capecoast, 'FaceColor', 'none');
At this point the map looks like this:

9 Render the elevations, and set the colormap

accordingly:
meshm(capeterrain, caperef, size(capeterrain), capeterrain); demcmap(capeterrain)
The resulting map, shown below, is a window on Cape Cod, and illustrates the relative coarseness of
DTED level 0 data.

Mapping Multiple DTED Files with the DTED Function When your region of interest extends across
more than one DTED tile, the dted function concatenates the tiles into a single matrix, which can be at
full resolution or a sample of every nth row and column. You can specify a single DTED file, a folder
containing several files (for different latitudes along a constant longitude), or a higher level folder
containing subfolders with files for several longitude bands.

1 To follow this exercise, you need to acquire the necessary DTED files from the Internet as described in
the following tech note
http://www.mathworks.com/help/map/finding-geospatial-data.html
or from a CD-ROM. This yields a set of directories that contain the following files:
/dted
/w070
n41.avg
n41.dt0
n41.max
n41.min n43.avg n43.dt0 n43.max n43.min

/w071
n41.avg n41.dt0 n41.max n41.min n42.avg n42.dt0 n42.max n42.min n43.avg n43.dt0 n43.max n43.min

/w072
n41.avg n41.dt0 n41.max n41.min n42.avg n42.dt0 n42.max n42.min n43.avg n43.dt0 n43.max n43.min

2 Change your working folder to the folder that includes the top-level DTED folder (which is always
named dted).
3 Use the dted function, specifying that folder as the first argument:
latlim = [ 41.1 43.9]; lonlim = [-71.9 -69.1]; samplefactor = 5;
[capetopo,caperef] = dted(pwd, samplefactor, latlim, lonlim);

The sample factor value of 5 specifies that only every fifth data cell, in both latitude and longitude, will
be read from the original DTED file. You can choose a larger value to save memory and speed
processing and display, at the expense of resolution and accuracy. The size of your elevation array
(capetopo) will be inversely proportional to the square of the sample factor.

Note You can specify a DTED filename rather than a folder name if you are accessing only one DTED
file. If the file cannot be found, a file dialog is presented for you to navigate to the file you want. See the
example Mapping a Single DTED File with the DTED Function on page 5-7.

4 As DTEDs contain no bathymetric depths, recode all zero elevations to -1, to enable water areas to be
rendered properly:
capetopo(capetopo==0)=-1;
5 Obtain the elevation grids latitude and longitude limits; use them to draw an outline map of the area to
orient the viewer:
[latlim,lonlim] = limitm(capetopo,caperef);

figure;
ax = usamap(latlim,lonlim);
capecoast = shaperead('usastatehi',...

'UseGeoCoords', true,...
'BoundingBox', [lonlim' latlim']); geoshow(ax,capecoast,'FaceColor','None');

Themapnowlookslikethis. 6 Render the elevation grid

with meshm, and then recolor the map with demcmap to display hypsometric colors (elevation tints):
meshm(capetopo, caperef, size(capetopo), capetopo); demcmap(capetopo)
Hereisthemap;notethemissingtiletotherightwherenoDTEDdataexists.

Reading Elevation Data Interactively

Extracting DEM Data with demdataui

You can browse many formats of digital elevation map data using the demdataui graphical user interface.
The demdataui GUI determines and graphically depicts coverage of ETOPO5, TerrainBase, the satellite
bathymetry model (SATBATH), GTOPO30, GLOBE, and DTED data sets on local and network file
systems, and can import these files into the workspace.

Note When it opens, demdataui scans your Mapping Toolbox path for candidate data files. On PCs, it also
checks the root directories of CD-ROMs and other drives, including mapped network drives. This can
cause a delay before the GUI appears.

You can choose to read from any of the data sets demdataui has located. If demdataui does not recognize
data you think it should find, check your path and click Help to read about how files are identified.

This exercise illustrates how to use the demdataui interface. You will not necessarily have all the DEM
data sets shown in this example. Even if you have only one (the DTED used in the previous exercise, for
example), you can still follow the steps to obtain your own results:

1 Open the demdataui UI. It scans the path for data before it is displayed:
demdataui

The Sourcelistintheleftpaneshowsthedatasetsthatwerefound. The coverage of each data set is indicated

by a yellow tint on the map with gray borders around each tile of data. Here, the source is selected to
present all DTED files available to a user.
2 Clicking a different source in the left column updates the coverage display. Here is the coverage area
for available GTOPO30 tiles.
3 Use the map in the UI to specify the location and density of data to extract. To interactively set a
region of interest, click in the map to zoom by a factor of two centered on the cursor, or click and drag
across the map to define a rectangular region. The size of the matrix of the area currently displayed is
printed above the map. To reduce the amount of data, you can continue to zoomin,ororyoucanraisethe
Samplefactor slider. A sample factor of 1 reads every point, 2 reads every other point, 3 reads every
third point, etc. The matrix size is updated when you move the Samplefactor slider.

Here is the UI panel after selecting ETOPO30 data and zooming in on the Indian subcontinent.

4 To see the terrain you have windowed at the sample factor you specified, click the Get button. This
causes the GUI map pane to repaint to display the terrain grid with the demcmap colormap. In this
example, the data grid contains 580-by-568 data values, as shown below.

5 If you are not satisfied with the result, click the Clear button to remove all data previously read in via
Get and make new selections. You might need to close and reopen demdatui in order to select a new
region of interest.

6When you are ready to import DEM data to the workspace or save it as a MAT-file, click the Save
button. Select a destination and name the output variable or file. You can save to a MAT-file or to a
workspace variable. The demdataui function returns one or more matrices as an array of display structures,
having one element for each separate get you requested (assuming you did not subsequently Clear).
Youthenuse geoshow or mlayerstoaddthedatagridstoamapaxes.

The data returned by demdataui contains display structures. You cannot update these to geographic data
structures (geostructs) using the updategeostruct function, because they are of type surface,whichthe
updating function does not recognize. However, you can still display them with
geoshow,asshowninthenextstep.
7 To access the contents of the display structure, use its field names. Here

map and maplegend are copied from the structure and used to create a lighted three-dimensional elevation
map display using worldmap.(demdata is the default name for the structure, which you can override when
you save it.)

Z = demdata.map;
refvec = demdata.maplegend;
figure
ax = worldmap(Z, refvec);
geoshow(ax, Z, refvec, 'DisplayType', 'texturemap'); axis off
demcmap(Z);

Determining and Visualizing Visibility Across Terrain

Computing Line of Sight with los2

You can use regular data grids of elevation data to answer questions about the mutual visibility of
locations on a surface (intervisibility). For example,
 Is the line of sight from one point to another obscured by terrain?
What area can be seen from a location?
What area can see a given location?

The first question can be answered with the los2 function. In its simplest form, los2 determines the
visibility between two points on the surface of a digital elevation map. You can also specify the altitudes
of the observer and target points, as well as the datum with respect to which the altitudes are measured.
For specialized applications, you can even control the actual and effective radius of the Earth. This
allows you to assume, for example, that the Earth has a radius 1/3 larger than its actual value, a setting
which is frequently used in modeling radio wave propagation.

The following example shows a line-of-sight calculation between two points on a regular data grid
generated by the peaks function. The calculation is performed by the los2 function, which returns a logical
result: 1 (points are mutually visibleintervisible), or 0 (points are not intervisible).

1Create an elevation grid using peaks with a maximum elevation of 500, and set its origin at (0N, 0W),
with a spacing of 1000 cells per degree):
map = 500*peaks(100); maplegend = [ 1000 0 0];
2 Define two locations on this grid to test intervisibility:

lat1 = -0.027; lon1 = 0.05; lat2 = -0.093; lon2 = 0.042;

3 Calculate intervisibility. The final argument specifies the altitude (in meters) above the surface of the
first location (lat1, lon1)wherethe observer is located (the viewpoint):
los2(map,maplegend,lat1,lon1,lat2,lon2,100) ans =
1

The los2 function produces a profile diagram in a figure window showing visibility at each grid cell
along the line of sight that can be used to interpret the Boolean result. In this example, the diagram
shows that the line between the two locations just barely clears an intervening peak.

You can also compute the viewshed, a name derived from watershed,which indicates the elements of a
terrain elevation grid that are visible from a particular location. The viewshed function checks for a line of
sight between a fixed observer and each element in the grid. See the viewshed function reference page for
an example.

Shading and Lighting Terrain Maps

In this section...
Lighting a Terrain Map Constructed from a DTED File on page 5-21 Lighting a Global Terrain Map
with lightm and lightmui on page 5-24 Surface Relief Shading on page 5-27
Colored Surface Shaded Relief on page 5-31
Relief Mapping with Light Objects on page 5-34

Lighting a Terrain Map Constructed from a DTED File

The lightm function creates light objects in the current map. To modify the positions and colors of lights
created on world maps or large regions you can use the interactive lightmui GUI. For finer control over
light position (for example, in small areas lit by several lights), you have to specify light positions using
projected coordinates. This is because lights are children of axes and share their coordinate space. See
Lighting a Global Terrain Map with lightm and lightmui on page 5-24 for an example of using lightmui.

In this exercise, you manually specify the position of a single light in the northwest corner of a DTED
DEM for Cape Cod.

1To illustrate lighting terrain maps, begin by following the exercise in Mapping a Single DTED File
with the DTED Function on page 5-7, or execute the steps below:

latlim = [ 41.20 41.95];

lonlim = [-70.95 -70.10];
cd dted\w071 % Note: Your absolute path may vary. samplefactor = 1;
[capeterrain, caperef] = dted('n41.dt0', samplefactor, ...

latlim, lonlim);
capeterrain(capeterrain == 0) = -1;
capecoast = shaperead('usastatehi', ...

'UseGeoCoords', true, ...

'BoundingBox', [lonlim' latlim']);
2 Construct a map of the region within the specified latitude and longitude limits:

figure
ax = usamap(latlim,lonlim);
set(gcf,'Renderer','zbuffer')
geoshow(ax,capecoast,'FaceColor','none');
geoshow(ax,capeterrain,caperef,'DisplayType','texturemap'); demcmap(capeterrain)
The map looks like this.

3 Set the vertical exaggeration. Use

daspectm to specify that elevations are in meters and should be multiplied by 20:
daspectm('m',20)

4 Makesurethatthelinedataisvisible. Toensurethatitisnotobscuredby terrain, use zdatam to set it to the

highest elevation of the cape1 terrain data:

zdatam('allline',max(capeterrain(:)))
5 Specify a location for a light source with lightm:
lightm(42,-71)
If you omit arguments, a GUI for setting positional properties for the new light opens.

6 The lighting computations caused the map to become quite dark with specular highlights. Now restore
its luminance by specifying three surface reflectivity properties in the range of 0 to 1:

ambient = 0.7; diffuse = 1; specular = 0.6; material([ambient diffuse specular])

The surface looks blotchy because there is no interpolation of the lighting component (flat facets are
being modeled). Correct this by specifying Phong shading:

lighting phong
Themapnowlookslikethis.
 7 If you want to compare the lit map
with the unlit version, you can toggle the lighting off:
lighting none
For additional information, see the reference pages for daspectm, lightm, light, lighting,and material.

Lighting a Global Terrain Map with lightm and lightmui

In this example, you create a global topographic map and add a local light at adistanceof250 km above
New York City, (40.75 N, 73.9 W). You then change the material and lighting properties, add a second
light source, and activate the lightmui tool to change light position, altitude, and colors.

The lightmui display plots lights as circular markers whose facecolor indicates the light color. To change
the position of a light, click and drag the circular marker. Alternatively, right-clicking the circular
marker summons a dialog box for changing the position or color of the light object. Clicking the color
bar in that dialog box invokes the uisetcolor dialog box that can be used to specify or pick a color for the
light.

1 Load the topo DTM files, and set up an orthographic projection:

load topo
axesm('mapprojection','ortho','origin',[10 -20 0]) axis off
set(gcf,'Renderer','zbuffer')

2 Plot the topography and assign a topographic colormap:

meshm(topo,topolegend); demcmap(topo)
3 Set up a yellow light source over New York City:
lightm(40.75,-73.9,500/earthRadius('km'),... 'color','yellow','style','local')
The first two arguments to lightm are the latitude and longitude of the light source. The third argument is
its altitude, in units of Earth radii.
4 The surface is quite dark, so give it more reflectivity by specifying
material([0.7270 1.5353 1.9860 4.0000 0.9925]) lighting phong; hidem(gca)
The lighted orthographic map looks like this.

5 If you want, add more lights, as

follows:
lightm(20,40,0.1,'color','magenta','style','local')
The second light is magenta, and positioned over the Gulf of Arabia.
6 To modify the lights, use the lightmui GUI, which lets you drag lights across a world map and specify
their color and altitudes:
lightmui(gca)

The lights are shown as appropriately colored circles, which you can drag to new positions. You can also
Ctrl+click a circle to bring up a dialog box for directly specifying that lights position, altitude, and
color. The GUI and the map look like this at this point.
7 In the lightmui window, drag the yellow light to the eastern tip of Brazil,

and drag the magenta light to the Straits of Gibraltar.

8 Ctrl+click or Shift+click the magenta circle in the lightmui window. A second UI, for setting light
position and color, opens. Set the altitude to 0.04 (Earth radii). Set the light color components to 1.0
(red), 0.75 (green), and 1.0(blue). Press Return after each action. The colorbar on the UI changes to
indicate the color you set. If you prefer to pick a color, click on the colorbar to bring up a color-choosing
UI. The map now looks like this.

For additional information, see the reference pages for lightm and lightmui.

Surface Relief Shading

You can make dimensional monochrome shaded-relief maps with the function surflm, which is analogous
to the MATLAB surfl function. The effect of surflm is similar to using lights, but the function models
illumination itself (with one light source that you specify when you invoke it, but cannot reposition)
by weighting surface normals rather than using light objects.

Shaded relief maps of this type are usually portrayed two-dimensionally rather than as perspective
displays. The surflm function works with any projection except globe.

The surflm function accepts geolocated data grids only. Recall, however, that regular data grids are a
subset of geolocated data grids, to which they can be converted using meshgrat (see Fitting Gridded Data
to the Graticule on page 4-71). The following example illustrates this procedure.

Creating Monochrome Shaded Relief Maps Using surflm As stated above, surflm simulates a single
light source instead of inserting light objects in a figure. Conduct the following exercise with the korea
data set to see how surflm behaves. It uses worldmap to set up an appropriate map axes and reference
outlines.
1 Set up a projection and display a vector map of the Korean peninsula

with worldmap:
figure;
ax = worldmap('korea');
latlim = getm(ax,'MapLatLimit'); lonlim = getm(ax,'MapLonLimit');

coastline = shaperead('landareas',... 'UseGeoCoords', true,...

'BoundingBox', [lonlim' latlim']);

geoshow(ax, coastline, 'FaceColor', 'none');

worldmap chooses a projection and map bounds to make this map.

2 Load the korea terrain

model:
load korea
3 Generate the grid of latitudes and longitudes to transform the regular data grid to a geolocated one:
[klat,klon] = meshgrat(map,refvec);
4 Use surflm to generate a default shaded relief map, and change the colormap to a monochromatic scale,
such as gray, bone,or copper.
ht = surflm(klat,klon,map); colormap('copper')

In this default case, the lighting direction is set at 45 counterclockwise from the viewing direction; thus
the sun is in the southeast. This map is shown below.
5 To make the light come from some other direction, specify the light sources azimuth and elevation as
the fourth argument to surflm. Clear the terrain map and redraw it, specifying an azimuth of 135
(northeast) and an elevation of 60 above the horizon:

clmo(ht); ht=surflm(klat,klon,map,[135,60]);
The surface lightens and has a new character because it is lit closer to overhead and from a different
direction.

6 Now shift the light to the northwest (-135 azimuth), and lower it to 40 above the horizon. Because a
lower sun decreases the overall reflectance when viewed from straight above, also specify a more
reflective surface as a fifth argument to surflm. This is a 1-by-4 vector describing relative contributions of
ambient light, diffuse reflection, specular reflection, and a specular shine coefficient. It defaults to [.55 .6
.4 10].

clmo(ht); ht=surflm(klat,klon,map,[-135, 30],[.65 .4 .3 10]);

This is a good choice for lighting this terrain, because of the predominance of mountain ridges that run
from northeast to southwest, more or less perpendicular to the direction of illumination. Here is the final
map. For further information, see the reference pages for surflm and surfl.

Shaded relief representations can highlight the fine structure of the land and sea floor, but because of the
monochromatic coloration, it is difficult to distinguish land from sea. The next section describes how to
color such maps to set off land from water.
Colored Surface Shaded Relief

The functions meshlsrm and surflsrm display maps as shaded relief with surface coloring as well as light
source shading. You can think of them as extensions to surflm that combine surface coloring and surface
light shading. Use meshlsrm to display regular data grids and surflsrm to render geolocated data grids.

These two functions construct a new colormap and associated CData matrix that uses grayscales to
lighten or darken a matrix component based on its calculated surface normal to a light source. While
there are no analogous MATLAB display functions that work like this, you can obtain similar results
using MATLAB light objects, as Relief Mapping with Light Objects on page 5-34 explains.

Coloring Shaded Relief Maps and Viewing Them in 3-D In this exercise, you use surflsrm in a way
similar to how you used surflm in the preceding exercise, Creating Monochrome Shaded Relief Maps
Using surflm on page 5-27. In addition, you set a vertical scale and view the map from various
perspectives.

1 Start with a new map axes and the korea data, and then georeference the regular data grid:
load korea
[klat,klon] = meshgrat(map,refvec); axesm miller

2 Create a colormap for DEM data; it is transformed by surflsm to shade relief according to how you
specify the suns altitude and azimuth:
[cmap,clim] = demcmap(map);
3 Plot the colored shaded relief map, specifying an azimuth of -135 and an altitude of 50 for the light
source:
surflsrm(klat,klon,map,[-130 50],cmap,clim)

You can also achieve the same effect with meshlsrm, which operates on regular data grids (it first calls
meshgrat, just as you just did), e.g., meshlsrm(map,maplegend).

4The surface has more contrast than if it were not shaded, and it might help to lighten it uniformly by
25% or so:
brighten(.25)

The map, which has an overhead view, looks like this. 5 Plot an oblique view of the surface by hiding its
bounding box, exaggerating terrain relief by a factor of 50, and setting the view azimuth to -30 (south-
southwest) and view altitude to 30 above the horizon:

set(gca,'Box','off') daspectm('meters',50) view(-30,30)

Themapnowlookslikethis.

6 You can continue to rotate the perspective with the view function (or interactively with the Rotate 3D
tool in the figure window), and to change the vertical exaggeration with the daspectm function. You
cannot change the built-in lighting direction without generating a new view using surflsrm.

For further information, see the reference pages for surflsrm, meshlsrm, daspectm,and view.

Relief Mapping with Light Objects

In the exercise Lighting a Global Terrain Map with lightm and lightmui on page 5-24, you created
light objects to illuminate a Globe display. In the following one, you create a light object to mimic the
map produced in the previous exercise (Coloring Shaded Relief Maps and Viewing Them in 3-D on
page 5-32), which uses shaded relief computations rather than light objects.

The meshlsrm and surflsrm functions simulate lighting by modifying the colormap with bands of light and
dark. The map matrix is then converted to indices for the new shaded colormap based on calculated
surface normals. Using light objects allows for a wide range of lighting effects. The toolbox manages
light objects with the lightm function, which depends upon the MATLAB light function. Lights are
separate MATLAB graphic objects, each with its own object handle.

Colored 3-D Relief Maps Illuminated with Light Objects As a comparison to the lighted shaded
relief example shown earlier, add a light source to the surface colored data grid of the Korean peninsula
region:

1 If you need to, load the korea DEM, and create a map axes using the Miller projection:
load korea
figure; axesm('MapProjection','miller',... 'MapLatLimit',[30 45],'MapLonLimit',[115 135])
2 Display the DEM with meshm, and color it with terrain hues:
meshm(map,refvec,size(map),map); demcmap(map)

The map, without lighting effects, looks like this. 3 Create a lightobjectwith lightm (similar to the
MATLAB light function, but specifies position with latitude and longitude rather than x, y, z). The light is
placed at the northwest corner of the grid, one degree high:
h=lightm(45,115,1)
The figure becomes darker.
4 To see any relief in perspective, it is necessary to exaggerate the vertical dimension. Use a factor of 50
for this:
daspectm('meters',50)
The figure becomes darker still, with highlights at peaks.
5 Set the ambient (direct), diffuse (skylight), and specular (highlight) surface reflectivity characteristics,
respectively:
material ([.7, .9, .8])
6 By default, the lighting is flat (plane facets). Change this to Phong shading (interpolated normal
vectors at facet corners):
lighting phong
Themapnowlookslikethis. 7 Finally, remove the edges of the bounding box and set a viewpoint of -30
azimuth, 30 altitude:
set(gca,'Box','off') view(-30,30)

The view from (-30,30) with one light at (45,115,1) and Phong shading is shown below. Compare it to
the final map in the previous exercise, Coloring Shaded Relief Maps and Viewing Them in 3-D on
page 5-32.

To remove a light (when there is

only one) from the current figure, type
clmo(handlem('light'))

For more information, consult the reference pages for lightm, daspectm, material, lighting,and view, along with
the section on Lighting and Transparency in the 3D Visualization documentation.

Draping Data on Elevation Maps

In this section...
Draping Geoid Heights over Topography on page 5-38 Draping Data over Terrain with Different
Gridding on page 5-41
Draping Geoid Heights over Topography

Lighting effects can provide important visual cues when elevation maps are combined with other kinds
of data. The shading resulting from lighting a
surfacemakesitpossibletodrapesatellitedataoveragridofelevations. It is common to use this kind of
display to overlay georeferenced land cover images from Earth satellites such as LANDSAT and SPOT
on topography from digital elevation models. Mapping Toolbox displays use variations of techniques
described in the previous section.

When the elevation and image data grids correspond pixel-for-pixel to the same geographic locations,
you can build up such displays using the optional altitude arguments in the surface display functions. If
they do not, you can interpolate one or both source grids to a common mesh.

ThefollowingexampleshowsthefigureoftheEarth(the geoid data set) draped on topographic relief (the topo

data set). The geoid data is shown as an attribute (using a color scale) rather than being depicted as a
3-D surface itself. The two data sets are both 1-by-1-degree meshes sharing a common origin.

Note The geoid can be described as the surface of the ocean in the absence of waves, tides, or land
obstructions. It is influenced by the gravitational attraction of denser or lighter materials in the Earths
crust and interior and by the shape of the crust. A model of the geoid is required for converting
ellipsoidal heights (such as might be obtained from GPS measurements) to orthometric heights. Geoid
heights vary from a minimum of about 105 meters below sea level to a maximum of about 85 meters
above sea level.

1 Begin by loading the topo and geoid regular data grids:

load topo load geoid
2 Create a map axes using a Gall stereographic cylindrical projection (a perspective projection):
axesm gstereo

3 Use meshm to plot a colored display of the geoids variations, but specify
topoasthefinalargument,togiveeach geoid grid cell the height (z-value) of the corresponding topo grid cell:

meshm(geoid,geoidrefvec,size(geoid),topo)
Low geoid heights are shown as blue, high ones as red.

4 For reference, plot the world coastlines in black, raise their elevation to 1000 meters (high enough to
clear the surface in their vicinity), and expand the map to fill the frame:

load coast
plotm(lat,long,'k')
zdatam(handlem('allline'),1000) tightmap

At this point the map looks like this.

5 Duetothe vertical view and lack of lighting, the topographic relief is not visible, but it is part of the
figures surface data. Bring it

out by exaggerating relief greatly, and then setting a view from the south-southeast:
daspectm('m',200); tightmap
view(20,35)

6 Remove the bounding box, shine a light on the surface (using the default position, offset to the right of
the viewpoint), and render again with Phong shading:

set(gca,'Box','off')
camlight;
lighting phong

7 Finally, set the perspective to converge slightly (the default perspective is orthographic):
set(gca,'projection','perspective')

The final map is shown below. From it, you can see that the geoid mirrors the topography of the major
mountain chains such as the Andes, the Himalayas, and the Mid-Atlantic Ridge. You can also see that
large areas of high or low geoid heights are not simply a result of topography.
Draping Data over Terrain with Different Gridding

If you want to combine elevation and attribute (color) data grids that cover the same region but are
gridded differently, you must resample one matrix to be consistent with the other. It helps if at least one
of the grids is a geolocated data grid, because their explicit horizontal coordinates allow them to be
resampled using the ltln2val function. To combine dissimilar grids, you candooneofthefollowing:

Construct a geolocated grid version of the regular data grid values.

Construct a regular grid version of the geolocated data grid values.
The following two examples illustrate these closely related approaches.

Draping via Converting a Regular Grid to a Geolocated Data Grid

This example drapes slope data from a regular data grid on top of elevation data from a geolocated data
grid. Although the two data sets actually have thesameorigin(thegeolocatedgridderivesfromthe topo data
set), this approach works with any dissimilar grids. The example uses the geolocated data grid as the
source for surface elevations and transforms the regular data grid into slope values, which are then
sampled to conform to the geolocated data grid (creating a set of slope values for the diamond-shaped
grid) and color-coded for surface display.

Note When you use ltln2val to resample a regular data grid over an irregular area, make sure that the
regular data grid completely covers the area of the geolocated data grid.

1 Begin by loading the geolocated data grids from mapmtx, which contains two regions. You will only use
the diamond-shaped portion of mapmtx (lt1, lg1, and map1) centered on the Middle East, not the lt2, lg2,and
map1 data:

load mapmtx lt1 load mapmtx lg1 load mapmtx map1

Load the topo global regular data grid:

load topo
2 Compute surface aspect, slope, and gradients for topo. You use only the slopes in subsequent steps:
[aspect,slope,gradN,gradE] = gradientm(topo,topolegend);
3 Use ltln2val to interpolate slope values to the geolocated grid specified by lt1, lg1:
slope1 = ltln2val(slope,topolegend,lt1,lg1);
The output is a 50-by-50 grid of elevations matching the coverage of the map1 variable.

4 Set up a figure with a Miller projection and use surfm to display the slope data. Specify the z-values for
the surface explicitly as the map1 data, which is terrain elevation:

figure; axesm miller

surfm(lt1,lg1,slope1,map1)
The map mainly depicts steep cliffs, which represent mountains (the Himalayas in the northeast), and
continental shelves and trenches.

5 The coloration depicts steepness of slope. Change the colormap to make the steepest slopes magenta,
the gentler slopes dark blue, and the flat areas light blue:

colormap cool;
6 Use view to get a southeast perspective of the surface from a low viewpoint:
view(20,30); daspectm('m',200)
In 3-D, you immediately see the topography as well as the slope.

7 The default rendering uses faceted shading (no smooth interpolation). Render the surface again, this
time making it shiny with Phong shading and lighting from the east (the default of camlight lights surfaces
from over the viewers right shoulder):

material shiny;camlight;lighting phong

8 Finally, remove white space and re-render the figure in perspective mode:
axis tight; set(gca,'Projection','Perspective')
Here is the mapped result.

DrapingaGeolocatedGridonRegularDataGridviaTexture Mapping
The second way to combine a regular and a geolocated data grid is to construct a regular data grid of
your geolocated data grids z-data. This approach has the advantage that more computational functions
are available for regular data grids than for geolocated ones. Another aspect is that the color and
elevationgridsdonothavetobethesamesize. Iftheresolutionsofthetwo are different, you can create the
surface as a three-dimensional elevation map and later apply the colors as a texture map. You do this by
setting the surface Cdata property to contain the color matrix, and setting the surface face color to
'TextureMap'.

In the following steps, you create a new regular data grid that covers the region of the geolocated data
grid, then embed the color data values into the new matrix. The new matrix might need to have
somewhat lower resolution than the original, to ensure that every cell in the new map receives a value.

1 Load the topo and terrain data from mapmtx:

load topo;
load mapmtx lt1
load mapmtx lg1
load mapmtx map1

2 Identify the geographic limits of one of the mapmtx geolocated grids:

latlim = [min(lt1(:)) max(lt1(:))]; lonlim = [min(lg1(:)) max(lg1(:))];
3 Trim the topo data to the rectangular region enclosing the smaller grid:
[topo1,topo1ref] = maptrims(topo,topolegend,latlim,lonlim);
4 Create a regular grid filled with NaNstoreceivetexturedata:
[curve1,curve1ref] = nanm(latlim,lonlim,.5);
The last parameter establishes the grid at 1/.5 cells per degree.

5 Use imbedm to embed values from map1 into the curve1 grid; the values are the discrete Laplacian
transform (the difference between each element of the map1 grid and the average of its four orthogonal
neighbors):

curve1 = imbedm(lt1,lg1,del2(map1),curve1,curve1ref);
6 Set up a map axes with the Miller projection and use meshm to draw the topo1 extract of the topo DEM:
figure; axesm miller
h = meshm(topo1,topo1ref,size(topo1),topo1);
7 Render the figure as a 3-D view from a 20 azimuth and 30 altitude, and exaggerate the vertical
dimension by a factor of 200:
view(20,30); daspectm('m',200)
8 Light the view and render with Phong shading in perspective:
material shiny; camlight; lighting phong axis tight; set(gca,'Projection','Perspective')
So far, both the surface relief and coloring represent topographic elevation.
 9 Apply the curve1 matrix as a texture
map directly to the figure using the set function:
set(h,'Cdata',curve1,'FaceColor','TextureMap')

The area originally covered by the [lt1, lg1, map1] geolocated data grid, and recoded via the Laplacian
transform as curve1, now controls color symbolism, with the NaN-coded outside cells rendered in black.

Working with the Globe Display

In this section...
What Is the Globe Display? on page 5-47

The Globe Display Compared with the Orthographic Projection on page 5-48
Using Opacity and Transparency in Globe Displays on page 5-50 Over-the-Horizon 3-D Views
Using Camera Positioning Functions on page 5-53
Displaying a Rotating Globe on page 5-55
What Is the Globe Display?

The Globe display is a three-dimensional view of geospatial data capable of mapping terrain relief or
other data for an entire planet viewed from space. Its underlying transformation maps latitude, longitude,
and elevation to a three-dimensional Cartesian frame. All Mapping Toolbox projections transform
latitudes and longitudes to map x-and y-coordinates. The globe function is special because it can render
relative relief of elevations above, below, or on a sphere. In Earth-centered Cartesian (x,y,z) coordinates,
z is not an optional elevation; rather, it is an axis in Cartesian three-space. globe is useful for geospatial
applications that require three-dimensional relationships between objects to be maintained, such as when
one simulates flybys, and/or views planets as they rotate.

The Globe display is based on a coordinate transformation, and is not a map projection. While it has
none of the distortions inherent in planar projections, it is a three-dimensional model of a planet that
cannot be displayed without distortion or in its entirety. That is, in order to render the globe in a figure
window, either a perspective or orthographic transformation must be applied, both of which necessarily
involve setting a viewpoint, hiding the back side and distortions of shape, scale, and angles.

The Globe Display Compared with the Orthographic Projection

The following example illustrates the differences between the two-dimensional orthographic projection,
which looks spherical but is really flat, and the three-dimensional Globe display. Use the Rotate 3D tool
to manipulate the display.

1 Load the topo data set and render it with an orthographic map projection:
load topo
axesm ortho; framem
meshm(topo,topolegend);demcmap(topo)

2 View the map obliquely:

view(3); daspectm('m',1)

3 You can view it in 3-D from any perspective, even from underneath. To visualize this, define a
geolocated data grid with meshgrat,populateitwith aconstant z-value, and render it as a stem plot with
stem3m:

[latgrat,longrat] = meshgrat(topo,topolegend,[20 20]); stem3m(latgrat,longrat,500000*ones(size(latgrat)),'r')

Use the Rotate 3D tool on the figure window toolbar to change your viewpoint. No matter how you
position the view, you are looking at a disc with stems protruding perpendicularly.
4 Create another figure using the Globe transform rather than orthographic

projection:
figure
axesm('globe','Geoid',earthRadius)
5 Display the topo surface in this figure and view it in 3-D:
meshm(topo,topolegend); demcmap(topo)
view(3)
6 Include the stem plot to visualize the difference in surface normals on a sphere:
stem3m(latgrat,longrat,500000*ones(size(latgrat)),'r')
7 You can apply lighting to the display, but its location is fixed, and does not move as the camera
position is shifted:
camlight('headlight','infinite')
8 If you prefer a more unobstructed view, hide the 3-D axes:
set(gca,'Box','off')

Here is a representative view using theGlobedisplaywiththeheadlight.

You can use the LabelRotation property when you use the Orthographic or any other Mapping Toolbox
projection to align meridian and parallel labels with the graticule. Because the Globe display is not a true
map projection and is handled differently internally, LabelRotation does not work with it.

For additional information on functions used in this example, see the reference pages for view, camlight,
meshgrat,and stem3m.

Using Opacity and Transparency in Globe Displays

Because Globe displays depict 3-D objects, you can see into and through them as long as no opaque
surfaces (e.g., patches or surfaces) obscure your view. This can be particularly disorienting for point and
line data, because features on the back side of the world are reversed and can overlay features on the
front side.

Here is one way to create an opaque surface over which you can display line and point data:
1 Create a figure and set up a Globe display:
figure; axesm('globe')
2 Draw a graticule in a light color, slightly raised from the surface:
gridm('GLineStyle','-','Gcolor',[.8 .7 .6],'Galtitude', .02)
3 Load and plot the coast data in black, and set up a 3-D perspective:

load coast
plot3m(lat,long,.01,'k') view(3)
axis off; zoom(2)
 4 Use the Rotate 3D tool on the figures
toolbar to rotate the view. Note how confusing the display is because of its transparency.
5 Make a uniform 1-by-1-degree grid and a referencing matrix for it:
base = zeros(180,360);
baseR = makerefmat('RasterSize', size(base), ...
'Latlim',[-90 90],'Lonlim',[0 360]);
6 Render the grid onto the globe, color it copper, light it from camera right, and make the surface reflect
more light:

hs = meshm(base,baseR,size(base)); colormap copper

camlight right
material([.8 .9 .4])

Note Another way to make the surface of the globe one color is to change the FaceColor property of a
displayed surface mesh (e.g., topo).
If you havent rotated it, the display looks like this.

Whenyoumanuallyrotatethismap,itsmovementcanbejerkyduetothe number of vectors that must be

redisplayed. In any position, however, the copper surface effectively hides all lines on the back side of
the globe. Note The technique of using a uniform surface to hide rear-facing lines has limitations for the
display of patch symbolism (filled polygons). As patch polygons are represented as planar, in three-
space the interiors of large patches can intersect the spherical surface mesh, allowing its symbolism to
show through.

Over-the-Horizon 3-D Views Using Camera Positioning Functions

You can create dramatic 3-D views using the Globe display. The camtargmand camposm functions
(Mapping Toolbox functions corresponding to camtarget and campos) enable you to position focal point
and a viewpoint, respectively, in geographic coordinates, so you do not need to deal with 3-D Cartesian
figure coordinates.

In this exercise, you display coastlines from the landareas shapefile over topographic relief, and then view
the globe from above Washington, D.C., looking toward Moscow, Russia.

1 Set up a Globe display and obtain topographic data for the map:
figure
axesm globe load topo

2 Display topo without the vertical component (by omitting the fourth argument to meshm):
meshm(topo, topolegend, size(topo)); demcmap(topo);
The default view is from above the North Pole with the central meridian running parallel to the x-axis.
3 Add world coastlines from the global landareas shapefile and plot them in light gray:
coastlines = shaperead('landareas',...
'UseGeoCoords', true, 'Attributes', {});
plotm([coastlines.Lat], [coastlines.Lon], 'Color', [.7 .7 .7])

4 Read the coordinate locations for Moscow and Washington from the worldcities shapefile:
moscow = shaperead('worldcities',...
'UseGeoCoords', true,...
'Selector',{@(name) strcmpi(name,'Moscow'), 'Name'});

washington = shaperead('worldcities',...
'UseGeoCoords', true,...
'Selector',{@(name) strcmpi(name,'Washington D.C.'),... 'Name'});

5 Create a great circle track to connect Washington with Moscow and plot it in red:
[latc,lonc] = track2('gc',...
moscow.Lat, moscow.Lon, washington.Lat, washington.Lon);
plotm(latc,lonc,'r')

6 Point the camera at Moscow. Wherever the camera is subsequently moved, it always looks toward
[moscow.Lat moscow.Lon]:
camtargm(moscow.Lat, moscow.Lon, 0)
7 Station the camera above Washington. The third argument is an altitude in Earth radii:
camposm(washington.Lat, washington.Lon, 3)
8 Establish the camera up vector with the camera targets coordinates. The great circle joining
Washington and Moscow now runs vertically:
camupm(moscow.Lat, moscow.Lon)
9 Set the field of view for the camera to 20 for the final view:
camva(20)
10 Add a light, specify a relatively nonreflective surface material, and hide the map background:
camlight; material(0.6*[ 1 1 1]) hidem(gca)
Here is the final view.

For additional
information, see the reference pages for extractm, camtargm, camposm, camupm, Globe,and camlight.
Displaying a Rotating Globe

Because the Globe display can be viewed from any angle without the need to recompute a projection,
you can easily animate it to produce a rotating globe. If the displayed data is simple enough, such
animations can be redrawn at relatively fast rates. In this exercise, you progressively add or replace
features on a Globe display and rotate it under the control of a MATLAB program that resets the view to
rotate the globe from west to east in one-degree increments.

1 In the Mapping Toolbox editor, create a MATLAB program file containing the following code:
% spin.m: Rotates a view around the equator one revolution % in 5-degree steps. Negative step makes it rotate normally %
(west-to-east).
for i=360:-5:0

view(i,23.5); % Earth's axis tilts by 23.5 degrees drawnow

end

Save this as spin.m in your current folder or on the Mapping Toolbox path. Note that the azimuth
parameter for the figure does not have the same origin as geographic azimuth: it is 90 degrees to the
west.
2 Set up a Globe display with a graticule, as follows:

axesm('globe','Grid','on','Gcolor',[.7 .8 .9],'GlineStyle','-')
The view is from above the North Pole.
3 Show the axes, but hide the edges of the figures box, and view it in perspective rather than
orthographically (the default perspective):
set(gca, 'Box','off', 'Projection','perspective')
4 Spin the globe one revolution:
spin
The globe spins rapidly. The last position looks like this.
5To make the globe opaque, create a sea-level data grid as you did for the previous exercise, Using
Opacity and Transparency in Globe Displays on page 5-50:

base = zeros(180,360); baseref = [1 90 0]; hs = meshm(base,baseref,size(base)); colormap copper

The globe now is a uniform dark copper color with the grid overlaid.
6 Pop up the grid so it appears to float 2.5% above the surface. Prevent the display from stretching to fit
the window with the axis vis3d command:
setm(gca, 'Galtitude',0.025); axis vis3d
7 Spin the globe again:
spin
The motion is slower, due to the need to rerender the 180-by-360 mesh: The last frame looks like this.

8 Get ready to
replace the uniform sphere with topographic relief by deleting the copper mesh:
clmo(hs)
load topo
9 Scale the elevations to have an exaggeration of 50 (in units of Earth radii) and plot the surface:
topo = topo / (earthRadius('km')* 20);
hs = meshm(topo,topolegend,size(topo),topo);
demcmap(topo)

10 Show the Earth in space; blacken the figure background, turn off the three axes, and spin again:

set(gcf,'color','black'); axis off;

spin
Here is a representative view, showing the Himalayas rising on the Eastern limb of the planet and the
Andes on the Western limb.

11Youcanapplylightingaswell,whichshiftsastheplanetrotates. Trythe following settings, or experiment

with others:

camlight right
lighting phong;
material ([.7, .9, .8])
Here is the illuminated version of the preceding view:

For additional
information, see the globe, camlight,and view reference pages.

Customizing and Printing Maps

Inset Maps on page 6-2
Graphic Scales on page 6-8
North Arrows on page 6-14
Thematic Maps on page 6-17
Using Colormaps and Colorbars on page 6-24
Printing Maps to Scale on page 6-35

Inset Maps

Inset maps are often used to display widely separated areas, generally at the same scale, or to place a
map in context by including overviews at smaller scales. You can create inset maps by nesting multiple
axes in a figure and defining appropriate map projections for each. To ensure that the scale of each of the
maps is the same, use axesscale to resize them. As an example, create an inset map of California at the
same scale as the map of South America, to relate the size of that continent to a more familiar region:

1 Begin by defining a map frame for South America using worldmap:

figure
h1 = worldmap('south america');
 2 Use shaperead to read the world land areas polygon
shapefile:
land = shaperead('landareas.shp', 'UseGeoCoords', true);
3 Display the data in the map axes:
geoshow([land.Lat],[land.Lon])
setm(h1,'FFaceColor','w') % set the frame fill to white

4 Place axes for an inset in the lower middle of the map

frame, and project a line map of California:
h2 = axes('pos',[.5 .2 .1 .1]);
CA = shaperead('usastatehi', 'UseGeoCoords', true, ...

'Selector', {@(name) isequal(name,'California'), 'Name'}); usamap('california')

geoshow([CA.Lat],[CA.Lon])

5 Set the frame fill color and set the labels:

setm(h2,'FFaceColor','w')
mlabel; plabel; gridm % toggle off
6 Make the scale of the inset axes, h2 (California), match the scale of the original axes, h1 (South
America). Hide the map border:
axesscale(h1)
set([h1 h2], 'Visible', 'off')

Note that the toolbox software chose a different projection and appropriate parameters for each region
based on its location and shape. You can override these choices to make the two projections the same.

7Find out what map projections are used, and then make South Americas projection the same as
Californias:
getm(h1, 'mapprojection')
ans =
eqdconic
getm(h2, 'mapprojection')
ans =
lambert
setm(h1, 'mapprojection', getm(h2, 'mapprojection'))
 Note that the parameters for South America defaulted
properly (those appropriate for California were not used).
8 Finally, experiment with changing properties of the inset, such as its color: setm(h2, 'ffacecolor', 'y')

Graphic Scales

Graphic scale elements are used to provide indications of size even more frequently than insets are.
These are ruler-like objects that show distances on the ground at the nominal scale of the projection. You
can use the scaleruler function to add a graphic scale to the current map. You can check and modify the
scaleruler settings using getm and setm. You can also move the graphic scale to a new position by dragging
its baseline.
Try this by creating a map, adding a graphic scale with the default settings, and shifting its location.
Then add a second scale in nautical miles, and change the tick mark style and direction:

1 Use usamapto plot a map of Texas and surrounding states as filled polygons:
states = shaperead('usastatehi.shp', 'UseGeoCoords', true); figure; usamap('Texas')
faceColors = makesymbolspec('Polygon',...

{'INDEX', [1 numel(states)], ...

'FaceColor', polcmap(numel(states))});
geoshow(states,'DisplayType', 'polygon', ...
'SymbolSpec', faceColors)

Because polcmap randomizes patch colors, your display can look different.

2 Add a default graphic scale and then

move it to a new location:

scaleruler on
setm(handlem('scaleruler1'), ...
'XLoc',-6.2e5,'YLoc',3.1e6, ...
'MajorTick',0:200:600)

The units of scaleruler default to kilometers. Note that handlem accepts the keyword 'scaleruler' or 'scaleruler1'
for the first scaleruler, 'scaleruler2' for the second one, etc. If there is more than one scaleruler on the
current axes, specifying the keyword 'scaleruler' returns a vector of handles.
3 Obtain a handle to the scalerulers hggroup using handlem and inspect its

properties using getm:

s = handlem('scaleruler');
getm(s)
ans =
Azimuth: 0
Children: 'scaleruler1'

Color: [0 0 0]
FontAngle: 'normal'
FontName: 'Helvetica' FontSize: 9

FontUnits: 'points'
FontWeight: 'normal'
Label: ''
Lat: 29.6479
Long: -101.7263
LineWidth: 0.5000
MajorTick: [0 200 400 600] MajorTickLabel: {4x1 cell}

MajorTickLength: 20
MinorTick: [0 25 50 75 100] MinorTickLabel: '100'
MinorTickLength: 12.5000
Radius: 'earth'
RulerStyle: 'ruler'
TickDir: 'up'
TickMode: 'manual'
Units: 'km'
XLoc: -620000
YLoc: 3100000
ZLoc: []

4 Change the scalerulers font size to 8 points:

setm(s,'fontsize',8)
5 Place a second graphic scale, this one in units of nautical miles:
scaleruler('units','nm')
6 Modify its tick properties:

setm(handlem('scaleruler2'), 'YLoc', 3.0e6, ... 'MajorTick', 0:100:300,...

'MinorTick', 0:25:50, 'TickDir', 'down', ... 'MajorTickLength', km2nm(25),...
'MinorTickLength', km2nm(12.5))

7 Experiment with the two other ruler styles available:

setm(handlem('scaleruler1'), 'RulerStyle', 'lines') setm(handlem('scaleruler2'), 'RulerStyle', 'patches')

North Arrows

The north arrow element provides the orientation of a map by pointing to the geographic North Pole.
You can use the northarrow function to display a symbol indicating the direction due north on the current
map. The north arrow symbol can be repositioned by clicking and dragging its icon. The orientation of
the north arrow is computed, and does not need manual adjustment no matter where you move the
symbol. Ctrl+clicking the icon creates an input dialog box with which you can change the location of
the north arrow:

1 To illustrate the use of north arrows, create a map centered at the South Pole and add a north arrow
symbol at a specified geographic position:

Antarctica = shaperead('landareas', 'UseGeoCoords', true, ... 'Selector',{@(name) strcmpi(name,{'Antarctica'}), 'Name'});

figure;
worldmap('south pole')
geoshow(Antarctica)
northarrow('latitude', -57, 'longitude', 135);
 Click and drag the north arrow symbol to
2
another corner of the map. Note that it always points to the North Pole.
3 Drag the north arrow back to the top left corner.

4 Right-click or Ctrl+click the north arrow. The Inputs for North Arrow dialog opens, which lets you
specify the line weight, edge and fill colors, and relative size of the arrow. Set some properties and click
OK.

5 Also set some north arrow properties manually, just to get a feel for them:
h = handlem('NorthArrow');
set(h, 'FaceColor', [1.000 0.8431 0.0000],... 'EdgeColor', [0.0100 0.0100 0.9000])
 6 Make three more north arrows, to show that
from the South Pole, every direction is north:

northarrow('latitude',-57,'longitude', 45);
northarrow('latitude',-57,'longitude',225);
northarrow('latitude',-57,'longitude',315);
Note North arrows are created as objects in the MATLAB axes (and thus have Cartesian coordinates),
not as mapping objects. As a result, if you create more than one north arrow, any Mapping Toolbox
function that manipulates anortharrow will affect only the last one drawn.

Thematic Maps

In this section...
WhatIsaThematicMap?onpage6-17
Choropleth Maps on page 6-18
Special Thematic Mapping Functions on page 6-20

WhatIsaThematicMap?

Most published and online maps fall into four categories:

Navigation maps, including topographic maps and nautical and aeronautical charts
Geophysical maps, that show the structure and dynamics of earth, oceans and atmosphere
Location maps, that depict the locations and names of physical features
Thematic maps, that portray attribute data about locations and features
Although online maps often combine these categories in new and unexpected ways, published maps and
atlases tend to respect them.

Thematic maps tend to be more highly stylized than other types of maps and frequently omit locational
information such as place names, physical features, coordinate grids, and map scales. This is because
rather than showing physical features on the ground, such as shorelines, roads, settlements, topography,
and vegetation, a thematic map displays quantified facts (a theme), such as statistics for a region or
sets of regions. Examples include the locations of traffic accidents in a city, or election results by state.
Thematic maps have a wide vocabulary of cartographic symbols, such as point symbols, dot
distributions, quiver vectors, isolines, colored zones, raised prisms, and continuous 3-D surfaces.
Mapping Toolbox functions can generate most of these types of map symbology.

Choropleth Maps

The most familiar form of thematic map is probably the choropleth map (from the Greek
choros,forplace,and plethos, for magnitude). Choropleth maps use colors or patterns to represent
attributes associated with certain geographic regions. For example, the global distribution of malaria-
carrying mosquitoes can be illustrated in a choropleth map, with the habitat of each mosquito
represented by a different color. In this example, colors are used to represent nominal data; the
categories of mosquitoes have no inherent ranking. If the data is ordinal, rather than nominal, the map
may contain a colorbar with shades of colors representing the ranking. For instance, a map of crime rates
in different areas could show high crime areas in red, lower crime areas in pink, and lowest crime areas
in white.

Creating choropleth maps with the Mapping Toolbox is fairly straightforward. Start with a geographic
data structure; create a symbolspec to map attribute values to face colors; and apply either geoshow or
mapshow, depending on whether you are working with latitude-longitude or pre-projected map
coordinates. The following example illustrates the process of creating a choropleth map of population
density for the six New England states in the year 2000.
1 Set the map limits for the New England region. Import low-resolution U.S. state boundary polygons:
MapLatLimit = [41 48]; MapLonLimit = [-74 -66];
NEstates = shaperead('usastatelo', 'UseGeoCoords', true, ... 'BoundingBox', [MapLonLimit' MapLatLimit']);
2 Set up map axes with a projection suitable to display the New England states:

axesm('MapProjection', 'eqaconic', 'MapParallels', [],... 'MapLatLimit', MapLatLimit, 'MapLonLimit', MapLonLimit,...

'GLineStyle', '-')

3 Display the New England states:

geoshow(NEstates, 'DisplayType', 'polygon', 'FaceColor','green')

4 Identify the maximum population density for New

England states:
maxdensity = max([NEstates.PopDens2000]);
5 Create an autumn colormap for the six New England states, and then use the flipud command to invert
the matrix.
fall = flipud(autumn(numel(NEstates)));
6 Make a symbol specification structure, a symbolspec, that assigns an autumn color to each polygon
according to the population density.
densityColors = makesymbolspec('Polygon', {'PopDens2000', ... [0 maxdensity], 'FaceColor', fall});
7 Display the map.

geoshow(NEstates, 'DisplayType', 'polygon', ...

'SymbolSpec', densityColors)
title ({'Population Density in New England in 2000', ... 'in Persons per Square Mile'})

8 Create a colorbar.

caxis([0 maxdensity]) colormap(fall)

colorbar
 9 Experiment
with other colormaps. Some names of predefined colormaps are autumn, cool, copper, gray, pink,and jet.

Special Thematic Mapping Functions

In addition to choropleth maps, other Mapping Toolbox display and symbology functions include

Function cometm
comet3m

Used For
Traces (animates) vectors slowly from a comet head

Traces (animates) vectors in 3-D slowly from a comet head

Function quiverm
quiver3m
scatterm
stem3m
Used For

Plots directed vectors in 2-D from specified latitudes and longitudes with lengths also specified as
latitudes and longitudes

Plots directed vectors in 3-D from specified latitudes, longitudes, and altitudes with lengths also
specified as latitudes and longitudes and altitudes
Draws fixed or proportional symbol maps for each point in a vector with specified marker symbol.
Similar maps can be generated using geoshow and mapshow using appropriate symbol specifications
(symbolspecs).

Projects a 3-D stem plot map on the current map axes

The cometm and quiverm functions operate like their MATLAB counterparts comet and quiver.The stem3m
function allows you to display geographic bar graphs. Like the MATLAB scatter function, the scatterm
function allows you to display a thematic map with proportionally sized symbols. The tissot function
calculates and displays Tissot Indicatrices, which graphically portray the shape distortions of any map
projection. For more information on these capabilities, consult the descriptions of these functions in the
reference pages.

Stem Maps
Stem plots are 3-D geographic bar graphs portraying numeric attributes at point locations, usually on
vector base maps. Below is an example of a stem plot over a map of the continental United States. The
bars could represent anything from selected city populations to the number of units of a product
purchased at each location:

Contour Maps
Contour and quiver plots can be useful in analyzing matrix data. In the following example, contour
elevation lines have been drawn over a topographical map. The region displayed is the Gulf of Mexico,
obtained from the topo matrix. Quiver plots have been added to visualize the gradient of the
topographical matrix.
Here is the displayed map:

Scatter Maps
The scatterm function plots symbols at specified point locations, like the MATLAB scatter function. If the
symbols are small and inconspicuous and do not vary in size, the result is a dot-distribution
map.Ifthesymbolsvary in size and/or shape according to a vector of attribute values, the result is a
proportional symbol map.

Using Colormaps and Colorbars

In this section...
Colormap for Terrain Data on page 6-24 Contour Colormaps on page 6-27
Colormaps for Political Maps on page 6-29 Labeling Colorbars on page 6-33
Editing Colorbars on page 6-34

Colormap for Terrain Data

Colors and colorscales (ordered progressions of colors) are invaluable for representing geographic
variables on maps, particularly when you create terrain and thematic maps. The following sections
describe techniques and provide examples for applying colormaps and colorbars to maps.

In previous examples, the function demcmap was used to color several digital elevation model (DEM)
topographic displays. This function creates colormaps appropriate to rendering DEMs, although it is
certainly not limited to DEMs.

These colormaps, by default, have atlas-like colors varying with elevation or depth that properly
preserve the land-sea interface. In cartography, such color schemes are called hypsometric tints.

1Here you explore demcmap using the topographic data for the Korean peninsula provided in the korea
data set. To set up an appropriate map projection, pass the korea data grid and referencing vector to
worldmap:

load korea
figure
worldmap(map,refvec)
2 Display the data grid with geoshow:
geoshow(map, refvec, 'DisplayType', 'mesh')

3 The Korea DEM is displayed using the default colormap, which is inappropriate and causes the surface
to be unrecognizable. Now apply the default DEM colormap:

demcmap(map)
4 You can also make demcmap assign all altitudes within a particular range to the same color. This results
in a quasi-contour map with breaks at a constant interval. Now color this map using the same color
scheme coarsened to display 500 meter bands:

demcmap('inc',map,500)
colorbar

Note that the first argument to demcmap, 'inc', indicates that the third argument should be interpreted as a
value range. If you prefer, you can specify the desired number of colors with the third argument by
setting the first argument to 'size'.

Contour Colormaps

You can create colormaps that make surfaces look like contour maps for other types of data besides
terrain. The contourcmap function creates a colormap that has color changes at a fixed value increment. Its
required arguments are the increment value and the name of a colormap function. Optionally, you can
also use contourcmap to add and label a colorbar similarly to the MATLAB colorbar function:

1 Explore contourcmap by loading the world geoid data set and rendering it with a default colormap:
load geoid
figure;
worldmap(geoid,geoidrefvec)
geoshow(geoid, geoidrefvec, 'DisplayType', 'surface')
2 Use contourcmap to specify a contour interval of 10 (meters), and to place a colorbar beneath the map:
contourcmap('jet',10,'colorbar','on','location','horizontal')

3 If you want to render a restricted value range, you can enter a vector of evenly spaced values for the
first argument. Here you specify a 5-meter interval and truncate symbology at 0 meters on the low end
and 50 meters at the high end:
contourcmap('jet',[0:5:50],...
'colorbar','on','location','horizontal')

Should you need to write a custom colormap function, for example, one that has irregular contour
intervals, you can easily do so, but it should have the N-by-3 structure of MATLAB colormaps.

Colormaps for Political Maps

Political maps typically use muted, contrasting colors that make it easy to distinguish one country from
its neighbors. You can create colormaps of this kind using the polcmap function. The polcmap function
creates a colormap with randomly selected colors of all hues. Since the colors are random, if you dont
like the result, execute polcmap again to generate a different colormap:

1 To explore political colormaps, display the usastatelo data set as patches, setting up the map with
worldmap and plotting it with geoshow:

figure
worldmap na
states = shaperead('usastatelo', 'UseGeoCoords', true); geoshow(states)
Note that the default face color is black, which is not very interesting.

2 Use polcmap to populate color

definitions to a symbolspec to randomly recolor the patches and expand the map to fill the frame:
faceColors = makesymbolspec('Polygon',...
{'INDEX', [1 numel(states)], 'FaceColor',... polcmap(numel(states))});

geoshow(states,'SymbolSpec',faceColors)

3 The polcmap function can also control the number and saturation of colors. Reissue the command
specifying 256 colors and a maximum saturation of 0.2. To ensure that the colormap is always the same,
reset the seed on the MATLAB random number function using the 'state' argument with a fixed value of
your choice:
figure
worldmap na
rand('state',0)
faceColors = makesymbolspec('Polygon',...

{'INDEX', [1 numel(states)], 'FaceColor', polcmap(256,.2)}); geoshow(states, 'SymbolSpec', faceColors)

4 For maximum control over the colors, specify the ranges of hues, saturations, and values. Use the same
set of random color indices as before.
figure
worldmap na
rand('state',0)
faceColors = makesymbolspec('Polygon', ...

{'INDEX', [1 numel(states)], ...

'FaceColor', polcmap(256,[.2 .5],[.3 .3],[1 1]) }); geoshow(states, 'SymbolSpec', faceColors)

Note The famous Four Color theorem states that any political map can be colored to completely
differentiate neighboring patches using only four colors. Experiment to find how many colors it takes to
color neighbors differently with polcmap.

Labeling Colorbars

Political maps are an example of nominal data display. Many nominal data sets have names associated
with a set of integer values, or consist of codes that identify values that are ordinal in nature (such as
low, medium, and high). The function lcolorbar creates a colorbar having a text label aligned with each
color. Nominal colorbars are customarily used only with small colormaps (where 10 categories or fewer
are being displayed). lcolorbar has options for orienting the colorbar and aligning text in addition to the
graphic properties it shares with axes objects.

figure; colormap(jet(5))
labels = {'apples','oranges','grapes','peaches','melons'}; lcolorbar(labels,'fontweight','bold');

Editing Colorbars

Maps of nominal data often require colormaps with special colors for each index value. To avoid
building such colormaps by hand, use the MATLAB GUI for colormaps, colormapeditor, described in the
MATLAB Function Referencepages. AlsoseetheMATLAB colormap function documentation.

Printing Maps to Scale

Maps are often printed at a size that makes objects on paper a particular fraction of their real size. The
linear ratio of the mapped to real object sizes is called map scale, and it is usually notated with a colon
as 1:1,000,000 or 1:24,000. Another way of specifying scale is to call out the printed and real
lengths, for example 1 inch = 1 mile.

You can specify the printed scale using the paperscale function. It modifies the size of the printed area on
the page to match the scale. If the resulting dimensions are larger than your paper, you can reduce the
amount of empty space around the map using tightmap, zoom,or panzoom, and by changing the axes
position to fill the figure. This also reduces the amount of memory needed to print with the zbuffer (raster
image) renderer. Be sure to set the paper scale last. For example,

set(gca,'Units','Normalized','Position',[0 0 1 1]) tightmap

paperscale(1,'in', 5,'miles')

The paperscale function also can take a scale denominator as its first and only argument. If you want the
map to be printed at 1:20,000,000, type
paperscale(2e7)
To check the size and extent of text and the relative position of axes, use previewmap, which resizes the
figure to the printed size.
previewmap
For more information on printing, see the Printing and Exporting section of the MATLAB Graphics
documentation.

Manipulating Geospatial Data

For some purposes, geospatial data is fine to use as is. Sooner or later, though, you need to extract,
combine, massage, and transform geodata. This chapter discusses some Mapping Toolbox tools and
techniques provided for such purposes.

Manipulating Vector Geodata on page 7-2

Manipulating Raster Geodata on page 7-31

Manipulating Vector Geodata

In this section...
Repackaging Vector Objects on page 7-2
Matching Line Segments on page 7-4
Geographic Interpolation of Vectors on page 7-5
Vector Intersections on page 7-8
Calculating Polygon Area on page 7-11
Overlaying Polygons with Set Logic on page 7-12 Cutting Polygons at the Date Line on page 7-17
Building Buffer Zones on page 7-19
Trimming Vector Data to a Rectangular Region on page 7-21 Trimming Vector Data to an Arbitrary
Region on page 7-24 Simplifying Vector Coordinate Data on page 7-25

Repackaging Vector Objects

It can be difficult to identify line or patch segments once they have been combined into large NaN-
clipped vectors. You can separate these polygon or line vectors into their component segments using
polysplit,whichtakes column vectors as inputs.

Extracting and Joining Polygons or Line Segments

1 Enter two NaN-delimited arrays in the form of column vectors:
lat = [45.6 -23.47 78 NaN 43.9 -67.14 90 -89]'; long = [13 -97.45 165 NaN 0 -114.2 -18 0]';
2 Use polysplit to create two cell arrays, latc and lonc:
[latc,lonc] = polysplit(lat,long)
latc =

[3x1 double] lonc =

[3x1 double] [4x1 double]

[4x1 double]
3 Inspect the contents of the cell arrays:
[latc{1} lonc{1}] [latc{2} lonc{2}]

ans = 45.6 13
-23.47 -97.45
78 165

ans = 43.9 0
-67.14 -114.2
90 -18
-89 0

Note that each cell array element contains a segment of the original line.
4 To reverse the process, use polyjoin:
[lat2,lon2] = polyjoin(latc,lonc);
5 The joined segments are identical with the initial lat and lon arrays:
[lat long] == [lat2 lon2]

ans =
11
11
11
00
11
11
11
11

The logical comparison is false for the NaN delimiters, by definition. 6 You can test for global equality,
including NaNs, as follows:
isequaln(lat,lat2) & isequaln(long,lon2)
ans = 1 See the polysplit and polyjoin reference pages for further information.

Matching Line Segments

A common operation on sets of line segments is the concatenation of segments that have matching
endpoints. The polymerge command compares endpoints of segments within latitude and longitude
vectors to identify endpoints that match exactly or lie within a specified distance. The matching
segments are then concatenated, and the process continues until no more coincidental endpoints can be
found. The two required arguments are a latitude (x)vector and a longitude (y) vector. The following
exercise shows this process at work.

Linking Line Segments into Polygons

1 Construct column vectors representing coordinate values:
lat = [3 2 NaN 1 2 NaN 5 6 NaN 3 4]'; lon = [13 12 NaN 11 12 NaN 15 16 NaN 13 14]';
2 Concatenate the segments that match exactly:
[latm,lonm] = polymerge(lat,lon); [latm lonm]
ans =

111
212
313
414
NaN NaN
515
616
NaN NaN

The original four segments are merged into two segments.

The polymerge function takes an optional third argument, a (circular) distance tolerance that permits
inexact matching. A fourth argument enables you to specify whether the function outputs vectors or cell
arrays. See the polymerge reference page for further information.

Geographic Interpolation of Vectors

When using vector data, remember that, like raster data, coordinates are sampled measurements. This
involves unavoidable assumptions concerning what the geographic reality is between specified data
points. The normal assumption when plotting vector data requires that points be connected with straight
line segments, which essentially indicates a lack of knowledge about conditions between the measured
points. For lines that are by nature continuous, such as most rivers and coastlines, such piecewise linear
interpolation can be false and misleading, as the following figure depicts.

Interpolating between sparse data points can mislead Stream channel

Digitized channel
Interpolated points
Interpolating Sparse Vector Data

Despite the possibility of misinterpretation, circumstances do exist in which geographic data

interpolation is useful or even necessary. To do this, use the interpm function to interpolate between
known data points. One value of linearly interpolating points is to fill in lines of constant latitude or
longitude (e.g., administrative boundaries) that can curve when projected.

Interpolating Vectors to Achieve a Minimum Point Density This example interpolates values in a set
of latitude and longitude points to have no more than one degree of separation in either direction.

1 Define two fictitious latitude and longitude data vectors:

lats = [1 2 4 5]; longs = [1 3 4 5];
2 Specify a densification parameter of 1 (the default unit is degrees):
maxdiff = 1;
3 Call interpm to fill in any gaps greater than 1 in either direction:
[newlats,newlongs] = interpm(lats,longs,maxdiff)
newlats =
1.0000
1.5000
2.0000
3.0000
4.0000
5.0000
newlongs =
1.0000
2.0000
3.0000
3.5000
4.0000
5.0000

In lats, a gap of 2 exists between the values 2 and 4. A linearly interpolated point, (3,3.5) was therefore
inserted in newlats and newlongs. Similarly, in longs, a gap of 2 exists between the 1 and the 3. The point
(1.5, 2) was therefore interpolated and placed into newlats and newlongs. Now, the separation of adjacent
points is no greater than maxdiff in either newlats or newlongs.

See the interpm reference page for further information.

Interpolating Coordinates at Specific Locations

interpm returns both the original data and new linearly interpolated points. Sometimes, however, you
might want only the interpolated values. The functions intrplat and intrplon work similarly to the MATLAB
interp1 function, and give you control over the method used for interpolation. Note that they only
interpolate and return one value at a time.

Use intrplat to interpolate a latitude for a given longitude. Given a monotonic set of longitudes and their
matching latitude points, you can interpolate a new latitude for a longitude you specify, interpolating
along linear, spline, cubic, rhumb line, or great circle paths. The longitudes must increase or decrease
monotonically. If this is not the case, you might be able to use the intrplon companion function if the
latitude values are monotonic.

Interpolate a latitude corresponding to a longitude of 7.3 in the following data in a linear, great circle,
and rhumb line sense:
1 Define some fictitious latitudes and longitudes:
longs = [1 3 4 9 13]; lats = [57 68 60 65 56];
2 Specify the longitude for which to compute a latitude:
newlong = 7.3;
3 Generate a new latitude with linear interpolation:
newlat = intrplat(longs,lats,newlong,'linear')
newlat = 63.3000
4 Generate the latitude using great circle interpolation:
newlat = intrplat(longs,lats,newlong,'gc')
newlat = 63.5029
5 Generate it again, specifying interpolation along a rhumb line:
newlat = intrplat(longs,lats,newlong,'rh')
newlat = 63.3937
The following diagram illustrates these three types of interpolation. The intrplat function also can perform
spline and cubic spline interpolations.

(65 , 9) Rhumb line latitude = 63.5029

Great circle latitude = 63.3937
Linear latitude = 63.3000

(60, 4) (Longitude = 7.3)

As mentioned above, the intrplon function provides the capability to interpolate new longitudes from a
given set of longitudes and monotonic latitudes.

See the intrplat and intrplon reference pages for further information.

Vector Intersections

A set of Mapping Toolbox functions perform intersection calculations on vector data computed by the
toolbox, which include great and small circles as well as rhumb line tracks. The functions also determine
intersections of arbitrary vector data.

Compute the intersection of a small circle centered at (0,0) with a radius of

1250 nautical miles and a small circle centered at (5N,30E) with a radius of
2500 kilometers:

[lat,long] = scxsc(0,0,nm2deg(1250),5,30,km2deg(2500)) lat =

17.7487 -12.9839 long =

11.0624 16.4170

(17.7N, 11.1E)
(5N, 30E)
2500 km 1250 nm
(0, 0)
(13.0N, 16.4E)

In general, small circles intersect twice or never. For the case of exact tangency, scxsc returns two
identical intersection points. Other similar commands include rhxrh for intersecting rhumb lines, gcxgc for
intersecting great circles, and gcxsc for intersecting a great circle with a small circle.

Imagine a ship setting sail from Norfolk, Virginia (37N,76W), maintaining a steady due-east course
(90), and another ship setting sail from Dakar, Senegal (15N,17W), with a steady northwest course
(315). Where would the tracks of the two vessels cross?

[lat,long] = rhxrh(37,-76,90,15,-17,315)
lat = 37
long =
-41.7028
The intersection of the tracks is at (37N,41.7W), which is roughly 600 nautical miles west of the
Azores in the Atlantic Ocean.

You can also compute the intersection points of arbitrary vectors of latitude and longitude. The polyxpoly
command finds the segments that intersect and interpolates to find the intersection points. The
interpolation is done linearly, as if the points were in a Cartesian x-y coordinate system. The polyxpoly
command can also identify the line segment numbers associated with the intersections:

[xint,yint] = polyxpoly(x1,y1,x2,y2);

If the spacing between points is large, there can be some difference between the intersection points
computed by polyxpoly and the intersections shown on a map display. This is a result of the difference
between straight lines in the unprojected and projected coordinates. Similarly, there can be differences
between the polyxpoly result and intersections assuming great circles or rhumb lines between points.
Calculating Polygon Area

Use the function areaint to calculate geographic areas for vector data in polygon format. The function
performs a numerical integration using Greens Theorem for the area on a surface enclosed by a
polygon. Because this is a discrete integration on discrete data, the results are not exact. Nevertheless,
the method provides the best means of calculating the areas of arbitrarily shaped regions. Better
measures result from better data.

The Mapping Toolbox function areaint (for area by integration), like the other area functions, areaquad and
areamat, returns areas as a fraction of the entire planets surface, unless a radius is provided. Here you
calculate the area of the continental United States using the conus MAT-file. Three areas are returned,
because the data contains three polygons: Long Island, Marthas Vineyard, and the rest of the continental
U.S.:

load conus
earthradius = earthRadius('km');
area = areaint(uslat,uslon,earthradius)

area =
1.0e+06 * 7.9256 0.0035 0.0004

Because the default Earth radius is in kilometers, the area is in square kilometers. From the same
variables, the areas of the Great Lakes can be calculated, this time in square miles:

load conus
earthradius = earthRadius('miles');
area = areaint(gtlakelat,gtlakelon,earthradius)

area =
1.0e+004 * 8.0119 1.0381 0.7634

Again, three areas are returned, the largest for the polygon representing Superior, Michigan, and Huron
together, the other two for Erie and Ontario.

Overlaying Polygons with Set Logic

Polygon set operations are used to answer a variety of questions about logical relationships of vector
data polygon objects. Standard set operations include intersection, union, subtraction, and an exclusive
OR operation. The polybool function performs these operations on two sets of vectors, which can
represent x-y or latitude-longitude coordinate pairs. In computing points where boundaries intersect,
interpolations are carried out on the coordinates as if they were planar. Here is an example that shows all
the available operations.

Intersection Union
Exclusive Or Subtraction

The result is returned as NaN-clipped vectors by default. In cases where it is important to distinguish
outer contours of polygons from interior holes, polybool can also accept inputs and return outputs as cell
arrays. In the cell array format, a cell array entry starts with the list of points making up the outer
contour. Subsequent NaN-clipped faces within the cell entry are interpreted as interior holes.

Overlaying Polygons with the polybool Function The following exercise demonstrates how you can
use polybool:
1 Construct a twelve-sided polygon:

theta = -(0:pi/6:2*pi)'; lat1 = sin(theta);

lon1 = cos(theta);

2 Construct a triangle that overlaps it:

lat2 = [0 1 -1 0]'; lon2 = [0 2 2 0]';
3 Plot the two shapes together with blue and red lines:
axesm miller
plotm(lat1,lon1,'b') plotm(lat2,lon2,'r')

4 Compute the intersection polygon and plot it as a green patch:

[loni,lati] = polybool('intersection',lon1,lat1,lon2,lat2); [lati loni]
geoshow(lati,loni,'DisplayType','polygon','FaceColor','g')

ans = 0 1.0000
-0.4409 0.8819
00
0.4409 0.8819
0 1.0000

5 Compute the union polygon and plot it as a magenta patch:

[lonu,latu] = polybool('union',lon1,lat1,lon2,lat2); [latu lonu]
geoshow(latu,lonu,'DisplayType','polygon','FaceColor','m')

ans =
-1.0000 2.0000
-0.4409 0.8819
-0.5000 0.8660
-0.8660 0.5000
-1.0000 0.0000
-0.8660 -0.5000
-0.5000 -0.8660
0 -1.0000
0.5000 -0.8660
0.8660 -0.5000
1.0000 -0.0000
0.8660 0.5000
0.5000 0.8660
0.4409 0.8819
1.0000 2.0000
-1.0000 2.0000

6 Compute the exclusive OR polygon and plot it as a yellow patch:

[lonx,latx] = polybool('xor',lon1,lat1,lon2,lat2); [latx lonx]
geoshow(latx,lonx,'DisplayType','polygon','FaceColor','y')
ans =
-1.0000 2.0000
-0.4409 0.8819
-0.5000 0.8660
-0.8660 0.5000
-1.0000 0.0000
-0.8660 -0.5000
-0.5000 -0.8660
0 -1.0000
0.5000 -0.8660
0.8660 -0.5000
1.0000 -0.0000
0.8660 0.5000
0.5000 0.8660
0.4409 0.8819
1.0000 2.0000
-1.0000 2.0000
NaN NaN 0.4409 0.8819
00
-0.4409 0.8819
0 1.0000
0.4409 0.8819

7Subtract the triangle from the 12-sided polygon and plot the resulting concave polygon as a white
patch:
[lonm,latm] = polybool('minus',lon1,lat1,lon2,lat2); [latm lonm]
geoshow(latm,lonm,'DisplayType','polygon','FaceColor','w')

ans =
0.8660 0.5000
0.5000 0.8660
0.4409 0.8819
00
-0.4409 0.8819
-0.5000 0.8660
-0.8660 0.5000
-1.0000 0.0000
-0.8660 -0.5000
-0.5000 -0.8660
0 -1.0000
0.5000 -0.8660
0.8660 -0.5000
1.0000 -0.0000
0.8660 0.5000

The final set of colored shapes is shown below. See the polybool reference page for further information.

Cutting Polygons at the Date Line

Polygon set operations treat input vectors as plane coordinates. The polyxpoly function can be confused
by geographic data that has discontinuities in longitude coordinates at date-line crossings. This can
happen when points with longitudes near 180 connect to points with longitudes near -180, as might be
the case for eastern Siberia and Antarctica, and also for small circles and other patch objects generated
by toolbox functions.
Youcanpreparesuchgeographicdataforusewith polybool or for patch rendering by cutting the polygons at
the date line with the flatearthpoly function. The result of flatearthpoly is a polygon with points inserted to
follow the date line up to the pole, traverse the longitudes at the pole, and
returntothedatelinecrossingalongtheotheredgeofthedateline.

Removing Discontinuities from a Small Circle

1 Create an orthographic view of the Earth and plot coast on it:

axesm ortho
setm(gca,'Origin', [60 170]); framem on; gridm on load coast
plotm(lat, long)

2 Generate a small circle that encompasses the North Pole and color it yellow:
[latc,lonc] = scircle1(75,45,30); patchm(latc,lonc,'y')
3 Flatten the small circle with flatearthpoly:
[latf,lonf] = flatearthpoly(latc,lonc);
4 Plot the cut circle that you just generated as a magenta line:
plotm(latf,lonf,'m')
5 Generate a second small circle that does not include a pole:
[latc1 lonc1] = scircle1(20, 170, 30);
6 Flatten it and plot it as a red line:
[latf1,lonf1] = flatearthpoly(latc1,lonc1); plotm(latf1,lonf1,'r')

The following figure shows the result of these operations. Note that the second small circle, which does
not cover a pole, has been clipped into two pieces along the date line. On the right, the polygon for the
first small circle is plotted in plane coordinates to illustrate its flattened shape. The flatearthpoly function
assumes that the interior of the polygon being flattened is in the hemisphere that contains most of its
edge points. Thus a polygon produced by flatearthpoly does not cover more than a hemisphere.

Note As this figure illustrates, you do not need to use flatearthpoly to prepare data for a map display. The
Mapping Toolbox display functions automatically cut and trim geographic data if required by the map
projection. Use this function only when conducting set operations on polygons.

See the flatearthpoly reference page for further information.

Building Buffer Zones

A buffer zone is the area within a specified distance of a map feature. For vector geodata, buffer zones
are constructed as polygons. For raster geodata, buffer zones are collections of contiguous, identically
coded grid cells. When the feature is a polygon, a buffer zone can be defined as the locus of points
within a certain distance of its boundary, either inside or outside the polygon. A buffer zone for a linear
object is the locus of points a certain distance away from it. Buffer zones form equidistant contour lines
around objects. The bufferm function computes and returns vectors that represent a set of points that
define a buffer zone. It forms the buffer by placing small circles at the vertices of the polygon and
rectangles along each of its line segments, and applying a polygon union set operation to these objects.

Generating a Buffer Around a Polygon

Demonstrate bufferm using a polygon representing the Island of Madagascar that you extract from the
 data set. The boundary of Madagascar is passed to bufferm as latitude and longitude vectors.
landareas
Using this data, compute a buffer zone at a distance of 0.75 degrees in from the boundaries of
Madagascar:

1 Create a base map of the area surrounding Madagascar:

ax = worldmap('madagascar');
madagascar = shaperead('landareas',...
'UseGeoCoords', true,...
'Selector', {@(name)strcmpi(name,'Madagascar'), 'Name'}); geoshow(ax, madagascar)

2 Use bufferm to
process the polygon and output a buffer zone .75 degrees inland:
[latb,lonb] = bufferm(madagascar.Lat, madagascar.Lon, .75, 'in');
3 Show the buffer zone in green: geoshow(latb, lonb, 'DisplayType', 'polygon', 'FaceColor', 'green')

Trimming Vector Data to a Rectangular Region

It is not unusual for vector data to extend beyond the geographic region currently of interest. For
example, you might have coastline data for the entire world (such as the coast data set), but are interested
in mapping Australia only. In this and other situations, you might want to eliminate unnecessary data
from the workspace and from calculations in order to save memory or to speed up processing and
display.

Line data and patch data need to be trimmed differently. You can trim line data by simply removing
points outside the region of interest by clipping lines atthemapframeortosomeotherdefinedregion.
Patchdatarequiresamore complicated method to ensure that the patch objects are correctly formed.

For the vector data, two functions are available to achieve this. If the vectors
aretobehandledaslinedata,the maptriml function returns variables containing only those points that lie
within the defined region. If, instead, you want to maintain polygon format, use the maptrimp function. Be
aware, however, that patch-trimmed data is usually larger and more expensive to compute.

Note When drawing maps, Mapping Toolbox display functions automatically trim vector geodata to the
region specified by the frame limits (FLatLimit and FLonLimit map axes properties) for azimuthal
projections, or to frame or map limits (MapLatLimit and MapLonLimit map axes properties) for
nonazimuthal projections. The trimming is done internally in the display routine, keeping the original
data intact. For further information on trimming vector geodata, see Axes for Drawing Maps on page
4-12, along with the reference pages for the trimming functions.
Trimming Vectors to Form Lines and Polygons
1 Load the coast MAT-file for the entire world:
load coast
2 Define a region of interest centered on Australia:
latlim = [-50 0]; longlim = [105 160];
3 Use maptriml to delete all data outside these limits, producing line vectors:
[linelat,linelong] = maptriml(lat,long,latlim,longlim);
4 Do this again, but use maptrimp to produce polygon vectors:
[polylat,polylong] = maptrimp(lat,long,latlim,longlim);
5 See how much data has been reduced:
whos
Name Size Bytes Class

lat 9589x1 76712 double latlim 1x2 16 double linelat 870x1 6960 double linelong 870x1 6960 double long 9589x1 76712
double longlim 1x2 16 double polylat 878x1 7024 double polylong 878x1 7024 double

Note that the clipped data is only 10% as large as the original data set.
6 Plot the trimmed patch vectors on a Miller projection:

axesm('MapProjection', 'miller', 'Frame', 'on',... 'FlatLimit', latlim, 'FlonLimit', longlim) patchesm(polylat, polylong, 'c')

7 Plot the trimmed line vectors to see that they conform to the patches:

plotm(linelat, linelong, 'm') See the maptriml and

maptrimp reference pages for further information.

Trimming Vector Data to an Arbitrary Region

Often a set of data contains unwanted data mixed in with the desired values. For example, your data
might include vectors covering the entire United States, but you only want to work with those falling in
Alabama. Sometimes a data set contains noiseperhaps three or four points out of several thousand are
obvious errors (for example, one of your city points is in the middle of the ocean). In such cases,
locating outliers and errors in the data arrays can be quite tedious.

The filterm command uses a data grid to filter a vector data set. Its calling sequence is as follows:
[flats,flons] = filterm(lats,lons,grid,refvector,allowed)

Each location defined by lats and lons is mapped to a cell in grid,andthe value of that grid cell is obtained.
If that value is found in allowed, that point is output to flats and flons. Otherwise, the point is filtered out.

The grid might encode political units, and the allowed values might be the code or codes indexing
certain states or countries (e.g., Alabama). The grid might also be real-valued (e.g., terrain elevations),
although it could be awkward to specify all the values allowed. More often, logical or relational
operators give better results for such grids, enabling the allowed value to be 1 (for true). For example,
you could use this transformation of the topo grid:

[flats,flons] = filterm(lats,lons,double(topo>0),topolegend,1)
The output would be those points in lats and lons that occupy dry land (mostly because some water bodies
are above sea level).
For further information, see the filterm reference page. Also see Data Grids as Logical Variables on
page 7-39.

Simplifying Vector Coordinate Data

Avoiding visual clutter in composing maps is an essential part of cartographic presentation. In

cartography, this is described as map generalization, which involves coordinating many techniques, both
manual and automated. Limiting the number of points in vector geodata is an important part of
generalizing maps, and is especially useful for conditioning cartographic data, plotting maps at small
scales, and creating versions of geodata for use at small scales.

An easy, but naive, approach to point reduction is to discard every nth element in each coordinate vector
(simple decimation). However, this can result in poor representations of the original shapes. The toolbox
provides a function to eliminate insignificant geometric detail in linear and polygonal objects, while still
maintaining accurate representations of their shapes. The reducem function implements a powerful line
simplification algorithm (known as Douglas-Peucker) that intelligently selects and deletes visually
redundant points.

The reducem function takes latitude and longitude vectors, plus an optional linear tolerance parameter as
arguments, and outputs reduced (simplified) versions of the vectors, in which deviations perpendicular
to local trend lines in the vectors are all greater than the tolerance criterion. Endpoints of vectors are
preserved. Optional outputs are an error measure and the tolerance value used (it is computed when you
do not supply a value).

Note Simplified line data might not always be appropriate for display. If all or most intermediate points
in a feature are deleted, then lines that appear straight in one projection can be incorrectly displayed as
straight lines in others, and separate lines can be caused to intersect. In addition, when you are reducing
data over large world regions, the effective degree of reduction near the poles are less than that achieved
near the equator, due to the fact that the algorithm treats geographic coordinates as if they were planar.
Using reducem to Simplify Lines
The reducem function works on both patch and line data. Getting results that look right at an intended
scale might require some experimentation with the toleranceparameter.
Thebestwaytoproceedmightbetoallowthetolerance to default, and have reducem return the tolerance it
computed as the fourth return argument. If the output still has too much detail, then double the tolerance
and try again. Similarly, if the output lines do not have enough detail, halve the tolerance and try again.
You can also use the third return parameter, which indicates the percentage of line length that was
eliminated by reduction, as a guide to achieve consistent simplification results, although this parameter
is sensitive to line geometry and thus can vary by feature type.

To demonstrate the use of reducem, this example extracts the outline of the state of Massachusetts from
the usastatehi high-resolution shapefile:
1 Read Massachusetts data from the shapefile. Use the Selector parameter to read only the vectors
representing the Massachusetts state boundaries:
ma = shaperead('usastatehi.shp',...
'UseGeoCoords', true,...
'Selector', {@(name)strcmpi(name,'Massachusetts'), 'Name'});

2 Extract the coordinate data for simplification. There are 957 points to begin with:
maLat = ma.Lat; maLon = ma.Lon; numel(maLat)

ans = 957
3 Use reducem to simplify the boundary vectors, and inspect the results:
[maLat1, maLon1, cerr, tol] = reducem(maLat', maLon'); numel(maLat1)
ans = 252
4 The number of points used to represent the boundary has dropped from 958 to 253. Compute the
degree of reduction:
numel(maLat1)/numel(maLat)
ans = 0.2633
The vectors have been reduced to about a quarter of their original size using the default tolerance.
5 Examine the error and tolerance values returned by reducem:
[cerr tol]
ans =
0.0331 0.0060

The cerr value says that only 3.3% of total boundary length was eliminated (despite removing 74% of the
points). The tolerance that achieved this was computed by reducem as 0.006 decimal degrees, or about
0.66 km. 6 Use geoshow to plot the reduced outline in red over the original outline

in blue:

figure
axesm('MapProjection', 'eqdcyl', 'FlatLim', [41.1 43.0],... 'FlonLim', [-69.8, -73.6], 'Frame', 'off', 'Grid', 'off'); geoshow(maLat,
maLon, 'DisplayType', 'line', 'color', 'blue') geoshow(maLat1, maLon1, 'DisplayType', 'line', 'color', 'red')

Differences in details are not apparent unless you zoom in two or three times; click the Zoom tool to
explore the map.
7 Double the tolerance, and reduce the original boundary into new variables:
[maLat2,maLon2,cerr2,tol2] = reducem(maLat', maLon', 0.012);
8 Repeat step 3 with new data and plot it in dark green:
numel(maLat2)/numel(maLat)
ans = 0.1641
[cerr2 tol2]
ans = 0.0517 0.0120
geoshow(maLat2, maLon2, 'DisplayType', 'line', 'color', [0 .6 0])
Now you have removed 84% of the points, and 5.2% of total length.
9 Repeat one more time, raising the tolerance to 0.1 degrees, and plot the result in black:
[maLat3, maLon3, cerr3, tol3] = reducem(maLat', maLon', 0.1); geoshow(maLat3, maLon3, 'DisplayType', 'line', 'color',
'black')

As overlaid with the original data, the reduced state boundaries look like this.
As this example and the composite map below demonstrate, the visual effects of point reduction are
subtle, up to a point. Most of the vertices can be eliminated before the effects of line simplification are
very noticeable. Experimentation is usually required, because the visual effects a given value for a
tolerance yield depend on the degrees and types of line complexity, and they are often nonlinear with
respect to tolerance values. Also, the extent of line detail reduction should be informed by the purpose of
the map and the scale at which it is to be displayed.

Note This exercise generalized a set of disconnected patches. When patches are contiguous (such as the
U.S. state outlines), using reducem can result in inconsistencies in boundary representation and gaps at
points where states meet. For best results, reducem should be applied to line data.

42.5 N 42.5 N

42.0 N 42.0 N
No reduction Tol: 0.006 deg.
41.5 N 957 points (100%)41.5 N 252 points (26%)

73 W 72 W 71 W 70 W 73 W 72 W 71 W 70 W
42.5 N 42.5 N

42.0 N 42.0 N
Tol: 0.012 deg Tol: 0.100 deg
41.5 N 157 points (16%)41.5 N 32 points (3%)

73 W 72 W 71 W 70 W 73 W 72 W 71 W 70 W See the reducem reference page for further

information.

Manipulating Raster Geodata

In this section...
Vector-to-Raster Data Conversion on page 7-31 Data Grids as Logical Variables on page 7-39 Data
Grid Values Along a Path on page 7-41 Data Grid Gradient, Slope, and Aspect on page 7-43
Vector-to-Raster Data Conversion

You can convert latitude-longitude vector data to a grid at any resolution you choose to make a raster
base map or grid layer. Certain Mapping Toolbox GUI tools help you do some of this, but you can also
perform vector-to-raster conversions from the command line. The principal function for gridding vector
data is vec2mtx, which allocates lines to a grid of any size you indicate, marking the lines with 1s and the
unoccupied grid cells with 0s. The grid contains doubles, but if you want a logical grid (see Data Grids
as Logical Variables on page 7-39, below) cast the result to be a logical array.

If the vector data consists of polygons (patches), the gridded outlines are all hollow. You can
differentiate them using the encodem function, calling it with an array of rows, columns, and seed values
to produce a new grid containing polygonal areas filled with the seed values to replace the binary values
generated by vec2mtx.

Creating Data Grids from Vector Data

To demonstrate vector-to-raster data conversion, use patch data for Indiana from the usastatehi shapefile:

1 Use shaperead to get the patch data for the boundary:

indiana = shaperead('usastatehi.shp',...
'UseGeoCoords', true,...
'Selector', {@(name)strcmpi('Indiana',name), 'Name'});

inLat = indiana.Lat;
inLon = indiana.Lon;
2 Set the grid density to be 40 cells per degree, and use vec2mtx to rasterize the boundary and generate a
referencing vector for it:
gridDensity = 40;
[inGrid, inRefVec] = vec2mtx(inLat, inLon, gridDensity); whos

Name Size Bytes Class

gridDensity 1x1 8 double inGrid 164x137 179744 double inLat 1x626 5008 double inLon 1x626 5008 double inRefVec 1x3
24 double indiana 1x1 10960 struct

The resulting grid contains doubles, and has 80 rows and 186 columns.
3 Make a map of the data grid in contrasting colors:

figure
axesm eqdcyl
meshm(inGrid, inRefVec) colormap jet(4)
 4 Set up the map limits:

[latlim, lonlim] = limitm(inGrid, inRefVec); setm(gca, 'Flatlimit', latlim, 'FlonLimit', lonlim) tightmap

5To fill (recode) the interior of Indiana, you need a seed point (which must be identified by row and
column) and a seed value (to be allocated to all cells within the polygon). Select the middle row and
column of the grid and choose an index value of 3 to identify the territory when calling encodem to
generate a new grid:
inPt = round([size(inGrid)/2, 3]);
inGrid3 = encodem(inGrid, inPt,1);
Thelastargument(1) identifies the code for boundary cells, where filling should halt.
6 Clear and redraw the map using the filled grid:
meshm(inGrid3, inRefVec)

7 Plot the original vectors on the grid to see how well data was
rasterized:
plotm(inLat, inLon,'k')

The resulting map is shown on the left below. Use the Zoom tool on
thefigurewindowtoexaminethegriddingresultsmoreclosely,asthe right-hand figure shows.
See the vec2mtx and encodem reference pages for further information. imbedm is a related function for
gridding point values.

Using a GUI to Rasterize Polygons

In the previous example, had you wanted to include the states that border Indiana, you could also have
extracted Illinois, Kentucky, Ohio, and Michigan, and then deleted unwanted areas of these polygons
using maptrimp (see Trimming Vector Data to a Rectangular Region on page 7-21 for specific
detailsonitsuse). Usethe seedm function with seed points found using the getseeds GUI to fill multiple
polygons after they are gridded:

1 Extract the data for Indiana and its neighbors by passing their names in acell array to shaperead:
pcs = {'Indiana', 'Michigan', 'Ohio', 'Kentucky', 'Illinois'};

centralUS = shaperead('usastatelo.shp',...
'UseGeoCoords', true,...
'Selector',{@(name)any(strcmpi(name,pcs),2), 'Name'}); meLat = [centralUS.Lat]; meLon = [centralUS.Lon];

2 Rasterize the trimmed polygons at a 1-arc-minute resolution (60 cells per degree), also producing a
referencing vector:
[meGrid, meRefVec] = vec2mtx(meLat, meLon, 60);
3 Set up a map figure and display the binary grid just created:

figure
axesm eqdcyl
geoshow(meLat, meLon, 'Color', 'r'); meshm(meGrid, meRefVec)
colormap jet(8)
 4 Use getseeds to interactively pick seed points for Indiana,
Michigan, Ohio, Kentucky, and Illinois, in that order:
[row,col,val] = getseeds(meGrid, meRefVec, 5, [3 4 5 6 7]);

[row col val]

ans =
207 140 3 219 326 4 212 506 5

56 459 6 393 433 7

The MATLAB prompt returns after you pick five locations in the figure window. As you chose them
yourself, your row and col numbers will differ.
5 Use encodem to fill each country with a unique value, producing a new grid:
meGrid5 = encodem(meGrid, [row col val], 1);
6 Clear the display and display meGrid5 to see the result:
clma
meshm(meGrid5, meRefVec)

The rasterized map of Indiana and its neighbors is shown below.

See the getseeds reference page for more information. The maptrim and seedm GUI tools are also useful in
this context.

Data Grids as Logical Variables

You can apply logical criteria to numeric data grids to create logical grids. Logical grids are data grids
consisting entirely of 1s and 0s. You can create them by performing logical tests on data grid variables.
The resulting binary grid is the same size as the original grid(s) and can use the same referencing vector,
as the following hypothetical data operation illustrates:

logicalgrid = (realgrid > 0);

This transforms all values greater than 0 into 1s and all other values to 0s. You can apply multiple
conditions to a grid in one operation:
logicalgrid = (realgrid >- 100)&(realgrid < 100);

If several grids are the same size and share the same referencing vector (i.e., the grids are co-registered),
you can create a logical grid by testing joint conditions, treating the individual data grids as map layers:

logicalgrid = (population > 10000)&(elevation < 400)&... (country == nigeria);

Several Mapping Toolbox functions enable the creation of logical grids using logical and relational
operators. Grids resulting from such operations contain logical rather than numeric values (which reduce
storage by a factor of 8), but mightneedtobecastto doubleinordertobeusedincertainfunctions. Use the onem
and zerom functions to create grids of all 1s and all 0s.

Obtaining the Area Occupied by a Logical Grid Variable You can analyze the results of logical grid
manipulations to determine the area satisfying one or more conditions (either coded as 1s or an
expression that yields a logical value of 1). The areamat function can provide the fractional surface area
on the globe associated with 1s in a logical grid. Each grid element is a quadrangle, and the sum of the
areas meeting the logical condition provides the total area:
1 You can use the topo grid and the greater-than relational operator to

determine what fraction of the Earth lies above sea level:

load topo
topoR = makerefmat('RasterSize', size(topo), ... 'Latlim', [-90 90], 'Lonlim', [0 360]);

a = areamat((topo > 0),topoR)

a=
0.2890
The answer is about 30%. (Note that land areas below sea level are excluded.)

2 You can include a planetary radius in specified units if you want the result to have those units. Here is
the same query specifying units of square kilometers:

a = areamat((topo > 0),topoR,earthRadius('km'))

a=
1.4739e+08

3 Use the usamtx data grid codes to find the area of a specific state within
theU.S.A.Asanexample,determinetheareaofthestateofTexas,which is coded as 46 in the usamtx grid:

load usamtx
a = areamat((map == 46), refvec, earthRadius('km'))
a= 6.2528e+005
The grid codes 625,277 square kilometers of land area as belonging to the U.S.

4You can construct more complex queries. For instance, using the last example, compute what portion
of the land area of the conterminous U.S. that Texas occupies (water and bordering countries are coded
with 2 and 3, respectively):

usaland = areamat((map > 3 | map == 1), maplegend); texasland = areamat((map == 46), maplegend); texasratio = texasland/
usaland

texasratio = 0.0735
This indicates that Texas occupies roughly 7.35% of the land area of the U.S.
For further information, see the areamat reference page.

Data Grid Values Along a Path

A common application for gridded geodata is to calculate data values along a path, for example, the
computation of terrain height along a transect, a road, or a flight path. The mapprofile function does this,
based on numerical data defining a set of waypoints, or by defining them interactively via graphic input
from a map display. Values computed for the resulting profile can be displayed in a new plot or returned
as output arguments for further analysis or display.
Using the mapprofile Function
The following example computes the elevation profile along a straight line:
1 Load the Korean elevation data:
figure;
load korea
2 Get its latitude and longitude limits using limitm and use them to set up a map frame via worldmap:
[latlim, lonlim] = limitm(map, maplegend); worldmap(latlim, lonlim)
worldmap plots only the map frame. 3 Render the map and apply a digital elevation model (DEM)
colormap to it:
meshm(map,maplegend,size(map),map) demcmap(map)
4 Define endpoints for a straight-line transect through the region:
plat = [40.5 30.7]; plon = [121.5 133.5];
5 Compute the elevation profile, defaulting the track type to great circle and the interpolation type to
bilinear:
[z,rng,lat,lon] = mapprofile(map,maplegend,plat,plon);
6 Draw the transect in 3-D so it follows the terrain:
plot3m(lat,lon,z,'w','LineWidth',2)

7 Construct a plot of transect elevation and

range:
figure; plot(rng,z,'r')

The mapprofile function has other useful options, including the ability to interactively define tracks and
specify units of distance for them. For further information, see the mapprofile reference page.

Data Grid Gradient, Slope, and Aspect

A map profile is often used to determine slopes along a path. A related application is the calculation of
slope at all points on a matrix. The gradientm function uses a finite-difference approach to compute
gradients for either a regular or a georeferenced data grid. The function returns the components of the
gradient in the north and east directions (i.e., north-to-south, east-to-west), as well as slope and aspect.
The gradient components are the change in the grid variable per meter of distance in the north and east
directions. If the grid contains elevations in meters, the aspect and slope are the angles of the surface
normal clockwise from north and up from the horizontal. Slope is defined as the change in elevation per
unit distance along the path of steepest ascent or descent from a grid cell to one of its eight immediate
neighbors, expressed as the arctangent. The angles are in units of degrees by default.

Computing Gradient Data from a Regular Data Grid The following example illustrates computation
of gradient, slope, and aspect data grids for a regular data grid based on the MATLAB peaks function:

1 Construct a 100-by-100 grid using the peaks function and construct a referencing matrix for it:
datagrid = 500*peaks(100);
R = makerefmat('RasterSize',size(datagrid));
2 Use gradientm to generate grids containing aspect, slope, gradients to north, and gradients to east:
[aspect,slope,gradN,gradE] = gradientm(datagrid,R); whos
Name Size Bytes Class
aspect 100x100 80000 double datagrid 100x100 80000 double gradE 100x100 80000 double gradN 100x100 80000 double
gridrv 1x3 24 double slope 100x100 80000 double

3 Map the surface data in a cylindrical equal area projection. Start with the original elevations:
figure; axesm eqacyl meshm(datagrid,R) colormap (jet(64)) colorbar('vert') title('Peaks: elevation') axis square

4 Clear the frame and display the slope grid:

figure; axesm eqacyl meshm(slope,R)
colormap (jet(64)) colorbar('vert'); title('Peaks: slope')

5 Map the aspect grid:

figure; axesm eqacyl meshm(aspect,R)
colormap (jet(64)) colorbar('vert');
title('Peaks: aspect')

6 Map the gradients to the north:

figure; axesm eqacyl
meshm(gradN,R)
colormap (jet(64))
colorbar('vert');
title('Peaks: North gradient')

7 Finally, map the gradients to the east:

figure; axesm eqacyl

meshm(gradE,R)
colormap (jet(64))
colorbar('vert');
title('Peaks: East gradient')

The maps of the peaks surface elevation and gradient data are shown below. See the gradientm reference
page for additional information.
Using Map Projections and Coordinate Systems
All geospatial data must be flattened onto a display surface in order to visually portray what exists
where. The mathematics and craft of map projection are central to this process. Although there is no
limit to the ways geodata can be projected, conventions, constraints, standards, and applications
generally prescribeitsusage. Thischapterdescribeswhatmapprojectionsare,how they are constructed and
controlled, their essential properties, and some possibilities and limitations.

What Is a Map Projection? on page 8-2

Quantitative Properties of Map Projections on page 8-3
The Three Main Families of Map Projections on page 8-5
Projection Aspect on page 8-10
Projection Parameters on page 8-18
Visualizing and Quantifying Projection Distortions on page 8-27
Accessing, Computing, and Inverting Map Projection Data on page 8-37
Working with the UTM System on page 8-51
Summary and Guide to Projections on page 8-63
If you are not acquainted with the types, properties, and uses of map projections, read the first four
sections. When constructing mapsespecially in an environment in which a variety of projections are
readily availableit is important to understand how to evaluate projections to select one appropriate to
the contents and purpose of a given map.

What Is a Map Projection?

Human beings have known that the shape of the Earth resembles a sphere and not a flat surface since
classical times, and possibly much earlier than that. If the world were indeed flat, cartography would be
much simpler because map projections would be unnecessary.

To represent a curved surface such as the Earth in two dimensions, you must geometrically transform
(literally, and in the mathematical sense, map) that surface to a plane. Such a transformation is called a
map projection.The term projection derives from the geometric methods that were traditionally used to
construct maps, in the fashion of optical projections made with a device called camera obscura that
Renaissance artists relied on to render three-dimensional perspective views on paper and canvas.

While many map projections no longer rely on physical projections, it is useful to think of map
projections in geometric terms. This is because map projection consists of constructing points on
geometric objects such as cylinders, cones, and circles that correspond to homologous points on the
surface of the planet being mapped according to certain rules and formulas.

The following sections describe the basic properties of map projections, the surfaces onto which
projections are developed, the types of parameters associated with different classes of projections, how
projected data can be mapped back to the sphere or spheroid it represents, and details about one very
widely used projection system, called Universal Transverse Mercator.

Note Most map projections in the toolbox are implemented as MATLAB functions; however, these are
only used by certain calling functions (such as geoshow and axesm), and thus have no documented public
API.

For more detailed information on specific projections, browse the Supported Map Projections. For
further reading, Appendix A, Bibliography provides references to books and papers on map
projection.

Quantitative Properties of Map Projections

A sphere, unlike a polyhedron, cone, or cylinder, cannot be reformed into a plane. In order to portray the
surface of a round body on a two-dimensional flat plane, you must first define a developable surface
(i.e., one that can be cut and flattened onto a plane without stretching or creasing) and devise rules for
systematically representing all or part of the spherical surface on the plane. Any such process inevitably
leads to distortions of one kind or another. Five essential characteristic properties of map projections are
subject to distortion: shape, distance, direction, scale,and area. No projection can retain more than one
of these properties over a large portion of the Earth. This is not because a sufficiently clever projection
has yet to be devised; the task is physically impossible. The technical meanings of these terms are
described below.
 Shape (also called conformality)

Shape is preserved locally (within small areas) when the scale of a map at any point on the map is the
same in any direction. Projections with this property are called conformal. In them, meridians (lines of
longitude) and parallels (lines of latitude) intersect at right angles. An older term for conformal is
orthomorphic (from the Greek orthos, straight, and morphe, shape).

Distance (also called equidistance)

A map projection can preserve distances from the center of the projection to all other places on the map
(but from the center only). Such a map projection is called equidistant. Maps are also described as
equidistant when the separation between parallels is uniform (e.g., distances along meridians are
maintained). No map projection maintains distance proportionality in all directions from any arbitrary
point.

Direction

A map projection preserves direction when azimuths (angles from the central point or from a point on a
line to another point) are portrayed correctly in all directions. Many azimuthal projections have this
property.

Scale

Scaleistheratiobetweenadistanceportrayedonamapandthesame extent on the Earth. No projection

faithfully maintains constant scale over
largeareas,butsomeareabletolimitscalevariationtooneortwopercent.
Area (also called equivalence)

A map can portray areas across it in proportional relationship to the areas on the Earth that they
represent. Such a map projection is called equal-area or equivalent. Two older terms for equal-area are
homolographic or homalographic (from the Greek homalos or homos, same, and graphos, write), and
authalic (from the Greek autos, same, and ailos,area),and equireal. Notethatnomapcanbebothequal-
areaandconformal.

For a complete description of the properties that specific map projections maintain, see Summary and
Guide to Projections on page 8-63.

The Three Main Families of Map Projections

In this section...
Unwrapping the Sphere to a Plane on page 8-5 Cylindrical Projections on page 8-5
Conic Projections on page 8-7
Azimuthal Projections on page 8-8
Unwrapping the Sphere to a Plane

Mapmakers have developed hundreds of map projections, over several thousand years. Three large
families of map projection, plus several smaller ones, are generally acknowledged. These are based on
the types of geometric shapes that are used to transfer features from a sphere or spheroid to a plane. As
described above, map projections are based on developable surfaces, and the three traditional families
consist of cylinders, cones, and planes. They are used to classify the majority of projections, including
some that are not analytically (geometrically) constructed. In addition, a number of map projections are
based on polyhedra. While polyhedral projections have interesting and useful properties, they are not
described in this guide.

Which developable surface to use for a projection depends on what region is to be mapped, its
geographical extent, and the geometric properties that areas, boundaries, and routes need to have, given
the purpose of the map. The following sections describe and illustrate how the cylindrical, conic, and
azimuthal families of map projections are constructed and provides some examples of projections that
are based on them.

Cylindrical Projections

A cylindrical projection is produced by wrapping a cylinder around a globe representing the Earth. The
map projection is the image of the globe projected onto the cylindrical surface, which is then unwrapped
into a flat surface. When the cylinder aligns with the polar axis, parallels appear as horizontal lines and
meridians as vertical lines. Cylindrical projections can be either equal-area, conformal, or equidistant.
The following figure shows a regular cylindrical or normal aspect orientation in which the cylinder is
tangent to the Earth along the Equator and the projection radiates horizontally from the axis of rotation.
The projection method is diagrammed on the left, and an example is given on the right (equal-area
cylindrical projection, normal/equatorial aspect).

For a description of projection aspect, see Projection Aspect on page 8-10.

Some widely used cylindrical map projections are

Equal-area cylindrical projection

Equidistant cylindrical projection
 Mercator projection
Miller projection
Plate Carre projection
Universal transverse Mercator projection

Pseudocylindrical Map Projections

All cylindrical projections fill a rectangular plane. Pseudocylindrical projection outlines tend to be
barrel-shaped rather than rectangular. However, they do resemble cylindrical projections, with straight
and parallel latitude lines, and can have equally spaced meridians, but meridians are curves, not straight
lines. Pseudocylindrical projections can be equal-area, but are not conformal or equidistant.

Some widely-used pseudocylindrical map projections are

Eckert projections (I-VI)

Goode homolosine projection
Mollweide projection
Quartic authalic projection
Robinson projection
Sinusoidal projection

Conic Projections

A conic projection is derived from the projection of the globe onto a cone placed over it. For the normal
aspect, the apex of the cone lies on the polar axis of the Earth. If the cone touches the Earth at just one
particular parallel of latitude, it is called tangent. If made smaller, the cone will intersect the Earth twice,
in which case it is called secant. Conic projections often achieve less distortion at mid- and high
latitudes than cylindrical projections. A further elaboration is the polyconic projection, which deploys a
family of tangent or secant cones to bracket a succession of bands of parallels to yield even less scale
distortion. The following figure illustrates conic projection, diagramming its construction on the left,
with an example on the right (Albers equal-area projection, polar aspect).

Some widely-used conic projections are

 Albers Equal-area projection
Equidistant projection
Lambert conformal projection
Polyconic projection

Azimuthal Projections

An azimuthal projection is a projection of the globe onto a plane. In polar aspect, an azimuthal
projection maps to a plane tangent to the Earth at one of the poles, with meridians projected as straight
lines radiating from the pole, and parallels shown as complete circles centered at the pole. Azimuthal
projections (especially the orthographic) can have equatorial or oblique aspects. The projection is
centered on a point, that is either on the surface, at the center of the Earth, at the antipode, some distance
beyond the Earth, or at infinity. Most azimuthal projections are not suitable for displaying the entire
Earth in one view, but give a sense of the globe. The following figure illustrates azimuthal projection,
diagramming it on the left, with an example on the right (orthographic projection, polar aspect).

Some widely used azimuthal projections are

Equidistant azimuthal projection

Gnomonic projection
Lambert equal-area azimuthal projection
Orthographic projection
Stereographic projection
Universal polar stereographic projection

For additional information on families of map projections and specific map projections, see Supported
Map Projections.
Projection Aspect

A map projections aspect is its orientation on the page or display screen. If north or south is straight up,
the aspect is said to be equatorial;formost projectionsthisisthe normal aspect. When the central axis of
the developable surface is oriented east-west, the projections aspect is transverse. Projections centered
on the North Pole or the South Pole have a polar aspect, regardless of what meridian is up. All other
orientations have an oblique aspect. So far, the examples and discussions of map displays have focused
on the normal aspect, by far the most commonly used. This section discusses the use of transverse,
oblique,and skew-oblique aspects.

Projection aspect is primarily of interest in the display of maps. However, this section also discusses
how the idea of projection aspect as a coordinate system transformation can be applied to map variables
for analytical purposes.

The Orientation Vector

A map axes Origin property is a vector describing the geometry of the displayed projection. This
Mapping Toolbox property is called an orientation vector (prior versions called it the origin vector). The
vector takes this form:

orientvec = [latitude longitude orientation]

The latitude and longitude represent the geographic coordinates of the center point of the display from
which the projection is calculated. The orientation refers to the clockwise angle from straight up at
which the North Pole points from this center point. The default orientation vector is [0 0 0]; that is, the
projection is centered on the geographic point (0,0) and the North Pole is straight up from this point.
Such a display is in a normal aspect. Changes to only the longitude value of the orientation vector do not
change the aspect; thus, a normal aspect is one centered on the Equator in latitude with an orientation of
0.

Both of these Miller projections have normal aspects, despite having different orientation vectors:

Origin at (0,0) with a 0

orientation Origin at (0,90W) with a 0 orientation (orientation vector = [0 0 0]) (orientation vector =
[0 -90 0])

This makes sense if you think about a simple, true cylindrical projection. This is the projection of the
globe onto a cylinder wrapped around it. For normal aspects, this cylinder is tangent to the globe at the
Equator, and changing the origin longitude simply corresponds to rotating the sphere about the
longitudinal axis of the cylinder. If you continue with the wrapped-cylinder model, you can understand
the other aspects as well.

Following this description, a transverse projection can be thought of as a cylinder wrapped around the
globe tangent at the poles and along a meridian and its antipodal meridian. Finally, when such a cylinder
is tangent along any great circle other than a meridian, the result is an oblique projection.

Here are diagrams of the four cylindrical map orientations, or aspects:

Normal Transverse
Oblique Skew-Oblique
Of course, few projections are true cylindrical projections, but the concept of the wrapped cylinder is
nonetheless a convenient way to describe aspect.

Exploring Projection Aspect

Perhaps the best way to gain an understanding of projection aspect is to experiment with orientation
vectors. For the following exercise, use a pseudocylindrical projection, the sinusoidal.

1 Create a default map axes in a sinusoidal projection, turn on the graticule, and display the coast data set
as filled polygons:

figure;
axesm sinusoid
framem on; gridm on; tightmap tight load coast
patchm(lat, long,'g')

The continents and graticule appear in normal aspect, as shown below.

Normal aspect: origin at (0,0), orientation 0 (orientation vector = [0 0 0])

2 Inspect the orientation vector from the map axes:
getm(gca,'Origin')
ans =
000
By default, the origin is set at (0E, 0N), oriented 0 from vertical.

3 In the normal aspect, the North Pole is at the topoftheimage. Tocreate a transverse aspect, imagine
pulling the North Pole down to the center of the display, which was originally occupied by the point
(0,0). Do this by setting the first element of Origin parameter to a latitude of 90N:

setm(gca,'Origin',[90 0 0])
The shape of the frame is unaffected; this is still a sinusoidal projection.

Transverse aspect: origin at (90N,0), orientation 0 (orientation vector = [90 0 0])

4 The normal and transverse aspects can be thought of as limiting conditions. Anything else is an
oblique aspect. Conceptually, if you push the North Pole halfway back to its original position (to the
position originally occupied by the point (45N, 0E) in the normal aspect), the result is a simple oblique
aspect.

setm(gca,'Origin',[45 0 0])
The oblique sinusoidal projection centered at (45N, 0E) is shown below.
Oblique aspect: origin at (45N,0), orientation 0 (orientation vector = [45 0 0])
You can think of this as pulling the new origin (45N, 0) to the center of the image, the place that (0,0)
occupied in the normal aspect.

5 The previous examples of projection aspect kept the aspect orientation at 0. If the orientation is
altered, an oblique aspect becomes a skew-oblique. Imagine the previous example with an orientation of
45. Think of this as pulling the new origin (45N,0E), down to the center of the projection and then
rotating the projection until the North Pole lies at an angle of 45 clockwise from straight up with respect
to the new origin.

setm(gca,'Origin',[45 0 45])
As in the previous example, the location (45N,0E) still occupies the center of the map.
Skew-oblique aspect: origin at (45N,0), orientation 45 (orientation vector = [45 0 45])

Any projection can be viewed in alternate aspects. Some of these are quite useful. For example, the
transverse aspect of the Mercator projection is widely used in cartography, especially for mapping
regions with predominantly north-south extent. One candidate for such handling might be Chile.
Oblique Mercator projections might be used to map long regions that run neither north and south nor
east and west, such as New Zealand.

Note The projection aspect discussed in this section is different from the map axes Aspect property. The
map axes Aspect property controls the orientation of the figure axes. For instance, if a map is in a normal
setting with a landscape orientation, a switch to a transverse aspect rotates the axes by 90, resulting in a
portrait orientation. To display a map in the transverse aspect, combine the transverse aspect property with
a -90 skew angle. The skew angle is the last element of the Origin parameter. For example, a [0 0 -90]
vector would produce a transverse map.

The base projection can be thought of as a standard coordinate system, and the normal aspect conforms
to it. The features of a projection are maintained in any aspect, relative to the base projection. As the
preceding illustrations show, the outline (frame) does not change. Nondirectional projection
characteristics also do not change. For example, the sinusoidal projection is equal-area, no matter what
its aspect. Directional characteristics must be considered carefully, however. In the normal aspect of the
sinusoidal projection, scale is true along every parallel and the central meridian. This is not the case for
the skew-oblique aspect; however, scale is true along the paths of the transformed parallels and
meridian.

Projection Parameters

Every projection has at least one parameter that controls how it transforms geographic coordinates into
planar coordinates. Some projections are rather fixed, and aside from the orientation vector and nominal
scale factor, have no parameters that the user should vary, as to do so would violate the definition of the
projection. For example, the Robinson projection has one standard parallel that is fixed by definition at
38 North and South; the Cassini and Wetch projections cannot be constructed in other than Normal
aspect. In general, however, projections have several variable parameters. The following section
discusses map projection parameters and provides guidance for setting them.

Projection Characteristics Maps Can Have

In addition to the name of the projection itself, the parameters that a map projection can have are

Aspect Orientation of the projection on the display surface

Center or Origin Latitude and longitude of the midpoint of the display
Scale Factor Ratio of distance on the map to distance on the ground
Standard Parallel(s) Chosen latitude(s) where scale distortion is zero
False Northing Planar offset for coordinates on the vertical map axis
False Easting Planar offset for coordinates on the horizontal map axis

Zone Designated latitude-longitude quadrangle used to systematically partition the planet for certain
classes of projections
Whilenotallprojectionsrequirealltheseparameters,therewillalwaysbea projection aspect, origin, and scale.
Other parameters are associated with the graphic expression of a projection, but do not define its
mathematical outcome. These include

Map latitude and longitude limits

Frame latitude and longitude limits

However, as certain projections are unable to map an entire planet, or become very distorted over large
regions, these limits are sometimes a necessary part of setting up a projection.

Determining Projection Parameters

In the following exercise, you define a map axes and examine default parameters for a cylindrical, a
conic, and an azimuthal projection.

1Set up a default Mercator projection (which is cylindrical) and pass its handle to the getm function to
query projection parameters:

figure;
h=axesm('Mapprojection','mercator','Grid','on','Frame','on',... 'MlabelParallel',0,'PlabelMeridian',0,'mlabellocation',60,...
'meridianlabel','on','parallellabel','on')

The graticule and frame for the default map projection are shown below.
75 N

60 N
45 N
30 N
180

W
120

W
60

15 N
W 0 60 E 120 E 180 E
15 S
30 S
45 S

60 S
75 S

2 Query the map axes handle using getmto inspect the properties that pertain to map projection
parameters. The principal ones are aspect, origin, scalefactor, nparallels, mapparallels, falsenorthing, falseeasting,
zone, maplatlimit, maplonlimit, rlatlimit,and flonlimit:

getm(h,'aspect')
ans = normal
getm(h,'origin')
ans = 000
getm(h,'scalefactor')
ans = 1
getm(h,'nparallels')
ans = 1
getm(h,'mapparallels')
ans = 0
getm(h,'falsenorthing')
ans = 0
getm(h,'falseeasting')
ans = 0 getm(h,'zone')
ans = []
getm(h,'maplatlimit')
ans =
-86 86
getm(h,'maplonlimit')
ans =
-180 180
getm(h,'Flatlimit')
ans =
-86 86
getm(h,'Flonlimit')
ans =
-180 180
For more information on these and other map axes properties, see the reference page for axesm.

3Reset the projection type to equal-area conic ('eqaconic'). Thefigureis redrawn to reflect the change.
Determine the parameters that the toolbox changes in response:

setm(h,'Mapprojection', 'eqaconic') getm(h,'aspect')

ans = normal
getm(h,'origin') 000
getm(h,'scalefactor')
ans = 1
getm(h,'nparallels')
ans = 2
getm(h,'mapparallels')
ans =
15 75
getm(h,'falsenorthing')
ans = 0
getm(h,'falseeasting')
ans = 0
getm(h,'zone')
ans = []
getm(h,'maplatlimit')
ans =
-86 86
getm(h,'maplonlimit')
-135 135
getm(h,'Flatlimit')
ans =
-86 86
getm(h,'Flonlimit')
ans =
-135 135

The eqaconic projection has two standard parallels, at 15 and 75. It also has reduced longitude limits
(covering 270 rather than 360). The resulting eqaconic graticule is shown below.
 4 Now set the
projection type to Stereographic ('stereo')andexaminethe same properties as you did for the previous
projections:
setm(h,'Mapprojection','stereo')
setm(gca,'MLabelParallel',0,'PLabelMeridian',0)
getm(h,'aspect')

ans =
normal
getm(h,'origin') ans = 000
getm(h,'scalefactor')
ans = 1
getm(h,'nparallels')
ans = 0
getm(h,'mapparallels')
ans = []
getm(h,'falsenorthing')
ans = 0
getm(h,'falseeasting')
ans = 0
getm(h,'zone')
ans = []
getm(h,'maplatlimit')
ans =
-90 90 getm(h,'maplonlimit')
ans =
-180 180
getm(h,'Flatlimit')
ans =
-Inf 90
getm(h,'Flonlimit')
ans =
-180 180
The stereographic projection, being azimuthal, does not have standard parallels, so none are indicated.
The map limits do not change from the previous projection. The map figure is shown below.

Supported Map Projections lists and illustrates all supported Mapping Toolbox map projections,
including suggestions for parameter usage.

Visualizing and Quantifying Projection Distortions

In this section...
Displays of Spatial Error in Maps on page 8-27 Quantifying Map Distortions at Point Locations on
page 8-31

Displays of Spatial Error in Maps

Because no projection can preserve all directional and nondirectional geographic characteristics, it is
useful to be able to estimate the degree of error in direction, area, and scale for a particular projection
type and parameters used. Several Mapping Toolbox functions display projection distortions, and one
computes distortion metrics for specified locations.

A standard method of visualizing the distortions introduced by the map projection is to display small
circles at regular intervals across the globe. After projection, the small circles appear as ellipses of
various sizes, elongations, and orientations. The sizes and shapes of the ellipses reflect the projection
distortions. Conformal projections have circular ellipses, while equal-area projections have ellipses of
the same area. This method was invented by Nicolas Tissot in the 19th century, and the ellipses are
called Tissot indicatrices in his honor. The measure is a tensor function of location that varies from place
to place, and reflects the fact that, unless a map is conformal, map scale is different in every direction at
a location.
Visualizing Projection Distortions via Tissot Indicatrices
Asthefollowingexampleillustrates,youcanaddtheindicatricestoamap display with the command tissot and
remove them with clmo tissot:

1 Set up a Sinusoidal projection in a skewed aspect, plotting the graticule:

figure;
axesm sinusoid
gridm on;framem on;
setm(gca,'Origin', [20 30 45])

2 Load the coast data set and plot it as green patches:

load coast
patchm(lat,long,'g')
3 Plot the default Tissot diagram, shown below:
tissot

Notice that the circles vary considerably in shape. This indicates that the Sinusoidal projection is not
conformal. Despite the distortions, however, the circles all cover equal amounts of area on the map,
because the projection has the equal-area property.

DefaultTissotdiagrams are drawn with blue unfilled 100-point circles spaced 30 degrees apart in both
directions. The default circle radius is 1/10 of the current radius of the reference ellipsoid (by default
that radius is 1).

4Now clear the Tissot diagram, rotate the projection to a polar aspect, and plot a new Tissot diagram
using circles paced 20 degrees apart, half as big as before, drawn with 20 points, and drawn in red:

clmo tissot
setm(gca,'Origin', [90 0 45])
tissot([20 20 .05 20],'Color','r')
The result is shown below. Note that circles are drawn faster because fewer points are computed for each
one. Also note that the distortions are still smallest close to the map origin, and still greatest near the
map frame.

Try changing the map projection to a conformal one such as Mercator or Stereographic to see what
Tissot indicatrices look like on shape-preserving maps.

For further information, see the reference page for tissot.

Visualizing Projection Distortions via Isolines

Most map projection distortions are rather orderly and vary continuously, making them suitable for
display via isolines (contour lines). In addition to Tissot diagrams, the toolbox can plot isolines of
variations of several parameters associated with map projections, using mdistort.

The mdistort function can plot variations in angles, areas, maximum and minimum scale, and scale along
parallels and meridians, in units of percent deviation (except for angles, for which degrees are used).
Use this function in selecting projections and projection parameters when you are concerned about
keeping specific types of distortion within limits. Below are some examples of mdistort using the
Hammer modified azimuthal projections and the Bonne pseudoconic projection.

1 Create a Hammer projection map axes in normal aspect, and plot a graticule, frame, and coastlines on
it:
figure;
axesm('MapProjection','hammer','Grid','on','Frame','on')
2 Load the coast data set and plot it as green patches:
load coast
patchm(lat,long,'g')
3 Call mdistort to plot contours of minimum-to-maximum scale ratios:
mdistort('scaleratio')
Notice that the region of minimum distortion is centered around (0,0).
4 Repeat this diagram with a Bonne projection in a new figure window:
figure;
axesm('MapProjection','bonne','Grid','on','Frame','on') patchm(lat,long,'g')
mdistort('scaleratio')

Notice that the region of minimum distortion is centered around (30,0),

whichiswherethesinglestandardparallelis.
Hammer Bonne

Isolines of maximum/minimum scale

ratio
5 You can toggle the isolines by typing mdistort or mdistort off. Look at some other types of distortion. The
types you can request are
 area Percent departures from equal area
angles Angular distortion of right angles
scale or maxscale Percent of maximum scale
minscale Percent of minimum scale
parscale Percent of scale along the parallels
merscale Percent of scale along the meridians
scaleratio Percent of maximum-to-minimum scale ratio

For further information see the reference page for mdistort.

Quantifying Map Distortions at Point Locations

The tissot and mdistort functions described above provide synoptic visual overviews of different forms of
map projection error. Sometimes, however, you need numerical estimates of error at specific locations in
order to quantify or correct for map distortions. This is useful, for example, if you are sampling
environmental data on a uniform basis across a map, and want to know precisely how much area is
associated with each sample point, a statistic that will vary by location and be projection dependent.
Once you have this information, you can adjust environmental density and other statistics you collect for
areal variations induced by the map projection.

A Mapping Toolbox function returns location-specific map error statistics from the current projection or
an mstruct. The distortcalc function computes the same distortion statistics as mdistort does, but for
specified locations provided as arguments. You provide the latitude-longitude locations one at a time or
in vectors. The general form is

[areascale,angdef,maxscale,minscale,merscale,parscale] = ... distortcalc(mstruct,lat,long)

However, if you are evaluating the current map figure, omit the mstruct. You need not specify any return
values following the last one of interest to you.

Using distortcalc to Determine Map Projection Geometric Distortions

The following exercise uses distortcalc to compute the maximum area distortion for a map of Argentina
from the landareas data set.

1 Read the North and South America polygon:

Americas = shaperead('landareas','UseGeoCoords',true, ... 'Selector', {@(name) ...
strcmpi(name,{'north and south america'}),'Name'});

2 Set the spatial extent (map limits) to contain the southern part of South America and also include an
area closer to the South Pole:
mlatlim = [-72.0 -20.0];
mlonlim = [-75.0 -50.0];
[alat, alon] = maptriml([Americas.Lat], ...

[Americas.Lon], mlatlim, mlonlim);

3 Create a Mercator cylindrical conformal projection using these limits, specify a five-degree graticule,
and then plot the outline for reference:
figure;
axesm('MapProjection','mercator','grid','on', ... 'MapLatLimit',mlatlim,'MapLonLimit',mlonlim,...
'MLineLocation',5, 'PLineLocation',5) plotm(alat,alon,'b')

The map looks like this: 4 Sample every tenth point of the patch outline for analysis:
alats = alat(1:10:numel(alat));
alons = alon(1:10:numel(alat));
5 Compute the area distortions (the first value returned by distortcalc) at the sample points:
adistort = distortcalc(alats, alons);
6 Find the range of area distortion across Argentina (percent of a unit area on, in this case, the equator):
adistortmm = [min(adistort) max(adistort)]
adistortmm =
1.1790 2.7716
As Argentina occupies mid southern latitudes, its area on a Mercator map is overstated, and the errors
vary noticeably from north to south.
7 Remove any NaNs from the coordinate arrays and plot symbols to represent the relative distortions as
proportional circles, using scatterm:

nanIndex = isnan(adistort);
alats(nanIndex) = [];
alons(nanIndex) = [];
adistort(nanIndex) = [];
scatterm(alats,alons,20*adistort,'red','filled')
The resulting map is shown below:

8The degree of area overstatement would be considerably larger if it extended farther toward the pole.
To see how much larger, get the area distortion for 50S, 60S, and 70S:

a=distortcalc(-50,-60)
a= 2.4203
a=distortcalc(-60,-60)
a= 4
>> a=distortcalc(-70,-60)
a= 8.5485
Note You can only use distortcalc to query locations that are within the current map frame or mstruct
limits. Outside points yield NaN as a result.

9 Using this technique, you can write a simple script that lets you query a map repeatedly to determine
distortion at any desired location. You can select locations with the graphic cursor using inputm. For
example,

[plat plon] = inputm(1)

plat =
-62.225
plon =
-72.301
>> a=distortcalc(plat,plon)

a= 4.6048
Naturally the answer you get will vary depending on what point you pick. Using this technique, you can
write a simple script that lets you query a map repeatedly to determine any distortion statistic at any
desired location. Try changing the map projection or even the orientation vector to see how the choice of
projection affects map distortion. For further information, see the reference page for distortcalc.

Accessing, Computing, and Inverting Map Projection Data

In this section...
Accessing Projected Coordinate Data on page 8-37 Projecting Coordinates Without a Map Axes on
page 8-39 Inverse Map Projection on page 8-41
Coordinate Transformations on page 8-45

Accessing Projected Coordinate Data

Most of the examples in this document assume that the end product of a map projection is a graphical
representation as a map, and that the planar coordinates yielded by projection are of little interest.
However, there might be times when you need access to projected coordinate data. You might also have
projected data that you want to transform back to latitude and longitude (assuming you know its
projection parameters). The following sections describe how to retrieve projected data, project it without
displaying it, and invert projections.

A MATLAB figure generally contains coordinate data only in its axes child object and in children of
axes objects, such as line, patch, and surface objects. Seethereferencepagefor axes for an overview of this
object hierarchy. Note that a map axes can have multiple patch children objects when created with
patchesm.

You can retrieve projected data from a map axes, but you can also obtain it without having to plot the
data or even creating a map axes. The following two exercises illustrate each of these approaches.

Retrieving Projected Coordinates from a Figure

An easy way to retrieve the projected coordinates of a map occupying a figure window is with the
MATLAB get command. The projected coordinates are stored in the objects XData and YData properties.
The XData and YData can belong to a child object rather than to the axes themselves, however, as the
following exercise demonstrates.

1 Create a Mollweide projection map axes and obtain its handle:

figure;
ha = axesm('mollweid')
2 Observe that the axes has no XData, YData,or children information:
get(ha,'XData')
??? Error using ==> get
Invalid axes property: 'XData'.
get(ha,'YData')
??? Error using ==> get
Invalid axes property: 'YData'.
get(ha,'children')
ans =
Empty matrix: 0-by-1
3 Display a map frame for the Mollweide projection, obtaining its handle. Confirm that the frame is a
child of the axes:
hf = framem
hf = 105
get(ha,'children')
ans = 105
4 Use get to extract the x-y coordinates of the map frame:
xf = get(hf,'XData'); yf = get(hf,'YData');
The xf and yf coordinates are 398-by-1 column vector arrays.
5 Load the coast data set and render it with plotm, obtaining a handle:
load coast
hl = plotm(lat,long)
hl = 106
get(ha, 'children')

ans =
106
105

Note that the line data is also a child of the axes.

6 Retrieve the projected coastline coordinates using handle hl:
xline = get(hl,'XData'); yline = get(hl,'YData');
The xline and yline coordinates are 1-by-9591 row vector arrays. Inspect their contents before proceeding.

7 The units for projected coordinates are established by the spheroid object (or ellipsoid vector)
associated with the map axes. By default, this is a unit sphere, which implies that lengths are in Earth
radii, but you can change the spheroid (and length unit) at any time using setm to control the geoid
property. For example, set the units to kilometers on a spherical earth with

setm(gca,'Geoid', referenceSphere('earth','kilometers'))

Repeat step 6 above to see how this affects coordinate values. See Reference Spheroids on page 3-4
for further information on specifying coordinate units and ellipsoids.

Projecting Coordinates Without a Map Axes

You do not need to display a map object to obtain its projected coordinates. You can perform the same
projection computations that are done within Mapping Toolbox display commands by calling the defaultm
and mfwdtran functions.

UsingmfwdtranwithaMapProjectionStructure
Before projecting the data, you must define projection parameters, just as you would prepare a map axes
with axesm before displaying a map. The projection parameters are stored in a map projection structure
that is stored within a map axes object, but you can directly create and use such a structure for projection
computations without involving a map axes or a graphical display.
1 Begin by using defaultm to create an empty map projection structure for a Sinusoidal projection.
mstruct = defaultm('sinusoid'); The structure mstruct appears in the workspace. Use the property editor to
view its fields and contents.

2Set the map limits for the mstruct. You must invoke defaultm a second time to fully populate the fields
of the map projection structure and to ensure that the effects of property settings are properly
implemented.

mstruct.maplonlimit = [-150 -30];

mstruct.geoid = referenceEllipsoid('grs80','kilometers'); mstruct = defaultm(mstruct);

3 Note that the origin longitude is centered between the longitude limits.
mstruct.origin
ans =
0-90 0 4 Trim the coast to the map limits set above.
load coast
[latt,lont] = maptriml(lat,long, ...
mstruct.maplatlimit,mstruct.maplonlimit);

5Having defined the map projection parameters, project the latitude and longitude vectors into plane
coordinates with the Sinusoidal projection and display the result using nonmapping MATLAB graphic
commands.

[x,y] = mfwdtran(mstruct,latt,lont); figure

plot(x,y) axis equal

The plot shows that resulting data are projected in the specified aspect.
For additional information, see the reference pages for defaultm and mfwdtran. It is also possible to reverse
the process using minvtran,asthe next section, Inverse Map Projection on page 8-41, describes. You
may also use projfwd and projinv, which are newer Mapping Toolbox functions that use the PROJ.4 map
projection library to do forward and inverse projections, respectively. See the references pages for
projfwd and projinv for details.

Inverse Map Projection

The process of obtaining latitudes and longitudes from geodata with planar coordinatesiscalled inverse
projection. Most, but not all, map projections have inverses. Mapping Toolbox function minvtran
transforms plane coordinates into geodetic coordinates; it is a mirror image of mfwdtran,which is
described in Using mfwdtran with a Map Projection Structure on page 8-40. Like its twin, minvtran
operates on a geographic data structure that you can explicitly create. If the coordinate data originates
from an external source or vendor, you need to know its correct projection parameters in order for
inverse projection to be successful.

Recovering Geodetic Coordinates with minvtran

In the following exercise exploring the use of minvtran, you again work with the coast data set, using the
projected coordinates created in the previous exercise, Using mfwdtran with a Map Projection
Structure on page 8-40.

1 If you do not have the results of the previous exercise in the workspace, perform it now and go on to
step 2. You have the following variables:
Name Size Bytes Class

lat 9589x1 76712 double array long 9589x1 76712 double array mstruct 1x1 7360 struct array x 9599x1 76792 double array y
9599x1 76792 double array

Grand total is 38563 elements using 314368 bytes

The difference in size between lat and long and x and y are due to clipping the x-y data to the map frame
(NaNs are inserted at clip locations).
2 Transform the projected x-y data back into geographic coordinates with the inverse transformation
function:
[lat2,long2] = minvtran(mstruct,x,y);
3 In a new figure, plot the resulting latitudes and longitudes as if they were plane coordinates, and set the
frame larger than default:
figure; plot(long2,lat2); axis equal set(gca,'XLim',[-200 200],'YLim',[-100 100])

Notice the wraparound in Antarctica. This occurred because its coastline crosses the International Date
Line. In the projection transformation process, longitude data outside [-180 180] degrees is projected back
into this range because angles differing by 360 are geographically equivalent. The data from the inverse
transformation process therefore jumps from 180 to -180, as depicted by the horizontal lines in the
figure above.

Obtaining Angular Directions in a Projection Space In addition to projecting geographic positions

into Cartesian coordinates, you can project angles between the sphere and the plane. For cylindrical
projections in normal aspect, north maps to up on the y-axis, and east maps to right on the x-axis. This is
not necessarily true of other projection types. In the normal aspect of conic projections, for example,
north may skew to the left or right of vertical, depending on longitude. The vfwdtran function, which
takes latitudes, longitudes, and azimuths, computes angles that geographic vectors make on the
projection plane.

To illustrate, define vectors pointing north (0) and east (90) at three locations and use vfwdtran to
compute the angles of north and east in projected coordinates on an equidistant conic projection.
Note Geographic angles are measured clockwise from north, while projected angles are measured
counterclockwise from the x-axis.

1 Set up an equidistant conic projection for the northern hemisphere:

figure;
axesm('eqdconic','MapLatLimit',[-10 45],'MapLonLimit',[-55 55]) gridm; framem; mlabel; plabel; tightmap

2 Define three locations along the equator:

lats = [0 0 0]; lons = [-45 0 45];
3 Define north and east azimuths for each point:
northazs = [0 0 0]; eastazs = [90 90 90];
4 Compute the projected direction of north for each location:
pnorth = vfwdtran(lats,lons,northazs)
ans = 59.614 90 120.39
North varies from about 60 from the x-axis, to vertical, to 120 from the x-axis, quite symmetrically.
5 Compute projected direction of east for each location:
peast = vfwdtran(lats,lons,eastazs)
ans =
-30.385 0.0001931 30.386
pnorth - peast
ans = 90 90 90
The projected east vectors show a similar symmetry, and as expected form complementary angles to
north.
6 Use quiverm to plot the six vectors on the projection; note their plane angles:
quiverm(lats, lons, [0 0 0], [10 10 10], 0) quiverm(lats, lons, [10 10 10], [0 0 0], 0)

For more
information, see the reference pages for vfwdtran and quiverm.

Coordinate Transformations

In The Orientation Vector on page 8-10, you explored the concept of altering the aspect of a map
projection in terms of pushing the North Pole to new locations. Another way to think about this is to
redefine the coordinate system, and then to compute a normal aspect projection based on the new
system. For example, you might redefine a spherical coordinate system so that your home town occupies
the origin. If you calculated a map projection in a normal aspect with respect to this transformed
coordinate system, the resulting display would look like an oblique aspect of the true coordinate system
of latitudes and longitudes.

This transformation of coordinate systems can be useful independent of map displays. If you transform
the coordinate system so that your home town is the new North Pole, then the transformed coordinates
of all other points will provide interesting information.

Note The types of coordinate transformations described here are appropriate for the spherical case only.
Attempts to perform them on an ellipsoid will produce incorrect answers on the order of several to tens
of meters.
When you place your home town at a pole, the spherical distance of each point from your hometown
becomes 90 minus its transformed latitude (also known as a colatitude). The point antipodal to your
town would become the South Pole, at -90. Its distance from your hometown is 90-(-90), or 180, as
expected. Points 90 distant from your hometown all have a transformed latitude of 0, and thus make up
the transformed equator. Transformed longitudes correspond to their respective great circle azimuths
from your home town.

Reorienting Vector Data with rotatem

The rotatem function uses an orientation vector to transform latitudes and longitudes into a new
coordinate system. The orientation vector can be produced by the newpole or putpole functions, or can be
specified manually.

As an example of transforming a coordinate system, suppose you live in Midland, Texas, at

(32N,102W). You have a brother in Tulsa (36.2N,96W) and a sister in New Orleans (30N,90W).

1 Define the three locations:

midl_lat = 32; midl_lon = -102; tuls_lat = 36.2; tuls_lon = -96; newo_lat = 30; newo_lon = -90;

2 Use the distancefunction to determine great circle distances and azimuths of Tulsa and New Orleans
from Midland:
[dist2tuls az2tuls] = distance(midl_lat,midl_lon,... tuls_lat,tuls_lon)
dist2tuls = 6.5032
az2tuls = 48.1386
[dist2neworl az2neworl] = distance(midl_lat,midl_lon,... newo_lat,newo_lon)
dist2neworl = 10.4727
az2neworl = 97.8644
Tulsa is about 6.5 degrees distant, New Orleans about 10.5 degrees distant.
3 Compute the absolute difference in azimuth, a fact you will use later.
azdif = abs(az2tuls-az2neworl)
azdif =
49.7258

4 Today, you feel on top of the world, so make Midland, Texas, the north pole of a transformed
coordinate system. To do this, first determine the origin required to put Midland at the pole using
newpole:

origin = newpole(midl_lat,midl_lon)
origin =
58 78 0
The origin of the new coordinate system is (58N, 78E). Midland is now at a new latitude of 90.

5 Determine the transformed coordinates of Tulsa and New Orleans using the rotatem command. Because
its units default to radians, be sure to include the degrees keyword:

[tuls_lat1,tuls_lon1] = rotatem(tuls_lat,tuls_lon,... origin,'forward','degrees') tuls_lat1 =

83.4968
tuls_lon1 =
-48.1386

[newo_lat1,newo_lon1] = rotatem(newo_lat,newo_lon,... origin,'forward','degrees')

newo_lat1 = 79.5273
newo_lon1 =
-97.8644

6 Show that the new colatitudes of Tulsa and New Orleans equal their distances from Midland computed
in step 2 above:
tuls_colat1 = 90-tuls_lat1
tuls_colat1 = 6.5032
newo_colat1 = 90-newo_lat1
newo_colat1 = 10.4727

7Recall from step 4 that the absolute difference in the azimuths of the two cities from Midland was
49.7258. Verify that this equals the difference in their new longitudes:

tuls_lon1-newo_lon1
ans =
49.7258
You might note small numerical differences in the results (on the order of 10-6), due to roundoff error
and trigonometric functions.
For further information, see the reference pages for rotatem, newpole, putpole, neworig,and org2pol.

Reorienting Gridded Data with neworig

You can transform coordinate systems of data grids as well as vector data. When regular data grids are
manipulated in this manner, distance and azimuth calculations with the map variable become row and
column operations.

It is easy to transform a regular data grid to create a new one with its data rearranged to correspond to a
new coordinate system using the neworig function. To demonstrate this, do the following:

1Load the topo data set and transform it to a new coordinate system in which a point in Sri Lanka (7N,
80E) is the north pole:
figure;
load topo
origin = newpole(7,80)

origin =
83.0000 -100.0000 0
2 Reorient the data grid with neworig, using this orientation vector:
[Z,lat,lon] = neworig(topo,topolegend,origin);
Note that the result, [Z,lat,lon],isa geolocated data grid, not a regular data grid like the original topo data.
3 Display the new map:
axesm miller
latlim = [ -90 90];
lonlim = [-180 180];
gratsize = [90 180];
[lat,lon] = meshgrat(latlim,lonlim,gratsize); surfm(lat,lon,Z);
demcmap(topo)
mstruct = getm(gca);
mstruct.origin

4 This map is displayed in normal aspect, as its orientation vector shows:

mstruct = getm(gca); mstruct.origin
ans = 000

An interesting feature of this new grid is that every cell in its first row is 01 distant from the point
(7N, 80E), and every cell in its second row is 12 distant, etc. Another feature is that every cell in a
particular column has the same great circle azimuth from the new origin.

WorkingwiththeUTMSystem

In this section...
What Is the Universal Transverse Mercator System? on page 8-51 Understanding UTM Parameters
on page 8-52
Setting UTM Parameters with a GUI on page 8-54
Working in UTM Without a Map Axes on page 8-59
Mapping Across UTM Zones on page 8-60

What Is the Universal Transverse Mercator System?

So far, this chapter has described types and parameters of specific projections, treating each in isolation.
The following sections discuss how the Transverse Mercator and Polar Stereographic projections are
used to organize a worldwide coordinate grid. This system of projections is generally called Universal
Transverse Mercator (UTM). This system supports many military, scientific, and surveying applications.
The UTM system divides the world into a regular nonoverlapping grid of quadrangles, called zones,
each 8 by 6 degrees in extent. Each zone uses formulas for a transverse version of the Mercator
projection, with projection and ellipsoid parameters designed to limit distortion. The Transverse
Mercator projection is defined between 80 degrees south and 84 degrees north. Beyond these limits, the
Universal Polar Stereographic (UPS) projection applies.

The UPS has two zones only, north and south, which also have special projection and ellipsoid parameters.

In addition to the zone identifiera grid reference in the form of a number followed by a letter (e.g.,
31T)each UTM zone has a false northing and a false easting.
Theseareoffsets(inmeters)thatenableeachzonetohavepositive coordinates in both directions. For UTM,
they are constant, as follows:

False easting (for every zone): 500,000 m

False northing (all zones in the Northern Hemisphere): 0 m
False northing (all zones in the Southern Hemisphere): 1,000,000 m

ForUPS(inboththe north and south zones), the false northing and false easting are both 2,000,000.

Understanding UTM Parameters

You can create UTM maps with axesm, just like any other projection. However, unlike other projections,
the map frame is limited to an 8-by-6 degree map window (the UTM zone), as the following steps
illustrate.

1 Create a UTM map axes:

axesm utm

2Get the map axes properties and inspect them in the Command Window or with the MATLAB
Variables editor. The first few illustrate the projection defaults:

h = getm(gca)
mapprojection: 'utm'
zone: '31N'
angleunits: 'degrees'
aspect: 'normal'
falsenorthing: 0
falseeasting: 500000
fixedorient: []
geoid: [6.3782e+006 0.082483] maplatlimit: [0 8]
maplonlimit: [0 6]
mapparallels: []
nparallels: 0
origin: [0 3 0]
scalefactor: 0.9996

trimlat: [-80 84]

trimlon: [-180 180]
frame: 'off'
ffill: 100
fedgecolor: [0 0 0]
ffacecolor: 'none'
flatlimit: [0 8]
flinewidth: 2
flonlimit: [-3 3] ...

Note that the default zone is 31N.Thisisselectedbecausethemap origin defaults to [0 3 0], which is on the
equator and at a longitude of 3 E. This is the center longitude of zone 31N, which has a latitude limit of
[0 8], and a longitude limit of [0 6].

3 Move the zone one to the east, and inspect the other parameters again:
setm(gca,'zone','32n')
h = getm(gca)
mapprojection: 'utm'

zone: '32N'
angleunits: 'degrees'
aspect: 'normal'
falsenorthing: 0
falseeasting: 500000
fixedorient: []
geoid: [6.3782e+006 0.082483] maplatlimit: [0 8]
maplonlimit: [6 12]

mapparallels: []
nparallels: 0
origin: [0 9 0]
scalefactor: 0.9996
trimlat: [-80 84]
trimlon: [-180 180]

frame: 'off'
ffill: 100
fedgecolor: [0 0 0]
ffacecolor: 'none'
flatlimit: [0 8]
flinewidth: 2
flonlimit: [-3 3]
...

Note that the map origin and limits are adjusted for zone 32N.
4 Draw the map grid and label it:
setm(gca,'grid','on','meridianlabel','on','parallellabel','on')
5 Load and plot the coast data set to see a close-up of the Gulf of Guinea and Bioko Island in UTM:
load coast

plotm(lat,long)

Setting UTM Parameters with a GUI

The easiest way to use the UTM projection is through a graphical user interface. You can create or
modify a UTM area of interest with the axesmui projection control panel, and get further assistance form
the utmzoneui control panel.
1 You can Shift+click in a map axes window, or type axesmui to display the

projection control panel. Here you start from scratch:

figure;
axesm utm axesmui

The Map Projection field is set to cyln: Universal Transverse Mercator (UTM).
Note For UTM and UPS maps, the Aspect field is set to normal and cannot be changed. If you attempt to
specify transverse, an error results.

2Click the Zone button to open the utmzoneui panel. Click the map near your area of interest to pick the
zone:
Note thatwhileyoucanopenthe utmzoneui control panel from the command line, you then have to manually
update the figure with the zone name it returns with a setm command:

setm(gca,'zone',ans)
3 Click the Accept button.

The utmzoneui panel closes, and the zone field is set to the one you picked. The map limits are updated
accordingly, and the geoid parameters are automatically set to an appropriate ellipsoid definition for that
zone. You can override the default choice by selecting another ellipsoid from the list or by typing the
parameters in the Geoid field.
4 Click Apply to close the projection control panel.

The projection is then ready for projection calculations or map display commands.
5 Now view a choropleth base map from the usstatehi shapefile for the area
withinthezonethatyoujustselected:
states = shaperead('usastatehi', 'UseGeoCoords', true); framem
faceColors = makesymbolspec('Polygon',...

{'INDEX', [1 numel(states)],...
'FaceColor', polcmap(numel(states))});
geoshow(states,'DisplayType', 'polygon',...
'SymbolSpec', faceColors)

What you see depends on the zone you selected. The preceding display is for zone 18T, which contains
portions of New England and the Middle Atlantic states.

You can also calculate projected UTM grid coordinates from latitudes and longitudes:
[latlim, lonlim] = utmzone('15S')

latlim =
32 40
lonlim =
-96 -90

[x,y] = mfwdtran(latlim, lonlim)

x=
-1.5029e+006 -7.8288e+005
y=
3.7403e+006 4.5369e+006

WorkinginUTMWithoutaMapAxes

You can set up UTM to calculate coordinates without generating a map display, using the defaultm
function. The utmzone and utmgeoid functions help you select a zone and an appropriate ellipsoid. In the
following exercise, you generate UTM coordinate data for a location in New York City, using that point
to define the projection itself.

1 Define a location in New York City:

p1 = [40.7, -74.0];
2 Obtain the UTM zone for this point:
z1 = utmzone(p1)
z1 = 18T
3 Obtain the suggested ellipsoid vector and name for this zone:
[ellipsoid,estr] = utmgeoid(z1)

ellipsoid =
6.3782e+006 0.082272
estr =
clarke66

4 Set up the UTM coordinate system based on this information:

utmstruct = defaultm('utm'); utmstruct.zone = '18T';

utmstruct.geoid = ellipsoid; utmstruct = defaultm(utmstruct)

The empty latitude limits will be set properly by defaultm.

5 Now you can calculate the grid coordinates, without a map display:
[x,y] = mfwdtran(utmstruct,p1(1),p1(2))

x=
5.8448e+005
y=
4.5057e+006

More on utmzone
You can also use the utmzone function to compute the zone limits for a given zone name. For example,
using the preceding data, the latitude and longitude limits for zone 18T are

utmzone('18T')
ans =
40 48 -78 -72
Therefore, you can call utmzone recursively to obtain the limits of the UTM zone within which a point
location falls:
[zonelats zonelons] = utmzone(utmzone(40.7, -74.0))

zonelats = 40 48
zonelons =
-78 -72

For further information, see the reference pages for utmzone, utmgeoid,and defaultm.

Mapping Across UTM Zones

Because UTM is a zone-based coordinate system, it is designed to be used like a map series, selecting
from the appropriate sheet. While it is possible to extend one zones coordinates into a neighboring
zones territory, this is not normally done.

To display areas that extend across more than one UTM zone, it might be appropriate to use the
Mercator projection in a transverse aspect. Of course, you do not obtain coordinates in meters that would
match those of a UTM projection, but the results will be nearly as accurate. Here is an example of a
transverse Mercator projection appropriate to Chile. Note how the projections line of zero distortion is
aligned with the predominantly north-south axis of the country. The zero distortion line could be put
exactly on the midline of the country by a better choice of the orientation vectors central meridian and
orientation angle.

figure;
latlim = [-60 -15];centralMeridian = -70; width = 20; axesm('mercator',...

'Origin',[0 centralMeridian -90],...

'Flatlimit',[-width/2 width/2],...
'Flonlimit',sort(-latlim),...
'Aspect','transverse')

land = shaperead('landareas.shp', 'UseGeoCoords', true); geoshow([land.Lat], [land.Lon]);

framem
gridm; setm(gca,'plinefill',1000)
tightmap
mdistort scale

Note You might receive warnings about points from landareas.shp falling outside the valid projection

region. You can ignore such warnings.

Summary and Guide to Projections

The toolbox has about 60 different built-in map projections. To list them all, type maps. The following
table also summarizes them and identifies their properties. Notes for Special Features are located at the
end of the table. Information on Mapping Toolbox map projections can be found in Projections and
Parameters.

Projection
Balthasart
Behrmann
Bolshoi Sovietskii Atlas Mira

Braun Perspective Cassini

Central

Cartographers often choose map projections by determining the types of distortion they want to
minimize or eliminate. They can also determine which of the three projection types (cylindrical, conic,
or azimuthal) best suits their purpose and region of interest. They can attach special importance to
certain projection properties such as equal areas, straight rhumb lines or great circles, true direction,
conformality, etc., further constricting the choice of a projection.

Equal-Area Cylindrical Equidistant

Cylindrical

Gall Isographic
Gall Orthographic
Gall Stereographic

Lambert Equal-Area Cylindrical

Syntax balthsrt behrmann bsam

Type
Cylindrical Cylindrical Cylindrical

Equal-ConEquiSpecial Area formal distant Features

braun
cassini ccylin
eqacylin eqdcylin

Cylindrical Cylindrical Cylindrical Cylindrical Cylindrical

giso
gortho
gstereo lambcyln

Cylindrical Cylindrical Cylindrical Cylindrical

 Mercator
Miller

Plate Carre
Trystan Edwards

Universal Transverse Mercator (UTM)

Wetch
Apianus II

mercator miller pcarree trystan utm

Cylindrical1 Cylindrical
Cylindrical
Cylindrical
Cylindrical

wetch apianus
Collignon collig
Craster Parabolic craster
Eckert I eckert1
Eckert II eckert2
Eckert III eckert3
Eckert IV eckert4
Eckert V eckert5
Eckert VI eckert6
Fournier fournier
Goode Homolosine goode Cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo cylindrical

Pseudo Hatano Asymmetrical Equal-Area

Kavraisky V
hatano
kavrsky5
Kavraisky VI kavrsky6
Loximuthal loximuth
McBryde-Thomas Flat-Polar Parabolic McBryde-Thomas Flat-Polar Quartic McBryde-Thomas Flat-
Polar Sinusoidal Mollweide
flatplrp
flatplrq
flatplrs
mollweid
Putnins P5 putnins5
Quartic Authalic quartic
Robinson robinson
Sinusoidal sinusoid
Tissot Modified Sinusoidal
Wagner IV
modsine
wagner4
Winkel I winkel
Pseudo cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo
cylindrical
Pseudo cylindrical
Pseudo cylindrical
Pseudo cylindrical

Pseudo
Albers Equal-Area Conic

Equidistant Conic
Lambert Conformal Conic
Murdoch I Conic
Murdoch III Minimum Error Conic

Bonne
Werner
Polyconic
VanDerGrintenI

Breusing Harmonic Mean

Equidistant Azimuthal Gnomonic

Lambert Azimuthal Equal-Area

Orthographic
Stereographic

Universal Polar
Stereographic (UPS) Vertical Perspective Azimuthal
Wiechel
eqaconic Conic
eqdconic lambert
Conic Conic
murdoch1 murdoch3
Conic 3 Conic 3

bonne
werner
polycon vgrint1 breusing

Pseudoconic Pseudoconic Polyconic

Polyconic
Azimuthal

eqdazim gnomonic eqaazim

Azimuthal
Azimuthal 4 Azimuthal

ortho stereo ups

Azimuthal
Azimuthal 5
Azimuthal 5

vperspec Azimuthal
wiechel
Aitoff aitoff
Pseudo azimuthal
Modified
Azimuthal
Briesemeister bries Modified
Azimuthal
Hammer hammer Modified
Azimuthal
Globe globe Spherical 6
1 Straight rhumb lines.
2 Rhumb lines from central point are straight, true to scale, and correct in azimuth.
3 Correct total area.
4 Straight line great circles.
5 Great and small circles appear as circles or lines. 6 Three-dimensional display (not a map projection).

Creating Web Map Service Maps

Introduction to Web Map Service on page 9-2
Basic Workflow for Creating WMS Maps on page 9-6
Searching the WMS Database on page 9-9
Refining Your Search on page 9-12
Updating Your Layer on page 9-14
Retrieving Your Map on page 9-16
Modifying Your Request on page 9-36
Overlaying Multiple Layers on page 9-41
Animating Data Layers on page 9-51
Retrieving Elevation Data on page 9-62
Saving Favorite Servers on page 9-73
Exploring Other Layers from a Server on page 9-74
Writing a KML File on page 9-77
Searching for Layers Outside the Database on page 9-79
Hosting Your Own WMS Server on page 9-80
Common Problems with WMS Servers on page 9-81

Introduction to Web Map Service

In this section...
What Web Map Service Servers Provide on page 9-2 Basic WMS Terminology on page 9-5

What Web Map Service Servers Provide

Web Map Service (WMS) servers follow a standard developed by the Open Geospatial Consortium,
Inc. (OGC) and provide access to a wealth of geospatial information. With maps from WMS servers,
you can:

Use any publicly available WMS data

Easily adjust colors and styles to more clearly display information
Update your map to reflect the most recent data
Share your map with others
Mapping Toolbox software simplifies the process of WMS map creation by using a stored database of
WMS servers. You can search the database for layers and servers that are of interest to you.
As an example, the WMS Global Mosaic map displays data from Landsat7 satellite scenes.

Courtesy NASA/JPL-
Caltech
The Ozone Effect on Global Warming map displays data from the NASA Goddard Institute for Space
Studies (GISS) computer model study.

Courtesy NASA/Goddard
Space Flight Center Scientific Visualization Studio

Limitations of WMS Servers

A WMS server typically renders a layer as an RGB image. In some rare cases, you can request the actual
data, rather than a pictorial representation, from a WMS server. Most often, you need to create either a
Web Coverage Service (WCS) request, for raster data, or a Web Feature Service (WFS) request, for
vector data. The Mapping Toolbox does not support WCS and WFS requests.

Basic WMS Terminology

Open Geospatial Consortium, Inc. (OGC) An organization comprising companies, government

agencies, and universities that defines specifications for providers of geospatial data and developers of
software designed to access that data. The specifications ensure that providers and clients can talk to
each other and thus promote the sharing of geospatial data worldwide. You can access the Web Map
Server Implementation Specification at the OGC Web site.

Web Map ServiceTheOGC defines a Web Map Service (WMS) as an entity that produces maps
of spatially referenced data dynamically from geographic information.

WMS server A server that follows the guidelines of the OGC to render maps and return them to
clients.
georeferenced Tied to a specific location on the Earth.
raster data Data represented as a matrix in which each element corresponds to a specific
rectangular or quadrangular geographic area.
mapTheOGC defines a map as a portrayal of geographic information as a digital image file
suitable for display on a computer screen.
raster map Geographically referenced information stored as a regular array of cells.

layer A data set containing a specific type of geographic information. Information can include
temperature, elevation, weather, orthoimagery, boundaries, demographics, topography, transportation,
environmental measurements, or various data from satellites.

capabilities document An XML document containing metadata describing the geographic content
offered by a server.

Basic Workflow for Creating WMS Maps

Workflow Summary

1 Search WMS Database.

2 Refine search.
3 Update layer.
4 Modify request.
5 Retrieve map. 6 Display map.

Creating a Map of Elevation in Europe

Follow the example to learn the basic steps in creating a WMS map.
1 Search the local WMS Database for a layer. WMS servers store map data in units called layers. Search
for elevation layers.
elevation = wmsfind('elevation');
wmsfind returns an array of hundreds of WMSLayer objects.

2 Refine your search. GTOPO30 is a digital elevation model developed by the United States Geological
Survey (USGS). Refine your search to include only the layer with the exact name, `Foundation.GTOPO30'
in the LayerName field.

gtopolayer = refine(elevation, 'Foundation.GTOPO30', ...

'SearchField', 'layername', 'Match', 'exact');
gtopolayer = refine(gtopolayer, 'nfis.org', 'SearchField', 'serverurl');
3 Update your layer. You can skip this optional step for this example. The wmsupdate function
accomplishes two tasks:
Updates your WMSLayer object to include the most recent data
Fills in its Details, CoordRefSysCodes,and Abstract fields

4 Modify your request. Specify geographic limits, image dimensions, background color, and other
properties of the map. In this simple example, modify only the background color. Choose red, green, and
blue levels to define an ocean color.

oceanColor = [0 170 255];

5 Retrieve your map.
First, set up a map axes with projection and geographic limits appropriate for Europe.
figure
worldmap europe;
Then, return the map axes map structure, which contains the settings for all the current map axes
properties.
mstruct = gcm;

Use the WMSLayer object gtopolayer as input for wmsread.Setthe wmsread longitude and latitude limit
parameters to the current map axes limits. Set the BackgroundColor parameter to oceanColor.

[elevationImage, R] = wmsread(gtopolayer, 'Latlim', ... mstruct.maplatlimit, 'Lonlim', mstruct.maplonlimit, ...

'BackgroundColor', oceanColor);

The wmsread function returns a map called elevationImage and a referencing matrix R, which ties the map to
a specific location on Earth.
6 Display your map.
geoshow(elevationImage, R);
title({'Europe','Elevation'}, 'FontWeight', 'bold')

Searching the WMS Database

In this section...
Introduction to the WMS Database on page 9-9 Finding Temperature Data on page 9-10

Introduction to the WMS Database

The Mapping Toolbox contains a database of over 1,000 stored WMS servers and over 100,000 layers.
This database, called the WMS Database,updates at the time of the software release and includes a
subset of available WMS servers. MathWorks created the database by conducting a series of Internet
searches and qualifying the search results.

Note MathWorks cannot guarantee the stability and accuracy of WMS data, as the servers listed in the
WMS Database are located on the Internet and are independent from MathWorks. Occasionally, you
may receive error messages from servers experiencing difficulties. The WMS Database changes at the
beginning of each new software release. Servers can go down or become unavailable.
The WMS Database contains the following fields.
Field Name Data Type ServerTitle String
ServerURL String LayerTitle String
LayerName String
Field Content
Title of the WMS server, descriptive information about the server
URL of the WMS server
Title of the layer, descriptive information about the layer
Name of the layer, keyword the server uses to retrieve the layer
Field Name Data Type Latlim Two-element vector
Lonlim Two-element vector
Field Content
Southern and northern latitude limits of the layer
Western and eastern longitude limits of the layer

The LayerTitle and LayerName fields sometimes have the same values. The LayerName indicates a code used
by the servers, such as '29:2',whilethe LayerTitle provides more descriptive information. For instance,
'Elevation and Rivers with Backdrop' is a LayerTitle.

wmsfind is the only WMS function that accesses the stored WMS Database. The following example
illustrates how to use wmsfind to find a layer.

Finding Temperature Data

For this example, assume that you work as a research scientist and study the relationship between global
warming and plankton growth. Increased plankton growth leads to increased carbon dioxide absorption
and reduced global warming. The sea surface temperature is already rising, however, which may reduce
plankton growth in some areas. You begin investigating this complex relationship by mapping sea
surface temperature.

1 Search the WMS Database for temperature data.

layers = wmsfind('temperature');

By default, wmsfind searches both the LayerName and LayerTitle fields of the WMS Database for partial
matches. The function returns a WMSLayer array, which contains one WMSLayer object for each layer
whose name or title partially matches 'temperature'.

2Click layers in the Workspace browser and then click one of the objects labeled <1x1 WMSLayer>.
Sample Output:
ServerTitle: 'NASA SVS Image Server'
ServerURL: 'http://svs.gsfc.nasa.gov/cgi-bin/wms?'

LayerTitle: 'Background Image for Global Sea Surface ... Temperature from June, 2002 to September, 2003 (WMS)'

LayerName: '2905_17492_bg'
Latlim: [-90.0000 90.0000]
Lonlim: [-180.0000 180.0000]
Abstract: '<Update using WMSUPDATE>'
CoordRefSysCodes: '<Update using WMSUPDATE>'
Details: '<Update using WMSUPDATE>'

A WMSLayer object contains three fields that do not appear in the WMS DatabaseAbstract,
CoordRefSysCodes,and Details. (By default, these fields do not display in the command window if they are
not populated with wmsupdate. For more information, see Updating Your Layer on page 9-14 in the
Mapping Toolbox Users Guide.)

Note WMSLayer is one of several classes related to WMS. If you are new to object-oriented
programming, you can learn more about classes, methods, and properties in the Object-Oriented
Programming section of the MATLAB documentation.

Refining Your Search

In this section...
Refining by Text String on page 9-12 Refining by Geographic Limits on page 9-13

Refining by Text String

Your initial search may return hundreds or even thousands of layers. Scanning all these layers to find the
most relevant one could take a long time. You need to refine your search.

1 Refine your search to receive only layers that include sea surface temperature.
layers = wmsfind('temperature'); sst = layers.refine('sea surface');
2 Refine the search again to include only layers that contain the term global.
global_sst = sst.refine('global');
3 Display one of the layers.
global_sst(4).disp
Sample Output:
Index: 4
ServerTitle: 'NASA SVS Image Server'

ServerURL: 'http://svs.gsfc.nasa.gov/cgi-bin/wms?' LayerTitle: 'Background Image for Global Sea Surface ... Temperature
from June, 2002 to September, ... 2003 (WMS)'

LayerName: '2905_17492_bg'
Latlim: [-90.0000 90.0000]
Lonlim: [-180.0000 180.0000]

Refining by Geographic Limits

You can search for layers in a specific geographic area.

1 First, find hurricane layers.
layers = wmsfind('hurricane');
2 Refine your search by selecting layers that are in the western hemisphere.
western_hemisphere = layers.refineLimits ... ('Latlim',[-90 90], 'Lonlim', [-180 0]);
3 Refine again to include only layers in the western hemisphere that include temperature data.
temp_and_west = western_hemisphere.refine('temperature');
Updating Your Layer

After you find your specific layer of interest, you can leave the local WMS Database and work with a
WMS server. In this section, you learn how to synchronize your layer with the WMS source server.

Note When working with the Internet, you may have to wait several minutes for information to
download, or servers can become unavailable. If you encounter problems, refer to Common Problems
with WMS Servers on page 9-81 for tips.

Use the wmsupdate function to synchronize a WMSLayer object with the corresponding WMS server. This
synchronization populates the Abstract, CoordRefSysCodes,and Details fields.

1 Find all layers in the WMS Database with the title Global Sea Surface Temperature.
global_sst = wmsfind ('Global Sea Surface Temperature', ... 'SearchField', 'LayerTitle');
2 Use the WMSLayer.servers method to determine the number of unique servers.
global_sst.servers

3 If your search returns more than one server, consider setting the wmsupdate 'AllowMultipleServers' property
to true. (However, be aware that if you have many servers, updating them could take a long time.)

global_sst = wmsupdate(global_sst, 'AllowMultipleServers', true);

4 Now that you have updated all the fields in your WMSLayer objects, you can search by the Abstract field.
el_nino = global_sst.refine ('El Nino', 'SearchField', ... 'abstract');
Type el_nino(1).Abstract at the command line to view the abstract of the first layer.
Sample Output:

The temperature of the surface of the world's oceans provides a clear indication of the state of the Earth's climate and
weather....In this visualization of the anomaly covering the period from June, 2002, to September, 2003, the most obvious
effects are a successive warming and cooling along the equator to the west of Peru, the signature of an El Nino/La Nina
cycle....

5 Type el_nino(1).CoordRefSysCodes at the command line to view the coordinate reference system codes
associated with this layer. In this example, 'EPSG:4326' is given as the coordinate reference system code.
For more information, see Understanding Coordinate Reference System Codes on page 9-17 in the
Mapping Toolbox Users Guide.

6To view the contents of the Details field, type el_nino(1).Details at the command line.
Sample Output:
ans =
MetadataURL: 'http://svs.gsfc.nasa.gov/vis/a000000/a002900... /a002906/a002906.fgdc'

Attributes: [1x1 struct]

BoundingBox: [1x1 struct]
Dimension: [1x1 struct]
ImageFormats: {'image/png'}
ScaleLimits: [1x1 struct]
Style: [1x2 struct]
Version: '1.1.1'
The Style field covers a wide range of information, such as the line styles used to render vector data, the
background color, the numeric format of data, the month of data collection, or the dimensional units.

Retrieving Your Map

In this section...
WaystoRetrieveYourMaponpage9-16
Understanding Coordinate Reference System Codes on page 9-17 Retrieving Your Map with
wmsread on page 9-17 Setting Optional Parameters on page 9-18
Adding a Legend to Your Map on page 9-20
Retrieving Your Map with WebMapServer.getMap on page 9-29

Ways to Retrieve Your Map

ToretrieveamapfromaWMSserver,usethefunction wmsread or, in a few specific situations, the

WebMapServer.getMap method. Use the getMap method when:

Working with non-EPSG:4326 reference systems

Creating an animation of a specific geographic area over time
Retrieving multiple layers from a WMS server

In most cases, use wmsread to retrieve your map. To use wmsread,specify either a WMSLayer object or a
map request URL. Obtain a WMSLayer object by using wmsfind to search the WMS Database. Obtain a
map request URL from:

The output of wmsread

The RequestURL property of a WMSMapRequest object
An Internet search

The map request URL string is composed of a WMS server URL with additional WMS parameters. The
map request URL can be inserted into a browser to make a request to a server, which then returns a
raster map.

Understanding Coordinate Reference System Codes

When using wmsread, request a map that uses the EPSG:4326 coordinate reference system. EPSG stands
for European Petroleum Survey Group. This group, an organization of specialists working in the field of
oil exploration, developed a database of coordinate reference systems. Coordinate reference systems
identify position unambiguously. Coordinate reference system codes are numbers that stand for specific
coordinate reference systems.

EPSG:4326 is based on the 1984 World Geodetic System (WGS84) datum and the latitude and longitude
coordinate system, with angles in degrees and Greenwich as the central meridian. All servers in the
WMS Database, and presumably all WMS servers in general, use the EPSG:4326 reference system. This
system is a requirement of the OGC WMS specification. If a layer does not use EPSG:4326, Mapping
Toolbox software uses the next available coordinate reference system code. The Mapping Toolbox does
not support automatic coordinate reference systems (systems in which the user chooses the center of
projection). For more information about coordinate reference system codes, please see the Spatial
Reference Web site.

Retrieving Your Map with wmsread

NASAs Blue Marble Next Generation layer shows the Earths surface for each month of 2004 at high
resolution (500 meters/pixel). Read and display the Blue Marble Next Generation layer.

1 Search the WMS Database for all layers with 'nasa' in the ServerURL field.
nasa = wmsfind('nasa', 'SearchField', 'serverurl');

2 Use the WMSLayer.refine method to refine your search to include only those layers with the phrase
'bluemarbleng' in the LayerName field. This syntax creates an exact search.

layer = nasa.refine('bluemarbleng', 'SearchField', 'layername', ... 'MatchType', 'exact');

3 Use the wmsread function to retrieve the Blue Marble Next Generation layer.
[A, R] = wmsread(layer);

The wmsread function returns A, a geographically referenced raster map, and R, a referencing matrix that
ties A to the EPSG:4326 geographic coordinate system. The geographic limits of A span the full latitude
and longitude extent of layer.

4 Open a figure window, set up your map axes, and display your map.

figure
axesm globe
axis off
geoshow(A, R)
title('Blue Marble: Next Generation')
 Courtesy NASA/
JPL-Caltech

Setting Optional Parameters

The wmsread function allows you to set many optional parameters, such as image height and width and
background color. This example demonstrates how to view an elevation map in 0.5-degree resolution by
changing the cell size,andhowtodisplaytheoceaninlightbluebysettingthebackground color. For a complete
list of parameters, see the wmsread reference page. 1 The MicroImages, Inc. TNTserver, like NASA,
hosts a wide variety

of layers. Search the WMS Database for layers that contain the string 'microimages' in the ServerURL field.
microLayers = wmsfind('microimages', 'SearchField', 'serverurl');

2 GTOPO30, a digital elevation model developed by the United States Geological Survey (USGS), has a
horizontal grid spacing of 30 arc seconds. Refine your search to include only layers that contain the
string 'gtopo30' in the LayerName and LayerTitle fields.

gtopo30Layer = microLayers.refine('gtopo30');
The refined search returns one layer.
3 Choose red, green, and blue levels to define a background color.
oceanColor = [0 170 255];
4 Use the BackgroundColor and CellSize parameters of the wmsread function to determine the background
color and cell size, as you retrieve your map.
cellSize = 0.5;
[A,R] = wmsread(gtopo30Layer, 'BackgroundColor', oceanColor, ... 'CellSize', cellSize);
5 Openafigurewindowandsetupaworldmapaxes. Displayyourmapwitha title.

figure
worldmap world
geoshow(A, R)
title('GTOPO30 Elevation Model')

Courtesy MicroImages, Inc.

AddingaLegendtoYourMap

A WMS server renders a layer as an image. Without a corresponding legend, interpreting the pixel
colors can be difficult. Some WMS servers provide access to a legend image for a particular layer via a
URL that appears in the layers Details.Style.LegendURL field. (See the WMSLayer.Details reference page for
more information.)

Although a legend provides valuable information to help interpret image pixel colors, only about 45% of
the servers in the WMS database contain at least one layer with an available legend. Less than 10% of
the layers in the WMS database contain a legend, but nearly 80% of the layers in the database are on the
columbo.nrlssci.navy.mil server. This server always has empty LegendURL fields. You cannot use wmsfind to
search only for layers with legends because the database does not store this level of detail. You must
update a layer from the server before you can access the LegendURL field.

This example demonstrates how to create a map of surface temperature, and then obtain and display the
associated legend image:

1 Search for layers from the NASA Goddard Space Flight SVS Image Server. This server contains layers
that have legend images. You can tell that legend images are available because the layers have content in
the LegendURL field.

layers = wmsfind('svs.gsfc.nasa.gov', 'SearchField', 'serverurl'); serverURL = layers(1).ServerURL; gsfc =

wmsinfo(serverURL);

2 Find the layer containing urban temperature signatures and display the abstract:
urban_temperature = gsfc.Layer.refine('urban*temperature'); disp(urban_temperature.Abstract)

Big cities influence the environment around them. For example, urban areas are typically warmer than their surroundings.
Cities are strikingly visible in computer models that simulate the Earth's land surface. This visualization shows average
surface temperature predicted by the Land Information System (LIS) for a day in June 2001. Only part of the global
computation is shown, focusing on the highly urbanized northeast corridor in the United States, including the cities of Boston,
New York, Philadelphia, Baltimore, and Washington.

Additional Credit:
NASA GSFC Land Information System (http://lis.gsfc.nasa.gov/)
3 Read and display the layer. The map appears with different colors in different regions, but without a
legend it is not clear what these colors represent.
[A,R] = wmsread(urban_temperature); figure
usamap(A,R)
geoshow(A,R)
title('Urban Temperature Signatures') axis off

Courtesy NASA Goddard Space Flight Center

4 Investigate the Details field of the urban_temperature layer. This layer has only one structure in the Style
field. The Style field determines how the server renders the layer.

urban_temperature.Details
ans =

MetadataURL: [1x65 char] Attributes: [1x1 struct]

BoundingBox: [1x1 struct] Dimension: [1x1 struct]
ImageFormats: {'image/png'} ScaleLimits: [1x1 struct] Style: [1x1 struct] Version: '1.1.1'

Display the Style field in the Command Window:

urban_temperature.Details.Style
ans =

Title: 'Opaque' Name: 'opaque' Abstract: [1x319 char]

LegendURL: [1x1 struct]

Each Style element has only one LegendURL. Investigate the LegendURL:
urban_temperature.Details.Style.LegendURL
ans =

OnlineResource: [1x65 char] Format: 'image/png' Height: 90

Width: 320
5 Download the legend URL and save it:
url = urban_temperature.Details.Style.LegendURL.OnlineResource urlwrite(url, 'temp_bar.png');
The URL appears in the command window:
url =
http://svs.gsfc.nasa.gov/vis/a000000/a003100/a003152/temp_bar.png
6 Display the legend image using the image command and set properties, such that the image displays
with one-to-one, screen-to-pixel resolution.
legend = imread('temp_bar.png');
figure('Color','white')
axis off image
set(gca,'units','pixels','position',...

[0 0 size(legend,2) size(legend,1)]); pos = get(gcf,'position');

set(gcf,'position',...

[pos(1) pos(2) size(legend,2) size(legend,1)]); image(legend)

Courtesy NASA Goddard Space Flight Center

Now the map makes more sense. The regions toward the red end of the spectrum are warmer.
Steps 710 demonstrate how to capture the output from a map frame and append the legend.
7 By appending the legend in this fashion, you avoid warping text in the legend image. (Legend text
warps if you display the image with geoshow.)
First set your latitude and longitude limits to match the limits of your map and read in a shapefile with
world city data:
[latlim,lonlim] = limitm(A,R);
S = shaperead('worldcities', 'UseGeoCoords',true,... 'BoundingBox',[lonlim(1) latlim(1);lonlim(2) latlim(2)]);

8Determine the position of the current figure window. Vary the pos(1) and pos(2) 'Position' parameters as
necessary based on the resolution of your screen.

colValue = [1 1 1];
dimension = size(A,1)/2;
set(gcf,'Color',[1,1,1])
pos = get(gcf, 'Position');
set(gcf, 'Position', [pos(1) pos(2) dimension dimension])

9Display the map and add city markers, state boundaries, meridian and parallel labels, a title, and a
North arrow:
usamap(A,R)
geoshow(A,R)
geoshow(S, 'MarkerEdgeColor', colValue, 'Color', colValue)

geoshow('usastatehi.shp', 'FaceColor', 'none',... 'EdgeColor','black')

mlabel('FontWeight','bold')
plabel('FontWeight','bold')
axis off
title('Urban Temperature Signatures', 'FontWeight', 'bold')

for k=1:numel(S)
textm(S(k).Lat, S(k).Lon, S(k).Name, 'Color', colValue,... 'FontWeight','bold')
end
lat = 36.249;
lon = -71.173;
northarrow('Facecolor', colValue, 'EdgeColor', colValue,...
'Latitude', lat, 'Longitude', lon);

Courtesy NASA Goddard Space Flight Center

10 Display the map and legend as a single, combined image:
f = getframe(gcf);
legendImg = uint8(255*ones(size(legend,1), size(f.cdata,2), 3)); offset = dimension/2;
halfSize = size(legend, 2)/2;
legendImg(:,offset-halfSize:offset+halfSize-1,:) = legend; combined = [f.cdata; legendImg];
pos = get(gcf,'position');
set(gcf,'position',[10 100 size(combined,2) size(combined,1)]) set(gca,'units','normalized','position', ...

[0 0 1 1]);
image(combined)
axis off image
 Courtesy NASA Goddard Space Flight Center

11 Another way to display the map and legend together is to burn the legend into the map at a specified
location. To view the image, use the image command, setting the position parameters such that there is a
one-to-one pixel-to-screen resolution. (Legend text warps if the image is displayed with geoshow.)

A_legend = A;

A_legend(end-size(legend,1):end-1,...
end-size(legend,2):end-1,:) = legend;
figure
image(A_legend)
axis off image
set(gca,'Units','normalized','position',...
[0 0 1 1]);
set(gcf,'Position',[10 100 size(A_legend,2) size(A_legend,1)]);
title('Urban Temperature Signatures', 'FontWeight', 'bold')

12 Combine the map and legend in one file, and then publish it to the Web. First write the images to a
file:
mkdir('html')
imwrite(A_legend, 'html/wms_legend.png') imwrite(combined, 'html/combined.png')

Open the MATLAB Editor, and paste in this code:

%%
% <<wms_legend.png>>
%%
% <<combined.png>>

Add any other text you want to include in your published document. Then select one of the cells and
choose File > Save File and Publish from the menu.

Retrieving Your Map with WebMapServer.getMap

The WebMapServer.getMap method allows you to retrieve maps in any properly defined EPSG coordinate
reference system. If you want to retrieve a map in the EPSG:4326 reference system, you can use
wmsread. If you want to retrieve a layer whose coordinates are not in the EPSG:4326 reference system,
however, you must use the WMSMapRequest class to construct the request URL and the
WebMapServer.getMap method to retrieve the map. This example demonstrates how to create maps in
"Web Mercator" coordinates using the WMSMapRequest and WebMapServer classes. The Web Mercator
coordinate system is commonly used by web applications.

The USGS National Map provides ortho-imagery and topography maps from various regions of the
United States. The server provides the data in both EPSG:4326 and in Web Mercator coordinates, as
defined by EPSG codes EPSG:102113, EPSG:3857. For more information about these codes, see the
Spatial Reference Web site.

1 Obtain geographic coordinates that are coincidental with the image in the file boston.tif.

filename = 'boston.tif';
proj = geotiffinfo(filename);
cornerLat = [proj.CornerCoords.Lat]; cornerLon = [proj.CornerCoords.Lon]; latlim = [min(cornerLat) max(cornerLat)];
lonlim = [min(cornerLon) max(cornerLon)];

2 Convert the geographic limits to Web Mercator. The EPSG:102113 coordinate system, is commonly
known as "Web Mercator", or "Spherical Mercator projection coordinate system". This system uses the
WGS84 semimajor axis length (in meters) but sets the semiminor axis length to 0. To obtain the imagery
in this coordinate reference system, you need to use WMSMapRequest and WebMapServer since wmsread
only requests data in the EPSG:4326 system.

mstruct = defaultm('mercator');
mstruct.origin = [0 0 0];
mstruct.maplatlimit = latlim;
mstruct.maplonlimit = lonlim;
wgs84 = wgs84Ellipsoid;
mstruct.geoid = [wgs84.SemimajorAxis 0 ]; mstruct = defaultm(mstruct);

[x,y] = mfwdtran(mstruct, latlim, lonlim); xlimits = [min(x) max(x)];

ylimits = [min(y) max(y)];
3 Calculate image height and width values for a sample size of 5 meters.
metersPerSample = 5;
imageHeight = round(diff(ylimits)/metersPerSample); imageWidth = round(diff(xlimits)/metersPerSample);

4 Re-compute the new limits.

yLim = [ylimits(1), ylimits(1) + imageHeight*metersPerSample]; xLim = [xlimits(1), xlimits(1) +
imageWidth*metersPerSample];
5 FindtheUSGSNationalMapfromtheWMSdatabaseandselecttheDigital Ortho-Quadrangle layer.
nmap = wmsfind('nationalmap', 'SearchField', 'serverurl'); doqLayer = refine(nmap, 'NAIP*ImageServer', 'SearchField',
'serverurl'); doqLayer = doqLayer(1);

6 Create WebMapServer and WMSMapRequest objects.

server = WebMapServer(doqLayer.ServerURL); numberOfAttempts = 50;
attempt = 0;
request = [];
while(isempty(request))

try
request = WMSMapRequest(doqLayer, server);
catch e
attempt = attempt + 1;
fprintf('%d\n', attempt)
if attempt > numberOfAttempts
throw(e)
end
end
end

7 Use WMSMapRequest properties to modify different aspects of your map % request, such as map
limits, image size, and coordinate reference system % code. Set the map limits to cover the same region
as found in the % boston.tif file.

request.CoordRefSysCode = 'EPSG:102113'; request.ImageHeight = imageHeight; request.ImageWidth = imageWidth;

request.XLim = xLim;
request.YLim = yLim;

8 Request a map of the ortho-imagery in Web Mercator coordinates.

A_PCS = getMap(server, request.RequestURL); R_PCS = request.RasterRef;
9 Obtain a map for the same region, but in EPSG:4326 coordinates.

request.CoordRefSysCode = 'EPSG:4326'; request.Latlim = latlim;

request.Lonlim = lonlim;
A_Geo = getMap(server, request.RequestURL); R_Geo = request.RasterRef;

1010. Read in Boston place names from a shapefile and overlay them on top of the maps. Convert the
coordinates of the features to Web Mercator and geographic coordinates. The point coordinates in the
shapefile are in meters and Massachusetts State Plane coordinates, but the GeoTIFF projection is
defined in survey feet.
S = shaperead('boston_placenames'); x = [S.X]*unitsratio('sf','meter'); y = [S.Y]*unitsratio('sf','meter'); names = {S.NAME};
[lat, lon] = projinv(proj, x, y);
[xPCS, yPCS] = mfwdtran(mstruct, lat, lon);

11 Project and display the ortho-imagery obtained in EPSG:4326 coordinates using geoshow.
mstruct.geoid = wgs84;
mstruct = defaultm(mstruct);

figure('Renderer','zbuffer')
axesm(mstruct)
geoshow(A_Geo,R_Geo)
textm(lat, lon, names, 'Color',[0 0 0], ... 'BackgroundColor',[0.9 0.9 0],'FontSize',6);

axis tight
title({'USGS Digital Ortho-Quadrangle - Boston', ... 'Geographic Layer'})

12 Display the
ortho-imagery obtained in Web Mercator coordinates..
figure
mapshow(A_PCS, R_PCS);
text(xPCS, yPCS, names, 'Color',[0 0 0], ...

'BackgroundColor',[0.9 0.9 0],'FontSize',6,'Clipping','on'); axis tight

title({'USGS Digital Ortho-Quadrangle - Boston', 'Web Mercator Layer'})
 13 Display the
image from boston.tif for comparison.
figure
mapshow(filename)
text(x, y, names, 'Color',[0 0 0], ...

'BackgroundColor',[0.9 0.9 0],'FontSize',6,'Clipping','on'); axis tight

title({filename, proj.PCS})
Modifying Your Request

In this section...
Setting the Geographic Limits and Time on page 9-36 Manually Editing a URL on page 9-38

Setting the Geographic Limits and Time

A WMSMapRequest object contains properties to modify the geographic extent and time of the requested
map. This example demonstrates how to modify your map request to map sea surface temperature for
the ocean surrounding the southern tip of Africa. See the WMSMapRequest reference page for a complete
list of properties.

1 Search the WMS Database for all layers on NASAs Earth Observations (NEO) WMS server.
neowms = wmsfind('neowms', 'SearchField', 'serverurl');
2 Refine your search to include only layers with 'sea surface temperature' in the layer title or layer name
fields of the WMS database.
sst = neowms.refine('sea surface temperature');
3 Refine your search to include only layers with monthly values from the MODIS sensor on the Aqua
satellite.
sst = sst.refine('month*modis');
4 Construct a WebMapServer object from the server URL stored in the ServerURL property of the WMSLayer
object sst.
server = WebMapServer(sst(1).ServerURL);
5 Construct a WebMapRequestobject from a WMSLayerarray and a WebMapServer object.
mapRequest = WMSMapRequest(sst, server);
6 Use the Latlim and Lonlim properties of WMSMapRequest to set the latitude and longitude limits.
mapRequest.Latlim = [-45 -25]; mapRequest.Lonlim = [15 35];
7 Set the time request to March 1, 2009.
mapRequest.Time = '2009-03-01';
8 Send your request to the server with the WebMapServer.getMap method. Pass in a
WMSMapRequest.RequestURL.
sstImage = server.getMap(mapRequest.RequestURL);
9 Set up empty map axes with the specified geographic limits.

figure
worldmap(mapRequest.Latlim, mapRequest.Lonlim); setm(gca, 'mlabelparallel', -45)

10Project and display an image georeferenced to latitude and longitude. Use the referencing matrix
provided by the RasterRef property of the WMSMapRequest object.

geoshow(sstImage, mapRequest.RasterRef); title({'South Africa', sst.LayerTitle}, ... 'FontWeight', 'bold', 'Interpreter', 'none')

Courtesy NASA
Earth Observations
Manually Editing a URL

You can modify a map request URL manually.

1 Obtain the map request URL.
nasa = wmsfind('nasa', 'SearchField', 'serverurl');
layer = nasa.refine('bluemarbleng', 'SearchField', 'layername', ...

'MatchType', 'exact');
layer = layer(1);
mapRequest = WMSMapRequest(layer);

2View the map request URL by typing mapRequest.RequestURL at the command line.
Sample Output:

ans =
http://neowms.sci.gsfc.nasa.gov/wms/wms?... SERVICE=WMS...
&LAYERS=BlueMarbleNG...
&EXCEPTIONS=application/vnd.ogc.se_xml... &FORMAT=image/jpeg...
&TRANSPARENT=FALSE...
&HEIGHT=256...
&BGCOLOR=0xFFFFFF...
&REQUEST=GetMap&WIDTH=512...
&BBOX=-180.0,-90.0,180.0,90.0...
&STYLES=&SRS=EPSG:4326...
&VERSION=1.1.1

3 Modify the bounding box to include the southern hemisphere by directly changing the
mapRequest.RequestURL. Enter the following at the command line:

modifiedURL =
Then enter the lengthy URL as shown in the previous code sample, but change the bounding box:
&BBOX=-180.0,-90.0,180.0,0.0
Enter the URL as one continuous string.
4 Display the modified map.

[A, R] = wmsread(modifiedURL);
figure
axesm globe
axis off
geoshow(A, R)
title('Blue Marble: Southern Hemisphere Edition')
 Courtesy NASA/
JPL-Caltech

Overlaying Multiple Layers

In this section...
Creating a Composite Map of Multiple Layers from One Server on page 9-41
Combining Layers from One Server with Data from Other Sources on page 9-42
Draping Topography and Ortho-Imagery Layers over a Digital Elevation Model Layer on page 9-44

Creating a Composite Map of Multiple Layers from One Server

TheWMSspecificationallowstheservertomergemultiplelayersintoa single raster map. Metacartas

VMAP0 server contains many data layers, such as coastlines, national boundaries, ocean, and ground.
Read and display a composite of multiple layers from the VMAP0 server. The rendered map has a
spatial resolution of 0.5 degrees per cell.

1 Find and update the VMAP0 layers.

vmap0 = wmsfind('vmap0.tiles', 'SearchField', 'serverurl'); vmap0 = wmsupdate(vmap0);
2 Create an array of multiple layers that include ground and ocean, coastlines and national boundaries.

layers = [refine(vmap0, 'coastline_01'); ... refine(vmap0, 'country_01'); ... refine(vmap0, 'ground_01'); ... refine(vmap0,
'inwater'); ... refine(vmap0, 'ocean')];
3 Retrieve the composite map. Request a cell size of .5 degrees by setting the image height and image
width parameters. Set Transparent to true so that all pixels not representing features or data values in a
layer are set to a transparent value in the resulting image, making it possible to produce a composite
map.

[overlayImage, R] = wmsread(layers, 'Transparent', true, ... 'ImageHeight', 360, 'ImageWidth', 720);

4 Display your composite map.

figure
worldmap('world')
geoshow(overlayImage, R);
title('Composite of VMAP0 Layers')

Combining Layers from One Server with Data from Other Sources

This example, a continuation of the one preceding it, illustrates how you can merge the boundaries raster
map with vector data. Combine two separate calls to vec2mtx to create a 4-color raster map showing
interior land areas, coastlines, national boundaries, oceans, and world rivers. The vec2mtx function
converts latitude-longitude vectors to a regular data grid. 1 Read the landareas vector shapefile and
convert it to an image.

land = shaperead('landareas', 'UseGeoCoords', true); lat = [land.Lat];

lon = [land.Lon];
[landImage, refvec] = ...

vec2mtx(lat, lon, 2, [-90, 90], [-180,180], 'filled'); mergedImage = landImage;

2 Read the worldrivers vector shapefile and convert it to an image.
rivers = shaperead('worldrivers.shp','UseGeoCoords',true); riverImage = vec2mtx([rivers.Lat], [rivers.Lon], landImage,
refvec);
3 Merge the rivers with the land.
mergedImage(riverImage == 1) = 3;
4 Obtain the boundaries image from the VMAP0 server.
vmap0 = wmsfind('vmap0.tiles', 'SearchField', 'serverurl'); vmap0 = wmsupdate(vmap0);
layer = refine(vmap0, 'country_01');
height = size(riverImage, 1);
width = size(riverImage, 2);
[boundaries, R] = wmsread(layer, 'ImageFormat', 'image/png', ...

'ImageHeight', height, 'ImageWidth', width);

5 Merge the rivers and land with the boundaries. You must first flip mergedImage because it has a
reference defined by a referencing vector, where columns run from south to north. (The columns of
WMS images run from north to south.)

mergedImage = flipud(mergedImage); index = boundaries(:,:,1) ~= 255 ... & boundaries(:,:,2) ~= 255 ...
& boundaries(:,:,3) ~= 255; mergedImage(index) = 1;

6 Display the result.

figure
worldmap(mergedImage, R)
geoshow(mergedImage, R, 'DisplayType', 'texturemap') colormap([.45 .60 .30; 0 0 0; 0 0.5 1; 0 0 1])

Draping Topography and Ortho-Imagery Layers over a Digital Elevation Model

Layer

Uncompress the zip file and read it with the ugs24kdem function. Set the geographic limits to the
minimum and maximum values in the DEM file.
1 Uncompress the zip file and read it with the usgs24kdem function. Set the geographic limits to the
minimum and maximum values in the DEM file.
filenames = gunzip('sanfranciscos.dem.gz', tempdir);
demFilename = filenames{1};
[lat,lon,Z,header,profile] = usgs24kdem(demFilename, 1); delete(demFilename);
Z(Z==0) = -1;
latlim = [min(lat(:)) max(lat(:))];
lonlim = [min(lon(:)) max(lon(:))];

2 Display the USGS 24K DEM data. Create map axes for the United States and assign an appropriate
elevation colormap. Use daspectm to display the elevation data.

figure
usamap(latlim, lonlim)
geoshow(lat, lon, Z, 'DisplayType','surface') demcmap(Z)
daspectm('m',1)
title('San Francisco South 24K DEM');

3Set the point of view by adjusting the CameraPosition, CameraTarget, and CameraAngle axes
properties.
cameraPosition = [87907 4.4313e+06 53103]; cameraTarget = [-1961.5 4.492e+06 231.46]; cameraAngle = 5.57428;
set(gca,'CameraPosition', cameraPosition, ...

'CameraTarget', cameraTarget, ... 'CameraViewAngle', cameraAngle)

4 The USGS National Map provides ortho-imagery and topographic maps from various regions of the
United States. One method to obtain the high-resolution ortho-imagery layer name is to obtain the
capabilities document from the server. The ortho-imagery layer is the only layer from this server. Use
multiple attempts to connect to the server in case it is busy.

numberOfAttempts = 5;
attempt = 0;
info = [];
serverURL = 'http://isse.cr.usgs.gov/arcgis/services/Orthoimagery/USGS_EDC_ while(isempty(info))

try
info = wmsinfo(serverURL); orthoLayer = info.Layer(1);

catch e
attempt = attempt + 1;
if attempt > numberOfAttempts

throw(e);
else
fprintf('Attempting to connect to server:\n"%s"\n', serverURL) end
end
end

5 Use the 'DRG_100k' layer.(DRG is an acronymn for Digital Raster Graphics).

layer = wmsfind('DRG_100k', 'MatchType', 'exact'); topoLayer = refine(layer, 'DRG', 'SearchField', 'serverurl');
6 Set the size for the requested images.
imageHeight = size(Z,1)*3; imageWidth = size(Z,2)*3;
7 Request a map of the ortho-imagery layer.
orthoImage = wmsread(orthoLayer, 'Latlim', latlim, 'Lonlim', lonlim, ... 'ImageHeight', imageHeight, 'ImageWidth',
imageWidth);
8 Request a map of the topographic layer.
topoMap = wmsread(topoLayer, 'Latlim', latlim, 'Lonlim', lonlim, ... 'ImageHeight', imageHeight, 'ImageWidth', imageWidth);
9 Drape the ortho-image onto the elevation data.

figure
usamap(latlim, lonlim)
geoshow(lat, lon, Z, ...

'DisplayType', 'surface', 'CData', orthoImage); daspectm('m',1)

title('San Francisco Ortho-Image');
axis vis3d
set(gca,'CameraPosition', cameraPosition, ...
'CameraTarget', cameraTarget, ... 'CameraViewAngle', cameraAngle)

10 Drape the
topographic map onto the elevation data.
figure
usamap(latlim, lonlim)
geoshow(lat, lon, Z, ...

'DisplayType', 'surface', 'CData', topoMap); daspectm('m',1)

title('San Francisco Topo Map');
axis vis3d
set(gca,'CameraPosition', cameraPosition, ...
'CameraTarget', cameraTarget, ...
'CameraViewAngle', cameraAngle)

Animating Data Layers

In this section...
Creating Movie of Terra/MODIS Images on page 9-51
Creating an Animated GIF File on page 9-53
Animating Time-Lapse Radar Observations on page 9-56 Displaying Animation of Radar Images
over GOES Backdrop on page 9-59

Creating Movie of Terra/MODIS Images

You can create maps of the same geographic region at different times and view them as a movie. For a
period of seven days, read and display a daily composite of visual images from NASAs Moderate
Resolution Imaging Spectroradiometer (MODIS) scenes captured during the month of December 2010.

1 Search the WMS Database for the MODIS layer.

neo = wmsfind('neowms*nasa', 'SearchField', 'serverurl'); modis = neo.refine('true*color*terra*modis');
modis = wmsupdate(modis);
2 Construct a WebMapServer object.
server = WebMapServer(modis.ServerURL);
3 Construct a WMSMapRequest object.
mapRequest = WMSMapRequest(modis, server);

4 The Extent field provides the information about how to retrieve individual frames. You can request a
single day since the extent is defined by day ('/P1D'). Note that for December 2010, the frames for
December 8 and December 31 are not available.

modis.Details.Dimension.Extent
5 Create an array indicating the first seven days.
days = 1:7;
6 Set the value of startTime to December 01, 2010 and use a serial date number.
time = '2010-12-01';
startTime = datenum(time);
7 Open a figure window with axes appropriate for the region specified by the modis layer.
hFig = figure('Color', 'white');
worldmap(mapRequest.Latlim, mapRequest.Lonlim);
8 Saveeachframeintoavideofile.

videoFilename = 'modis_dec.avi'; writer = VideoWriter(videoFilename); writer.FrameRate = 1;

writer.Quality = 100;
writer.open;

9 Retrieve a map of the modis layer for each requested day. Set the Time property to the day number.
When obtaining the data from the server, use a try/catch statement to ignore either data not found on the
server or any error issued by the server. Set startTime to one day less for correct indexing.

startTime = startTime - 1; for k = days

try

mapRequest.Time = startTime + k;
timeStr = datestr(mapRequest.Time);
dailyImage = server.getMap(mapRequest.RequestURL); geoshow(dailyImage, mapRequest.RasterRef);
title({mapRequest.Layer.LayerTitle, timeStr}, ...

'Interpreter', 'none', 'FontWeight', 'bold') shg

frame = getframe(hFig);
writer.writeVideo(frame);

catch e
fprintf(['Server error: %s.\n', ...
'Ignoring frame number %d on day %s.\n'], ... e.message, k, timeStr)

end
drawnow
shg

end
writer.close
10 Read in all video frames.
v = VideoReader(videoFilename); vidFrames = read(v);
numFrames = get(v, 'NumberOfFrames');

11 Create a MATLAB movie structure from the video frames.

frames = struct('cdata', [], 'colormap', []); frames(numFrames) = frames(1);
for k = 1 : numFrames

frames(k).cdata = vidFrames(:,:,:,k); frames(k).colormap = [];

end
12 Playback movie once at the videos frame rate. movie(hFig, frames, 1, v.FrameRate)

Creating an Animated GIF File

Read and display an animation of the Larsen Ice Shelf experiencing a dramatic collapse between
January 31 and March 7, 2002.
1 Search the WMS Database for the phrase Larsen Ice Shelf.
iceLayer = wmsfind('Larsen Ice Shelf');
Try the first layer.
2 Construct a WebMapServer object.
server = WebMapServer(iceLayer(1).ServerURL);

3Use the WebMapServer.updateLayers method to synchronize the layer with the WMS source server.
Retrieve the most recent data and fill in the Abstract, CoordRefSysCodes,and Details fields.

iceLayer = server.updateLayers(iceLayer(1));
4 View the abstract.
fprintf('%s\n', iceLayer(1).Abstract)
5 Create the WMSMapRequest object.
request = WMSMapRequest(iceLayer(1), server);

6 Because you have updated your layer, the Details field now has content. Click Details in the MATLAB
Variables editor. Then, click Dimension.The name of the dimension is 'time'.Click Extent.The Extent field
provides the available values for a dimension, in this case time. Save this information by entering the
following at the command line:

extent = [',' iceLayer.Details.Dimension.Extent, ','];

7 Calculate the number of required frames. (The extent contains a comma before the first frame and after
the last frame. To obtain the number of frames, subtract 1.)

frameIndex = strfind(extent, ','); numFrames = numel(frameIndex) - 1;

8 Open a figure window and set up a map axes with appropriate geographic limits.
h = figure;
worldmap(request.Latlim, request.Lonlim)

9 Set the map axes properties. MLineLocation establishes the interval between displayed grid meridians.
MLabelParallel determines the parallel where the labels appear.
setm(gca,'MLineLocation', 1, 'MLabelLocation', 1, ... 'MLabelParallel',-67.5, 'LabelRotation', 'off');
10 Initialize the value of animated to 0.
animated(1,1,1,numFrames) = 0;
11 Display the image of the Larsen Ice Shelf on different days.

for k=1:numFrames
request.Time = extent(frameIndex(k)+1:frameIndex(k+1)-1); iceImage = server.getMap(request.RequestURL);
geoshow(iceImage, request.RasterRef)
title(request.Time, 'Interpreter', 'none')
drawnow
shg
frame = getframe(h);
if k==1

[animated, cmap] = rgb2ind(frame.cdata, 256, 'nodither'); else

animated(:,:,1,k) = rgb2ind(frame.cdata, cmap, 'nodither'); end
end

12 Save and then view the animated GIF file.

filename = 'wmsanimated.gif';
imwrite(animated, cmap, filename, 'DelayTime', 1.5, ... 'LoopCount', inf);
web(filename)
Courtesy NASA/Goddard Space Flight Center Scientific Visualization Studio Snapshot from Animation of Larsen Ice
Shelf

Animating Time-Lapse Radar Observations

Display Next-Generation Radar (NEXRAD) images for the United States using data from the Iowa
Environmental Mesonet (IEM) Web map server. The server stores layers covering the past 50 minutes
up to the present time in increments of 5 minutes. Read and display the merged layers.

1 Find layers in the WMS Database that include 'mesonet' and 'nexrad' in their ServerURL fields.
mesonet = wmsfind('mesonet*nexrad', 'SearchField', 'serverurl');

2 NEXRAD Base Reflect Current ('nexrad-n0r')measurestheintensityof precipitation. Refine your search to

include only layers with this phrase in one of the search fields.

nexrad = mesonet.refine('nexrad-n0r', 'SearchField', 'any');

3 Remove the 900913 layers because they are intended for Google Maps overlay. Also remove the
WMST layer because it contains data for different times.
layers_900913 = nexrad.refine('900913', 'SearchField', ... 'layername');
layer_wmst = nexrad.refine('wmst', 'SearchField', 'layername');
rmLayerNames = {layers_900913.LayerName layer_wmst.LayerName};
index = ismember({nexrad.LayerName}, rmLayerNames);
nexrad = nexrad(~index);

4 Update your nexrad layer to fill in all fields and obtain most recent data.
nexrad = wmsupdate(nexrad, 'AllowMultipleServers', true);
 represents the conterminous 48 U.S. states (all except Hawaii and Alaska). Use the usamap
5 'conus'
function to construct a map axes for the conterminous states. Read in the nexrad layers.

region = 'conus';
figure
usamap(region)
mstruct = gcm;
latlim = mstruct.maplatlimit;
lonlim = mstruct.maplonlimit;
[A, R] = wmsread(nexrad, 'Latlim', latlim, 'Lonlim', lonlim, ...

'Transparent', true);
6 Display the NEXRAD merged layers map. Overlay with United States state boundary polygons.

geoshow(A, R);
geoshow('usastatehi.shp', 'FaceColor', 'none'); title({'NEXRAD Radar Map', 'Merged Layers'});

Courtesy NOAA and Iowa State University

7 Loop through the sequence of time-lapse radar observations.
hfig = figure;
usamap(region)
geoshow('usastatehi.shp', 'FaceColor', 'none');
numFrames = numel(nexrad);
frames = struct('cdata', [], 'colormap', []);
frames(numFrames) = frames;
hmap = [];
frameIndex = 0;
for k = numFrames:-1:1

frameIndex = frameIndex + 1;
delete(hmap)
[A, R] = wmsread(nexrad(k), 'Latlim', latlim, 'Lonlim', lonlim); hmap = geoshow(A, R);
title(nexrad(k).LayerName)
drawnow
frames(frameIndex) = getframe(hfig);
end

8 Create an array to write out as an animated GIF file.

animated(1,1,1,numFrames) = 0;
for k=1:numFrames
if k==1

[animated, cmap] = rgb2ind(frames(k).cdata, 256, 'nodither'); else

animated(:,:,1,k) = ...
rgb2ind(frames(k).cdata, cmap, 'nodither');
end
end

9 View the animated GIF file.

filename = 'wmsnexrad.gif';
imwrite(animated, cmap, filename, 'DelayTime', 1.5, ... 'LoopCount', inf);
web(filename)
1
Displaying Animation of Radar Images over GOES Backdrop

Display NEXRAD radar images for the past 24 hours, sampled at one-hour intervals, for the United
States using data from the IEM WMS server. Use the JPL Daily Planet layer as the backdrop.

Find the 'nexrad-n0r-wmst' layer and update it.

wmst = wmsfind('nexrad-n0r-wmst', 'SearchField', 'layername'); wmst = wmsupdate(wmst);
2 Find a generated CONUS composite of GOES IR imagery and update it.
goes = wmsfind('goes*conus*ir', 'SearchField', 'layername'); goes = wmsupdate(goes);
3 Create a figure with the desired geographic extent.

hfig = figure; region = 'conus'; usamap(region)

mstruct = gcm;
latlim = mstruct.maplatlimit; lonlim = mstruct.maplonlimit;

4 Read the GOES layer as a backdrop image.

cellsize = .1;
[backdrop, R] = wmsread(goes, 'ImageFormat', 'image/png', ... 'Latlim', latlim, 'Lonlim', lonlim, 'Cellsize', cellsize);
5 Calculate current time minus 24 hours and set up frames to hold the data from getframe.

now_m24 = datestr(now-1);
hour_m24 = [now_m24(1:end-5) '00:00']; hour = datenum(hour_m24);
hmap = [];
numFrames = 24;
frames = struct('cdata', [], 'colormap', []); frames(numFrames) = frames;

6For each hour, obtain the hourly NEXRAD map data and combine it with a copy of the backdrop.
Because of how this Web server handles PNG format, the resulting map data has an image with class
double. Thus, you must convert it to uint8 before merging.

geoshow('usastatehi.shp', 'FaceColor', 'none');

black = [0,0,0];
threshold = 0;
for k=1:numFrames

time = datestr(hour);
[A, R] = wmsread(wmst, 'Latlim', latlim, 'Lonlim', lonlim, ... 'Time', time, 'CellSize', cellsize, ...
'BackgroundColor', black, 'ImageFormat', 'image/png');
delete(hmap)
index = any(A > threshold, 3);
combination = backdrop;
index = cat(3,index,index,index);
combination(index) = uint8(255*A(index));
hmap = geoshow(combination, R); title({wmst.LayerName, time}) drawnow
frames(k) = getframe(hfig); hour = hour + 1/24;
end

7 View the movie loop.

numTimes = 10;
fps = 1.5;
movie(hfig, frames, numTimes, fps);

Retrieving Elevation Data

In this section...
Merge Elevation Data with Rasterized Vector Data on page 9-63

Display a Merged Elevation and Bathymetry Layer (SRTM30 Plus) on page 9-66
Drape a Landsat Image onto Elevation Data on page 9-70

Typically, a WMS server returns a pictorial representation of a layer (or layers) back to a requestor
rather than the actual data. However, in some rare cases, you can request actual data from specific WMS
servers, by using a certain option with wmsread.

A WMS server renders one or more layers and stores the results in a file, which is streamed to the
requestor. The wmsread function, or the getMap method of the WebMapServer class, makes the request on
your behalf, captures the stream in a temporary file, and imports the file content into a variable in your
MATLAB workspace. The format of the file may be a standard graphics format, such as JPEG, PNG, or
GIF, or it may be the band-interleaved by line (BIL) format, which is popular in remote sensing. Almost
all WMS servers support use of the JPEG format, and many support more than one standard graphics
format. Only a very few WMS servers support the BIL format, although it is very useful.

The choice of format can affect the quality of your results. For example, PNG format avoids the tile-
related artifacts that are common with JPEG. Format choice also determines whether you will get a
pictorial representation, which is the case with any of the standard graphics formats, or an absolutely
quantitative data grid (possibly including negative as well as positive values). Quantitative data sets are
provided via the BIL format.

With a server that supports multiple formats, you can control which format is used by specifying an
ImageFormat name-value pair when calling wmsread. For example, if the server supports the PNG format
you would choose PNG by specifying 'ImageFormat','image/png', thus avoiding the possibility of JPEG
artifacts.
With a server that supports it, you can obtain an absolutely quantitative data grid by specifying BIL
format when calling wmsread. Todothis,usethe name-value pair 'ImageFormat','image/bil'. Although a BIL file
typically contains multiple, co-registered bands (channels), the BIL files returned by a WMS server
include only a single band. In this case, the output of wmsread enters the MATLAB workspace as a 2-D
array.

For example, you can obtain signed, quantitative elevation data, rather than an RGB image, from the
NASA WorldWind WMS server (the only server in the Mapping Toolbox WMS database known to
support the 'image/bil' option). See the output from the command:

wmsinfo('http://www.nasa.network.com/elev?')
In fact, because the NASA WorldWind WMS server returns rendered layers only in the 'image/bil' format,
you do not need to provide an 'ImageFormat' name-value pair when using this server. However, it is good
practice to specify the image format, in case the server is ever updated to provide rendered layers in
other image formats.

After retrieving data using the 'ImageFormat','image/bil' option, display it as a surface or a texture-mapped
surface, rather than as an image, as shownintheexamplesbelow.

Merge Elevation Data with Rasterized Vector Data

The NASA WorldWind WMS server contains a wide selection of layers containing elevation data.
Follow this example to merge elevation data with a raster map containing national boundaries.

1 Find the layers from the NASA WorldWind server.

layers = wmsfind('nasa.network*elev', 'SearchField', 'serverurl'); layers = wmsupdate(layers);
2 Display the name and title of each layer.
disp(layers,'Properties',{'LayerTitle','LayerName'})
11x1 WMSLayer Properties:
Index: 1
LayerTitle: 'SRTM30 with Bathymetry (900m) merged with global ASTER ( LayerName: 'EarthAsterElevations30m'
Index: 2
LayerTitle: 'USGS NED 30m' LayerName: 'NED'
Index: 3
LayerTitle: 'ScankortElevationsDenmarkDSM'

LayerName: 'ScankortElevationsDenmarkDSM' .
.
.

Index: 10
LayerTitle: 'SRTM30 Plus'
LayerName: 'srtm30'
Index: 11
LayerTitle: 'USGS NED 10m' LayerName: 'usgs_ned_10m'
3 Select the 'EarthAsterElevations30m' layer containing SRTM30 data merged with global ASTER data.
aster = layers.refine('earthaster', 'SearchField', 'layername');
4 Define the region surrounding Afghanistan.
latlim = [25 40]; lonlim = [55 80];
5 Obtain the data at a 1-minute sampling interval.
cellSize = dms2degrees([0,1,0]);
[ZA, RA] = wmsread(aster, 'Latlim', latlim, 'Lonlim', lonlim, ... 'CellSize', cellSize, 'ImageFormat', 'image/bil');
6 Display the elevation data as a texture map.

figure('Renderer','zbuffer')
worldmap('Afghanistan')
geoshow(ZA, RA, 'DisplayType', 'texturemap')
demcmap(double(ZA))
title({'Afghanistan and Surrounding Region', aster.LayerTitle});
 7 Embed national
boundaries from the VMAP0 WMS server into the elevation map.
vmap0 = wmsfind('vmap0.tiles', 'SearchField', 'serverurl'); boundaries = refine(vmap0, 'country_02');
B = wmsread(boundaries, 'Latlim', latlim, ...

'Lonlim', lonlim, 'CellSize', cellSize, 'ImageFormat','image/png');

ZB = ZA;
ZB(B(:,:,1) < 250) = min(ZA(:));
figure('Renderer','zbuffer')
worldmap('Afghanistan')
demcmap(double(ZA))
geoshow(ZB, RA, 'DisplayType', 'texturemap')
title({'Afghanistan and Country Boundaries', aster.LayerTitle});
Display a Merged Elevation and Bathymetry Layer (SRTM30 Plus)

The Shuttle Radar Topography Mission (SRTM) is a project led by the U.S. National Geospatial-
Intelligence Agency (NGA) and NASA. SRTM has created a high-resolution, digital, topographic
database of Earth. The SRTM30 Plus data set combines GTOPO30, SRTM-derived land elevation and
Sandwell bathymetry data from the University of California at San Diego.

Follow this example to read and display the SRTM30 Plus layer for the Gulf of Maine at a 30 arc-second
sampling interval using data from the WorldWind server.

1 Find and update the 'srtm30' layer in the WMS Database. The 'srtm30'
layernamefromNASAWorldWindisthenamefortheSRTM30Plusdataset.
wldwind = wmsfind('nasa.network*elev', 'SearchField', 'serverurl'); wldwind = wmsupdate(wldwind);
srtmplus = wldwind.refine('srtm30', 'SearchField', 'layername');

2 Set the desired geographic limits.

latlim = [40 46]; lonlim = [-71 -65];
3 Set the sampling interval to 30 arc-seconds.
samplesPerInterval = dms2degrees([0 0 30]);
4 Set the ImageFormat to image/bil.
imageFormat = 'image/bil'; 5 Request the map from the NASA server.

[Z1, R1] = wmsread(srtmplus, 'Latlim', latlim, ... 'Lonlim', lonlim, 'ImageFormat', imageFormat, ... 'CellSize',
samplesPerInterval);
6 Open a figure window and set up a map axes with geographic limits that match the desired limits. The
referencing matrix R1 ties the intrinsic coordinates of the raster map to the EPSG:4326 geographic
coordinate system. Create a colormap appropriate for elevation data. Then, display and contour the map
at sea level (0 m).

figure('Renderer','zbuffer')
worldmap(Z1, R1)
geoshow(Z1, R1, 'DisplayType', 'texturemap') demcmap(double(Z1))
contourm(double(Z1), R1, [0 0], 'Color', 'black')
colorbar
title ({'Gulf of Maine', srtmplus.LayerTitle}, 'Interpreter','none')

7Compare the NASA WorldWind SRTM30 Plus layer with the SRTM30 with Bathymetry (900m)
merged with SRTM3 V4.1 (90m) and USGS NED (30m) (mergedSrtm)layer.

mergedSrtm = wldwind.refine('mergedSrtm');
8 Request the map from the NASA WorldWind server.
[Z2, R2] = wmsread(mergedSrtm, 'Latlim', latlim, 'Lonlim', lonlim, ... 'CellSize', samplesPerInterval, 'ImageFormat', 'image/
bil');
9 Display the data.

figure('Renderer','zbuffer')
worldmap(Z2, R2)
geoshow(Z2, R2, 'DisplayType', 'texturemap') demcmap(double(Z2))
contourm(double(Z2), R2, [0 0], 'Color', 'black') colorbar
title ({'Gulf of Maine', mergedSrtm.LayerTitle})

10 Compare the results.

fprintf(...
'\nSRTM30 Plus - %s\nMinimum value: %d\nMaximum value: %d\n', ... srtmplus.LayerName, min(Z1(:)), max(Z1(:)));

fprintf(...
'\nSRTM30 Plus Merged - %s\nMinimum value: %d\nMaximum value: %d\n', ... mergedSrtm.LayerName, min(Z2(:)),
max(Z2(:)));

11 The output appears as follows:

SRTM30 Plus - srtm30

Minimum value: -4543
Maximum value: 1463
Merged SRTM30 Plus - mergedSrtm Minimum value: -4543
Maximum value: 1463

Drape a Landsat Image onto Elevation Data

For some applications, you may want to merge elevation data with imagery. Follow this example to
drape Landsat imagery onto elevation data from the USGS National Elevation Dataset (NED) for an
area surrounding the Grand Canyon. Read the landsat layer from the USGS EROS Web Map server and
the USGS us_ned layer from the NASA WorldWind server.

1 Obtain the layers of interest.

landsat = wmsfind('landsat', 'SearchField', 'any');
global_mosaic = landsat.refine('LANDSAT_LZ77', 'MatchType', 'exact'); layers = wmsfind('nasa.network', 'SearchField',
'serverurl'); us_ned = layers.refine('usgs ned 30');

2 Assign geographic extent and image size.

latlim = [36 36.23];
lonlim = [-113.36 -113.13]; imageHeight = 575;
imageWidth = 575;

3 Read the global_mosaic layer.

A = wmsread(global_mosaic, 'Latlim', latlim, 'Lonlim', lonlim, ... 'ImageHeight', imageHeight, 'ImageWidth', imageWidth);
4 Read the USGS us_ned layer.

[Z, R] = wmsread(us_ned, 'ImageFormat', 'image/bil', ... 'Latlim', latlim, 'Lonlim', lonlim, ...
'ImageHeight', imageHeight, 'ImageWidth', imageWidth);

5 Drape the Landsat image onto the elevation data.

figure('Renderer','opengl') usamap(latlim, lonlim) framem off; mlabel off; plabel off; gridm off
geoshow(double(Z), R, 'DisplayType', 'surface', 'CData', A); daspectm('m',1)
title({'Grand Canyon', 'USGS NED and Landsat Global Mosaic'}, ...
'FontSize',8);
axis vis3d

6 Assign camera parameters.

cameraPosition = [96431 4.2956e+06 -72027]; cameraTarget = [-82.211 4.2805e+06 3054.6]; cameraViewAngle = 8.1561;
cameraUpVector = [3.8362e+06 5.9871e+05 5.05123e+006];

7 Set camera and light parameters.

set(gca,'CameraPosition', cameraPosition, ... 'CameraTarget', cameraTarget, ...
'CameraViewAngle', cameraViewAngle, ... 'CameraUpVector', cameraUpVector);

lightHandle = camlight;
camLightPosition = [7169.3 1.4081e+06 -4.1188e+006]; set(lightHandle, 'Position', camLightPosition);
Saving Favorite Servers

You can save your favorite layers for easy access in the future. Use wmsupdate to fill in the Abstract,
CoordRefSysCodes,and Details fields, and then save the layers. The next example demonstrates how to make
a mini-database from the NASA, WHOI, and ESA servers.

1 Find the servers and update all fields.

nasa = wmsfind('nasa','SearchField','serverurl'); favoriteLayers = nasa;
favoriteLayers = wmsupdate(favoriteLayers, ...

'AllowMultipleServers', true);
favoriteServers = favoriteLayers.servers;
2 Save your favorite layers in a MAT-file.
save favorites favoriteLayers
3 Search within your favorite layers for 'wind speed'. You have updated all fields, so you can search within
any field, including the Abstract. windSpeed = favoriteLayers.refine('wind speed','SearchFields','any')

Exploring Other Layers from a Server

You may find a layer you like in the WMS Database and then want to find other layers on the same
server.

1 Use the wmsinfo function to return the contents of the capabilities document as a WMSCapabilities object.
A capabilities document is an XML document containing metadata describing the geographic content
offered by a server.
serverURL = 'http://webapps.datafed.net/AQS_H.ogc?'; capabilities = wmsinfo(serverURL);
2 View the layer names.
capabilities.LayerNames
Sample Output:
ans =

'CO'
'NO2' 'NOX' 'NOY' 'O3'
'SO2' 'pm10'

3 Read the Carbon Monoxide ('CO')layer.

layer = capabilities.Layer.refine('CO');
[A,R] = wmsread(layer,'cellsize',.1,'ImageFormat','image/png'); 4 Set the longitude and latitude limits to the values
specified for the layer.
latlim = layer.Latlim; lonlim = layer.Lonlim;
5 Display the map.

figure
usamap(layer.Latlim, layer.Lonlim) geoshow('usastatehi.shp','FaceColor','none','EdgeColor','black') geoshow(A,R)
title(layer.LayerTitle)

Courtesy EPA

6 Examine the Style field. (Open layer and then Details and then Style.) Therearetwostructures.
Thestyleofthefirstoneissetto 'data'.Read the layer again with the StyleName set to 'data' and the cell size set
to 0.1 degree resolution. (When the style is set to 'data', the map does not include a legend.)

[A,R] = wmsread(layer,'cellsize',.1, ...

'ImageFormat','image/png','StyleName','data');
figure
usamap(layer.Latlim, layer.Lonlim)
geoshow('usastatehi.shp','FaceColor','none','EdgeColor','black')
geoshow(A,R)
title(layer.LayerTitle)

Courtesy
EPA

Writing a KML File

Some WMS server implementations, such as GeoServer, can render their maps in a non-image format,
such as KML. KML is an XML dialect used by Google Earth and Google Maps browsers. The
WebMapServer.getMap method and the wmsread function do not allow you to use the KML format because
they import only standard graphics image formats. Work around this limitation by using the
WMSMapRequest.RequestURL property.

1Search the WMS Database for layers on any GeoServer. Refine to include only the layers from the
MassGIS server. Refine that list to return a FEMA Flood Zone layer.

geoserver = wmsfind('geoserver', 'SearchField', 'any'); massgis = geoserver.refine('massgis*wms', 'SearchField', ...

'serverurl');
massgis = wmsupdate(massgis);
floodzone = massgis.refine('FEMA Flood Zones', 'SearchField', ...

'LayerTitle');
floodzone = floodzone(1);
2 Set geographic limits for a region around Boston, Massachusetts.
latlim = [ 42.305 42.417]; lonlim = [-71.131 -70.99];
3 Construct a WMSMapRequest object and set the geographic limits.
request = WMSMapRequest(floodzone); request.Latlim = latlim;
request.Lonlim = lonlim;

4 Obtain the graphics image from the server.

[A, R] = wmsread(request.RequestURL);
5 Display the image in a figure window.
figure
usamap(A, R)

6 Request an image format that opens in

Google Earth.
request.ImageFormat = 'application/vnd.google-earth.kml+xml';
7 Use the urlwrite function to write out a KML file.
filename = 'floodzone.kml';
urlwrite(request.RequestURL, filename);
8 OpenthefilewithGoogleEarthtoview. OnWindowsplatforms,display the KML file with:
winopen(filename)

For UNIX and Mac users, display the KML file with:

cmd = 'googleearth ';

fullfilename = fullfile(pwd, filename);
system([cmd fullfilename])
Searching for Layers Outside the Database

You can search for layers by using your Web browser rather than by using the WMS Database. For
example, this approach allows you to view layers developed more recently than the last software release.

1To search for layers outside the WMS Database, use your favorite search engine. If you are using
Google, select Images and enter the following in the search box: getmap wms.

2 View the images to choose a map. Click the map link and find the WMS GetCapabilities request
somewhere on the page. If you cannot find a GetCapabilities request, try another map.

For this example, the syntax for the URL of the WMS GetCapabilities request appearsasfollows:
url = ['http://sampleserver1.arcgisonline.com/' ...
'ArcGIS/services/Specialty/ESRI_StatesCitiesRivers_USA/' ... 'MapServer/
WMSServer?service=WMS&request=GetCapabilities' ... '&version=1.3.0'];

3 After you obtain the URL, you can use wmsinfo to return the capabilities document.
c = wmsinfo(url);
4 Next, read in a layer and display it as a map.

[A,R] = wmsread(c.Layer(1), ...

'BackgroundColor', [0,0,255], 'ImageFormat', 'image/png');
figure
usamap(c.Layer(1).Latlim, c.Layer(1).Lonlim)

Hosting Your Own WMS Server

You can host your own WMS server and share the maps you create with others. For free software and
instructions, see the GeoServer or MapServer Web sites.

CommonProblemswithWMSServers

In this section...
Connection Errors on page 9-81
Wrong Scale on page 9-83
Problems with Geographic Limits on page 9-84
Problems with Server Changing LayerName on page 9-84 Non-EPSG:4326 Coordinate Reference
Systems on page 9-85 Map Not Returned on page 9-85
Unsupported WMS Version on page 9-86
Other Unrecoverable Server Errors on page 9-87

Connection Errors

One of the challenges of working with WMS is that sometimes you can have
troubleconnectingtoaserver.
Time-Out Error
A server may issue a time-out error such as:
Connection timed out: connect
Or
Read timed out

Workaround: Try setting the 'TimeoutInSeconds' parameter to a larger value. The time-out setting defaults
to 60 seconds. (The functions wmsread, wmsinfo,and wmsupdate all have 'TimeoutInSeconds' parameters.)

Server No Longer Provides Full WMS Services

The NASA Jet Propulsion Laboratory (JPL) server may issue the following error message:

The DataFed server, http://webapps.datafed.net/OnEarth_JPL.ogc?,

This server no longer provides full WMS services!
cascades layers from the JPL server and may issue the following error message:

Error in Execution. Cannot fetch url.

Workaround: Use a TiledWMS URL or find a different server.

The JPL Global Imagery Service server,

http://onearth.jpl.nasa.gov/wms.cgi?, is no longer providing full WMS services for any of the datasets. Any
server (for example, http://webapps.datafed.net/OnEarth_JPL.ogc?) that cascades data from this server is also
affected by the change.

A small subset of the data can be accessed using a non-standard TiledWMS request. The available tiled
patterns can be found at:
http://pat.jpl.nasa.gov/wms.cgi?request=GetTileService

The WMS parameters must be in the exact order. If

you wish to obtain a tile, you can prepend the prefix,
'http://onearth.jpl.nasa.gov/wms.cgi?/SERVICE=WMS&' in front of the request found in the CDATA section of the
GetTileService request.

For example:
url = ['http://onearth.jpl.nasa.gov/wms.cgi?/SERVICE=WMS&' ...
'request=GetMap&layers=global_mosaic&srs=EPSG:4326&' ... 'format=image/
jpeg&styles=visual&width=512&height=512&' ... 'bbox=-180,58,-148,90'];

[A, R] = wmsread(url);

Elevation layers from onearth.jpl.nasa.gov can be replaced with layers from the NASA WorldWind server
(http://www.nasa.network.com/elev?). The Blue Marble layer can be replaced with a Blue Marble layer from
the NASA Goddard Space Flight Center WMS SVS Image Server (http://svs.gsfc.nasa.gov/cgi-bin/wms?) or
the Blue Marble: Next Generation layer from the NASA Earth Observations (NEO) WMS Server
(http://neowms.sci.gsfc.nasa.gov/wms/wms?).

The Daily Planet layer can be replaced with the 'True Color (1 day Terra/MODIS Rapid Response)' layer from
the NASA Earth Observations (NEO) WMS server.
HTTP Response Code 500
In some cases, the server becomes temporarily unavailable or the WMS server application experiences
some type of issue. The server issues an HTTP response code of 500, such as:

Server returned HTTP response code: 500 for URL: http://xyz.com ...
Workaround: Try again later. Also try setting a different 'ImageFormat' parameter.
WMSServlet Removed
If the columbo.nrlssc.navy.mil server issues an error such as:
WebMapServer cannot communicate to the host columbo.nrlssc.navy.mil. The host is unknown.
This message indicates that the server it is trying to access is no longer available.
Workaround: Choose a different layer.

Wrong Scale

The columbo.nrlssc.navy.mil server often throws this error message:

This layer is not visible for this scale. The maximum valid scale is approximately X. Zoom in and try again if desired. The
scale of the image requested is Y.

X and Y represent specific values that vary from layer to layer.

Workaround: Some of the WMS sources this server accesses have map layers sensitive to the requested
scale. Zoom in (choose a smaller region of interest), or zoom out (choose a larger region of interest).
Alternatively, you can select a larger output image size to view the layer at the appropriate scale.

Problems with Geographic Limits

Some servers do not follow the guidelines of the OGC specification regarding latitude and longitude
limits.

Latlim and Lonlim in Descending Order

The OGC specification requires, and the WMS functions expect, that the limits are ascending. Some
sites, however, have descending limits. As a result, you may get this error message:

??? Error using ==> WMSMapRequest>validateLimit at 1313 Expected the elements of 'Latlim' to be in ascending order.
Workaround: To address this problem, set the Latlim and Lonlim properties of WMSLayer:

layer = wmsfind('SampleServer.com', 'SearchField', 'serverurl'); layer = wmsupdate(layer);

latlim = [min(layer.Latlim), max(layer.Latlim)];
lonlim = [min(layer.Lonlim), max(layer.Lonlim)];
layer.Latlim = [max([ -90, latlim(1)]), min([ 90, latlim(2)])]; layer.Lonlim = [max([-180, lonlim(1)]), min([180, lonlim(2)])];
[A,R] = wmsread(layer);

Update your layer before setting the limits. Otherwise, wmsread updates the limits from the server, and
you once again have descending limits.

Limits Exceed Bounds

Some servers have limits that exceed the bounds of [-180 180] for longitude and [-90 90] for latitude.
Workaround: To address this problem, follow the same procedure outlined in Latlim and Lonlim in
Descending Order on page 9-84.

Problems with Server Changing LayerName

In most cases, the updated layer returned by wmsupdate should have ServerURL and LayerName properties
that match those of the layer you enter as input. In some cases when the layer is updated from the
columbo.nrlssc.navy.mil server, the server returns a layer with a different LayerName,butthe ServerURL and
LayerTitle are the same. The layers from the columbo.nrlssc.navy.mil server have names such as 'X:Y',where X
and YareASCIInumbers. Sincethetimeofyourlastupdate,alayerhasbeen added to or removed from the
server causing a shift in the sequence of layers. Since the LayerName property is constructed with ASCII
numbers based on the layers position in this sequence, the LayerName property has changed. For layers
from the columbo.nrlssci.navy.mil server, wmsupdate matches the LayerTitle property rather than the LayerName
property.

Non-EPSG:4326 Coordinate Reference Systems

Some layers are not defined in the EPSG:4326 coordinate reference system. You cannot read these
layers with the wmsread function.

Workaround: Use the WMSMapRequest class to construct a request URL and the WebMapServer.getMap
method to read the layer. See Understanding Coordinate Reference System Codes and Retrieving Your
Map with WebMapServer.getMap for more information.

Map Not Returned

Sometimes you can connect to the WMS server, but you do not receive the map you are expecting.
Blank Map Returned
A server may return a blank map.

Workaround: You can change the scale of your map; either increase the image height and width or
change the geographic bounds. Another possibility is that your requested geographic extent lies outside
the extent of the layer, in which case you should change the extent of your request. A third possibility is
that you have the wrong image format selected; in this case, change the 'ImageFormat' parameter.

HTML File Returned

You may receive this error message:
The server returned an HTML file instead of an image file.

Workaround: Follow the directions in the error message. The following example, which uses a sample
URL, illustrates the type of error message you receive.

% Example command.
>> [A,R] = wmsread('http://www.mathworks.com?&BBOX=-180,-90,180,90... &CRS=EPSG:4326');
Sample error message:
??? Error using ==> WebMapServer>issueReadGetMapError at 832 The server returned an HTML file instead of an image
file. You may view the complete error message by issuing the command,
web('http://www.mathworks.com?&BBOX=-180,-90,180,90&CRS=EPSG:4326') or
urlread('http://www.mathworks.com?&BBOX=-180,-90,180,90...

&CRS=EPSG:4326').

XML File Returned

The server issues a very long error message, beginning with the following phrase:

An error occurred while attempting to get the map from the server. The error returned is <?xml version="1.0"
encoding="utf-8"?> ...

Workaround: This problem occurs because the server breaks with the requirements of the OGC
standard and returns the XML capabilities document rather than the requested map. Choose a different
layer or server.

Unsupported WMS Version

In rare cases, the server uses a different and unsupported WMS version. In this case, you receive an error
message such as:

The WMS version, '1.2.0', listed in layer.Details.Version is not supported by the server. The supported versions are: '1.0.0'
'1.1.0' '1.1.1' '1.3.0' .

Workaround: Choose a different server.

Other Unrecoverable Server Errors

The server issues an error indicating that no correction or workaround exists. These cases result in the
following types of error messages:
Server redirected too many times (20)
An error occurred while attempting to parse the XML capabilities document from the server.
Unexpected end of file from server
An error occurred while attempting to get the map from the server. The server returned a map containing no data.