Documentation Center

  • Trial Software
  • Product Updates

Axes for Drawing Maps

What Is a Map Axes?

When you create a map, you can use one of the Mapping Toolbox™ built-in user interfaces (UIs), or you can build the graphic with MATLAB® and Mapping Toolbox functions. Many MATLAB graphics are built using the axes function:

axes
axes('PropertyName',PropertyValue,...)
axes(h)
h = axes(...)

Mapping Toolbox functions include an extended version of axes, called axesm, that includes information about the current coordinate system (map projection), as well as data to define the map grid and its labeling, the map frame and its limits, and other properties. Its syntax is similar to that of axes:

axesm
axesm(PropertyName,PropertyValue,...)
axesm(ProjectionFcn,PropertyName,PropertyValue,...)

The axesm function without arguments brings up a UI that lists all supported projections and assists in defining their parameters. You can also summon this UI with the axesmui function once you have created a map axes.

You can also list all the names, classes, and ID strings of Mapping Toolbox map projections with the maps function.

Axes created with axesm share all properties associated with regular axes, and have additional properties related to projections, scale, and positioning in geographic coordinates. See the axes and axesm reference pages for lists of properties.

You can place many types of objects in a map axes, such as lines, patches, markers, scale rulers, north arrows, grids, and text. You can use the handlem function and its associated UI to list these objects and obtain handles to them. See the handlem reference page for a list of the objects that can occupy a map axes and how to query for them.

Map axes objects created by axesm contain projection information in a structure. For an example of what these properties are, type

h = axesm('MapProjection','mercator')

and then use the getm function to retrieve all the map axes properties:

p = getm(h)

For complete descriptions of all map axes properties, see the axesm reference page. For more information on the use of axesmui, refer to the axesmui reference page.

Using axesm

The figure window created using axesm contains the same set of tools and menus as any MATLAB figure, and is by default blank, even if there is map data in your workspace. You can toggle certain properties, such as grids, frames, and axis labels, by right-clicking in the figure window to obtain a pop-up menu.

You can define multiple independent figures containing map axes, but only one can be active at any one time. Return handles for them when you create them to allow them to be referenced when they are no longer current. Use axes(handle) to activate an existing map axes object.

Accessing and Manipulating Map Axes Properties

Just as the properties of the underlying standard axes can be accessed and manipulated using the MATLAB functions set and get, map axes properties can also be accessed and manipulated using the functions setm and getm.

    Note   Use the axesm function only to create a map axes object. Use the setm function to modify existing map axes.

  1. As an example, create a map axes object containing no map data:

    axesm('MapProjection','miller','Frame','on')

    Note that you specify MapProjection string values in lowercase. At this point you can begin to customize the map. For example, you might decide to make the frame lines bordering the map thicker. First, you need to identify the current line width of the frame, which you do by querying the current axes, identified as gca.

  2. Access the current FLineWidth property value by typing

    getm(gca,'FLineWidth')
    ans =
    	2
  3. Now reset the line width to four points. The default fontunits value for axes is points. You can set fontunits to be points, normalized, inches, centimeters, or pixels.

    setm(gca,'FLineWidth',4)
  4. You can set any number of properties simultaneously with setm. Continue by reducing the line width, changing the projection to equidistant cylindrical, and verify the changes:

    setm(gca,'FLineWidth',3,'MapProjection','eqdcylin')
    
    getm(gca,'FLineWidth')
    ans =
    	3
    getm(gca,'MapProjection')
    ans =
    eqdcylin
  5. To inspect the entire set of map axes properties at their current settings, use the following command:

    getm(gca)
    ans = 
         mapprojection: 'eqdcylin'
                  zone: []
            angleunits: 'degrees'
                aspect: 'normal'
          falseeasting: []
         falsenorthing: []
           fixedorient: []
                 geoid: [1 0]
           maplatlimit: [-90 90]
           maplonlimit: [-180 180]
          mapparallels: 30
            nparallels: 1
                origin: [0 0 0]
           scalefactor: []
               trimlat: [-90 90]
               trimlon: [-180 180]
                 frame: 'on'
                 ffill: 100
            fedgecolor: [0 0 0]
            ffacecolor: 'none'
             flatlimit: [-90 90]
            flinewidth: 3
             flonlimit: [-180 180]
                  grid: 'off'
             galtitude: Inf
                gcolor: [0 0 0]
            glinestyle: ':'
            glinewidth: 0.5000
        mlineexception: []
             mlinefill: 100
            mlinelimit: []
         mlinelocation: 30
          mlinevisible: 'on'
        plineexception: []
             plinefill: 100
            plinelimit: []
         plinelocation: 15
          plinevisible: 'on'
             fontangle: 'normal'
             fontcolor: [0 0 0]
              fontname: 'helvetica'
              fontsize: 9
             fontunits: 'points'
            fontweight: 'normal'
           labelformat: 'compass'
            labelunits: 'degrees'
         meridianlabel: 'off'
        mlabellocation: 30
        mlabelparallel: 90
           mlabelround: 0
         parallellabel: 'off'
        plabellocation: 15
        plabelmeridian: -180
           plabelround: 0

    Note that the list of properties includes both those particular to map axes and general ones that apply to all MATLAB axes.

  6. Similarly, use the setm function alone to display the set of properties, their enumerated values, and defaults:

    setm(gca)
    AngleUnits                  [ {degrees} | radians ]                 
    Aspect                      [ {normal} | transverse ]               
    FalseEasting                                                        
    FalseNorthing                                                       
    FixedOrient                 FixedOrient is a read-only property     
    Geoid                                                               
    MapLatLimit                                                         
    MapLonLimit                                                         
    MapParallels                                                        
    MapProjection                                                       
    NParallels                  NParallels is a read-only property      
    Origin                                                              
    ScaleFactor                                                         
    TrimLat                     TrimLat is a read-only property         
    TrimLon                     TrimLon is a read-only property         
    Zone                                                                
    Frame                       [ on | {off} ]                          
    FEdgeColor                                                          
    FFaceColor                                                          
    FFill                                                               
    FLatLimit                                                           
    FLineWidth                                                          
    FLonLimit                                                           
    Grid                        [ on | {off} ]                          
    GAltitude                                                           
    GColor                                                              
    GLineStyle                  [ - | -- | -. | {:} ]                   
    GLineWidth                                                          
    MLineException                                                      
    MLineFill                                                           
    MLineLimit                                                          
    MLineLocation                                                       
    MLineVisible                [ {on} | off ]                          
    PLineException                                                      
    PLineFill                                                           
    PLineLimit                                                          
    PLineLocation                                                       
    PLineVisible                [ {on} | off ]                          
    FontAngle                   [ {normal} | italic | oblique ]         
    FontColor                                                           
    FontName                                                            
    FontSize                                                            
    FontUnits                  [ inches | centimeters | normalized | 
    {points} | pixels ]
    FontWeight                  [ {normal} | bold ]                     
    LabelFormat                 [ {compass} | signed | none ]           
    LabelRotation               [ on | {off} ]                          
    LabelUnits                  [ {degrees} | radians ]                 
    MeridianLabel               [ on | {off} ]                          
    MLabelLocation                                                      
    MLabelParallel                                                      
    MLabelRound                                                         
    ParallelLabel               [ on | {off} ]                          
    PLabelLocation                                                      
    PLabelMeridian                                                      
    PLabelRound 

    Many, but not all, property choices and defaults can also be displayed individually:

    setm(gca,'AngleUnits')
    AngleUnits                  [ {degrees} | radians ]
    setm(gca,'MapProjection')
    An axes's "MapProjection" property does not have a fixed set
    	of property values.
    setm(gca,'Frame')
    Frame                       [ on | {off} ]
    setm(gca,'FixedOrient')
    FixedOrient                 FixedOrient is a read-only property
  7. In the same way, getm displays the current value of any axes property:

    getm(gca,'AngleUnits')
    ans =
    degrees
    
    getm(gca,'MapProjection')
    ans =
    eqdconic
    
    getm(gca,'Frame')
    ans =
    on
    
    getm(gca,'FixedOrient')
    ans =
         []

For a complete listing and descriptions of map axes properties, see the reference page for axesm. To identify what properties apply to a given map projection, see the reference page for that projection.

Using the Map Limit Properties

In many common situations, the map limit properties, MapLatLimit and MapLonLimit, provide a convenient way of specifying your map projection origin or frame limits. Note that these properties are intentionally redundant; you can always avoid them if you wish and instead use the Origin, FLatLimit, and FLonLimit properties to set up your map. When they're applicable, however, you'll probably find that it's easier and more intuitive to set MapLatLimit and MapLonLimit, especially when creating a new map axes with axesm.

Example 1: Robinson Projection

Often, you'll want to create a map using a cylindrical projection (such as Mercator, Miller, or Plate Carée) or a pseudo-cylindrical projection (such as Mollweide or Robinson) showing all or most of the Earth, with the Equator running as a straight horizontal line across the center of the map. Your map will be bounded by a geographic quadrangle, and the projection origin will be located on the Equator and centered between the longitude limits. In this case, you can easily control the north-south extent of the quadrangle with the MapLatLimit property and the east-west extent with the MapLonLimit property. axesm will automatically set the Origin and assign consistent values for the frame limits (FLatLimit and FLonLimit).

For example, here's a way to create a map with a Robinson projection showing the western Pacific Ocean and surrounding areas:

latlim = [-80 80];
lonlim = [100 -120];
figure('Color','white')
axesm('robinson','MapLatLimit',latlim,'MapLonLimit',lonlim, ...
   'Frame','on','Grid','on','MeridianLabel','on', ...
   'ParallelLabel','on')
axis off
setm(gca,'MLabelLocation',60)
coast = load('coast.mat');
plotm(coast.lat,coast.long)

    Note:   The western limit (100 degrees E, in this case) must always precede the eastern limit (-120 degrees E, or 120 degrees W), even if the second number in the longitude-limit vector is smaller than the first.

Note that the map spans 140 degrees from west to east:

wrapTo360(diff(lonlim))
ans =
    140

axesm automatically sets the Origin and frame limits based on the values you selected for MapLatLim and MapLonLim. You can check the Origin and frame limits by using getm.

origin = getm(gca,'Origin');
flatlim = getm(gca,'FLatLimit');
flonlim = getm(gca,'FLonLimit');

The origin longitude should be located halfway between the longitude limits of 100 E and 120 W. Adding half of 140 to the western limit gives 100 + 70 = 170 degrees E. This should, and does, equal the second element of the origin vector:

 origin(2)
 ans =
    170

The frame is centered on this longitude with a half-width of 70 degrees:

flonlim
flonlim =
    -70    70

The story with latitudes is somewhat simpler; the origin latitude is on the Equator:

 origin(1)
 ans =
      0

and therefore the latitude limits of the frame equal the value supplied for MapLatLimit:

 flatlim
 flatlim =
    -80    80

Of course, after you've called axesm, you may look at your map and decide that you're not completely satisfied with your initial choice of map limits. Suppose that you decide it would be better to shift the western longitude limit to 40 degrees E in order to include a little more of Asia. You can do this by calling setm with a new MapLonLimit value:

 setm(gca,'MapLonLimit',[40 -120])

but the asymmetric appearance of the resulting map may surprise you.

You might have expected to see a symmetric map just like the one you would get if you replaced lonlim in the earlier call to axesm with [40 -120], but that's not what happened. This apparent inconsistency turns out to be an important consequence of the fact that MapLatLimit and MapLonLimit are redundant properties.

Before you call axesm, none of the map axes properties have been set yet because the map axes doesn't exist. Therefore, there's no value yet for the Origin property, and there's no problem in setting the longitude origin halfway between the longitudes specified in the MapLonLimit vector. But once axesm has been called, your map axes does have a projection origin. Since the projection origin is such a fundamental property, it takes precedence over the MapLonLimit property.

Therefore, if you try to reset your longitude limits without also resetting the origin, setm will maintain your current origin. So, the center of the map limits moved west, but the origin stayed fixed. This combination caused the asymmetry.

To avoid this asymmetry, you can repeat the operations shown above to figure out that the new central longitude must be at 140 degrees E and add this in the call to setm like this:

setm(gca,'MapLonLimit',[40 -120],'Origin',[0 140])

but you don't actually need to go through such trouble.

Instead, you can just tell setm that you'd like to calculate a new origin by providing an empty array instead of a new value for the Origin property.

 setm(gca,'MapLonLimit',[40 -120],'Origin',[])

Notice the symmetry of the resulting map frame. Usually this is the easiest thing to do.

Example 2: Cylindrical Projection

Load the "coast" MAT-file.

coast = load('coast');

Construct a Mercator projection covering the full range of permissible latitudes with longitudes covering a full 360 degrees starting at 60 West.

figure('Color','w')
axesm('mercator','MapLatLimit',[-90 90],'MapLonLimit',[-60 300])
axis off; framem on; gridm on; mlabel on; plabel on;
setm(gca,'MLabelLocation',60)
geoshow(coast.lat,coast.long,'DisplayType','polygon')

The call to axesm above is equivalent to:

axesm('mercator','Origin',[0 120 0], ...
     'FLatLimit',[-90 90],'FlonLimit',[-180 180])

You can verify this by checking these properties:

getm(gca,'Origin')
getm(gca,'FLatLimit')
getm(gca,'FLonLimit')
ans =
             0        120.00             0
ans =
        -86.00         86.00
ans =
       -180.00        180.00

Note that the map and frame limits are clamped to the range of [-86 86] imposed by the read-only TrimLat property.

getm(gca,'MapLatLimit')
getm(gca,'FLatLimit')
getm(gca,'TrimLat')
ans =
        -86.00         86.00
ans =
        -86.00         86.00
ans =
        -86.00         86.00

Example 3: Conic Projection

Create a map of the standard version of the Lambert Conformal Conic projection covering latitudes 20 North to 75 North and longitudes covering 90 degrees starting at 30 degrees West.

coast = load('coast');
figure('Color','w')
axesm('lambertstd','MapLatLimit',[20 75],'MapLonLimit',[-30 60])
axis off; framem on; gridm on; mlabel on; plabel on;
geoshow(coast.lat, coast.long, 'DisplayType', 'polygon')

The call to axesm above is equivalent to:

axesm('lambertstd','Origin',[0 15 0],'FLatLimit',[20 75], ...
		'FlonLimit',[-45 45])

Example 4: Southern Hemisphere Conic Projection

"Reflect" the preceding map into the Southern Hemisphere. Override the default standard parallels as well as change MapLatLimit.

coast = load('coast');
figure('Color','w')
axesm('lambertstd','MapParallels',[-75 -15], ...
		'MapLatLimit',[-75 -20],'MapLonLimit',[-30 60])
axis off; framem on; gridm on; mlabel on; plabel on;
geoshow(coast.lat,coast.long,'DisplayType','polygon')

Example 5: North-Polar Azimuthal Projection

Construct a North-polar Equal-Area Azimuthal projection map extending from the Equator to the pole and centered by default on longitude 0.

coast = load('coast');
figure('Color','w')
axesm('eqaazim','MapLatLimit',[0 90])
axis off; framem on; gridm on; mlabel on; plabel on;
setm(gca,'MLabelParallel',0)
geoshow(coast.lat,coast.long,'DisplayType','polygon')

The call to axesm above is equivalent to:

axesm('eqaazim','MLabelParallel',0,'Origin',[90 0 0], ...
		'FLatLimit',[-Inf 90])

Example 6: South-Polar Azimuthal Projection

Create a South-polar Stereographic Azimuthal projection map extending from the South Pole to 20 degrees S, centered on longitude 150 degrees West. Include a value for the Origin property in order to control the central meridian.

coast = load('coast');
figure('Color','w')
axesm('stereo','Origin',[-90 -150],'MapLatLimit',[-90 -20])
axis off; framem on; gridm on; mlabel on; plabel on;
setm(gca,'MLabelParallel',-20)
geoshow(coast.lat,coast.long,'DisplayType','polygon')

The call to axesm above is equivalent to:

axesm('stereo','Origin',[-90 -150 0],'FLatLimit',[-Inf 70])

Example 7: Equatorial Azimuthal Projection

Create a map of an Equidistant Azimuthal projection with the origin on the Equator, covering from 10 E to 170 E. The origin longitude falls at the center of this range (90 E), and the map reaches north and south to within 10 degrees of each pole.

coast = load('coast');
figure('Color','w')
axesm('eqdazim','FLatLimit',[],'MapLonLimit',[10 170])
axis off; framem on; gridm on; mlabel on; plabel on;
setm(gca,'MLabelParallel',0,'PLabelMeridian',60)
geoshow(coast.lat,coast.long,'DisplayType','polygon')

The call to axesm above is equivalent to:

 axesm('eqaazim','Origin',[0 90 0],'FLatLimit',[-Inf 80])

Example 8: General Azimuthal Projection

Construct an Orthographic projection map with the origin centered near Paris. You can't use MapLatLimit or MapLonLimit in this case.

coast = load('coast');
originLat = dm2degrees([48 48]);
originLon = dm2degrees([ 2 20]);

figure('Color','w')
axesm('ortho','Origin',[originLat originLon])
axis off; framem on; gridm on; mlabel on; plabel on;
setm(gca,'MLabelParallel',30,'PLabelMeridian',-30)
geoshow(coast.lat,coast.long,'DisplayType','polygon')

Example 9: Oblique Mercator Projection

Create a map with a long, narrow, oblique Mercator projection showing the area 10 degrees to either side of the great-circle flight path from Tokyo to New York. You can't use MapLatLimit or MapLonLimit in this case, either.

coast = load('coast');
latTokyo = dm2degrees([ 35 40]);
lonTokyo = dm2degrees([139 45]);

latNewYork = dm2degrees([ 40 47]);
lonNewYork = dm2degrees([-73 58]);

[dist,az] = distance(latTokyo,lonTokyo,latNewYork,lonNewYork);
[midLat,midLon] = reckon(latTokyo,lonTokyo,dist/2,az);
midAz = azimuth(midLat,midLon,latNewYork,lonNewYork);

buf = [-10 10];

figure('Color','w')
axesm('mercator','Origin',[midLat midLon 90-midAz], ...
    'FLatLimit',buf,'FLonLimit',[-dist/2 dist/2] + buf)
axis off; framem on; gridm on; tightmap
geoshow(coast.lat,coast.long,'DisplayType','polygon')
plotm([latTokyo latNewYork],[lonTokyo lonNewYork],'r-')

General Applicability of Map Limit Properties

As the preceding examples illustrate, most typically you use the MapLatLimit and MapLonLimit properties to set up a map axes with a non-oblique, non-azimuthal projection, with its origin on the Equator. (Most of the projections included in the Mapping Toolbox fall into this category; e.g., cylindrical, pseudo-cylindrical, conic, or modified azimuthal.) In addition, even with a non-zero origin latitude (origin off the Equator), you can use the MapLatLimit and MapLonLimit properties with projections that are implemented directly rather than via rotations of the sphere (e.g., tranmerc, utm, lambertstd, cassinistd, eqaconicstd, eqdconicstd, and polyconicstd). This list includes the projections used most frequently for large-scale maps, such as U.S. Geological Survey topographic quadrangle maps. Finally, when the origin is located at a pole or on the Equator, you can use the map limit properties with any azimuthal projection (e.g., stereo, ortho, breusing, eqaazim, eqdazim, gnomonic, or vperspec).

On the other hand, you should avoid the map limit properties, working instead with the Origin, FLatLimit, and FLonLimit properties, when:

  • You want your map frame to be positioned asymmetrically with respect to the origin longitude.

  • You want to use an oblique aspect (that is, assign a non-zero rotation angle to the third element of the "orientation vector" supplied as the Origin property value).

  • You want to change your projection's default aspect (normal vs. transverse).

  • You want to use a nonzero origin latitude, except in one of the special cases noted above.

  • You are using one of the following projections:

    • globe — No need for map limits; always covers entire planet

    • cassini — Always in a transverse aspect

    • wetch — Always in a transverse aspect

    • bries — Always in an oblique aspect

There's no need to supply a value for the MapLatLimit property if you've already supplied one for the Origin and FLatLimit properties. In fact, if you supply all three when calling either axesm or setm, the FLatLimit value will be ignored. Likewise, if you supply values for Origin, FLonLimit, and MapLonLimit, the FLonLimit value will be ignored.

If you do supply a value for either MapLatLimit or MapLonLimit in one of the situations listed above, axesm or setm will ignore it and issue a warning. For example,

axesm('lambert','Origin',[40 0],'MapLatLimit',[20 70])

generates the warning message:

Ignoring value of MapLatLimit due to use of nonzero origin
 latitude with the lambert projection.

Using the Map Limit Properties with setm

As shown in the earlier example in which the longitude limits of a map in the Robinson projection are changed via setm, it's important to understand that MapLatLimit and MapLonLimit are extra, redundant properties that are coupled to the Origin, FLatLimit, and FLonLimit properties. On the other hand, it's not too difficult to know how to update your map axes if you keep in mind the following:

  • The Origin property takes precedence. It is set (implicitly, if not explicitly) every time you call axesm and you cannot change it just by changing the map limits. (Note that when creating a new map axes from scratch, the map limits are used to help set the origin if it is not explicitly specified.)

  • MapLatLimit takes precedence over FLatLimit if both are provided in the same call to axesm or setm, but changing either one alone affects the other.

  • MapLonLimit and FLonLimit have a similar relationship.

As shown in the example, the precedence of Origin means that if you want to reset your map limits with setm and have setm also determine a new origin, you must set Origin to [] in the same call. For example,

setm(gca,'Origin',[],'MapLatLimit',newMapLatlim,...
   'MapLonLimit',newMapLonlim)

On the other hand, a call like this will automatically update the values of FLatLimit and FLonLimit. Similarly, a call like:

setm(gca,'FLatLimit',newFrameLatlim,'FLonLimit',newFrameLonlim)

will update the values of MapLatLimit and MapLonLimit.

Finally, you probably don't want to try the following:

setm(gca,'Origin',[],'FLonLimit',newFrameLonlim)

because the value of FLonLimit (unlike MapLonLimit) will not affect Origin, which will merely change to a projection-dependent default value (typically [0 0 0]).

Switching Between Projections

Once a map axes object has been created with axesm, whether map data is displayed or not, it is possible to change the current projection as well as many of its parameters. You can use setm or the maptool UI to reset the projection. The rest of this section describes the considerations and parameters involved in switching projections in a map axes. Additional details are given for doing this with the geoshow function in Changing Map Projections when Using geoshow.

When you switch from one projection to another, setm clears out settings that were specific to the earlier projection, updates the map frame and graticule, and generally keeps the map covering the same part of the world—even when switching between azimuthal and non-azimuthal projections. But in some cases, you might need to further adjust the map axes properties to achieve proper appearance. Settings that are suitable for one projection might not be appropriate for another. Most often, you'll need to update the positioning of your meridian and parallel labels.

Moving Meridian and Parallel Labels

  1. Create a Mercator projection with meridian and parallel labels.

    axesm mercator
    framem on; gridm on; mlabel on; plabel on
    setm(gca,'LabelFormat','signed')
    axis off

  2. Get the default map and frame latitude limits for the Mercator projection.

    [getm(gca,'MapLatLimit'); getm(gca,'FLatLimit')]
    ans =
    -86    86
    -86    86

    Both the frame and map latitude limits are set to 86º north and south for the Mercator projection to maintain a safe distance from the singularity at the poles.

  3. Now switch the projection to an orthographic azimuthal.

    setm(gca,'MapProjection','ortho')
    
  4. Manually specify new locations for the meridian and parallel labels. (See Labeling Grids.)

    setm(gca,'MLabelParallel',0,'PLabelMeridian',-90, ...
       'PLabelMeridian',-30)

Resetting Frame Limits

When switching from one projection to another, you may need to reset your origin and frame limits, especially if you are mapping a small portion of the Earth.

  1. Construct an empty map axes for a region of the U.S. in the Lambert Conformal Conic projection (the default projection for usamap).

    latlim = [32 42];
    lonlim = [-125 -111];
    h = usamap(latlim, lonlim);
    
  2. Read in the 'usastatehi' shapefile and return a subset of the shapefile contents, as defined by the latitude and longitude limits, in a structure called states.

    states = shaperead('usastatehi', 'UseGeoCoords', true, ...
       'BoundingBox', [lonlim', latlim']);
    
  3. Save the latitude and longitude data from the structure in the vectors lat and lon.

    lat = [states.Lat];
    lon = [states.Lon];
    
  4. Project patch objects on the map axes.

    patchm(lat, lon, [0.5 0.5 1])
    

  5. Change the projection to Lambert Equal Area Azimuthal and reset the origin and frame limits.

    setm(gca,'MapProjection','eqaazim','Origin',[37 -118], ...
       'FLatLimit',[-Inf 6]) 
    setm(gca,'mlinelocation',2,'plinelocation',2)
    tightmap

Projected and Unprojected Graphic Objects

Many Mapping Toolbox cartographic functions project features on a map axes based on their designated latitude-longitude positions. The latitudes and longitudes are mathematically transformed to x and y positions using the formulas for the current map projection. If the map projection or its parameters change, objects on a map axes can be automatically reprojected to update the map display accordingly, but only under the circumstances detailed in the following sections.

Auto-Reprojection of Mapped Objects and Its Limitations

Using the setm function, you can change the current map projection on the fly if the map display was created in a way that permits reprojection. Note that map displays can contain objects that cannot be reprojected, and may need to be explicitly deleted and redrawn. Automatic reprojection will take place when you use setm to modify the MapProjection property, or any other map axes property from the following list:

  • AngleUnits

  • Aspect

  • FalseEasting

  • FalseNorthing

  • FLatLimit

  • FLonLimit

  • Geoid

  • MapLatLimit

  • MapLonLimit

  • MapParallels

  • Origin

  • ScaleFactor

  • TrimLat

  • TrimLon

  • Zone

Auto-reprojection takes place for objects created with any of the following Mapping Toolbox functions:

In general, objects created with geoshow or with a combination of calls to mfwdtran followed by ordinary MATLAB graphics functions, such as line, patch, or surface, are not automatically reprojected. You should delete such objects whenever you change one or more of the map axes properties listed above, and then redisplay them.

The above Mapping Toolbox functions are analogous to standard MATLAB graphics functions having the same name, less the trailing m. You can use both types of functions to plot data on a map axes, as long as you are aware that the standard MATLAB graphics functions do not apply map projection transformations, and therefore require you to specify positions in map x-y space.

If you have preprojected vector or raster map data or read such data from files, you can display it with mapshow, mapview, or standard MATLAB graphics functions, such as plot or mesh. If its projection is known and is included in the Mapping Toolbox projection libraries, you can use its parameters to project geodata in geographic coordinates to display it in the same axes.

There are four common use cases for changing a map projection in a map axes with setm or for reprojecting map data plotted on a regular MATLAB axes:

Mapping Use CaseType of AxesReprojection Behavior
Plot geographic (latitude-longitude) vector coordinate data or data grid using a Mapping Toolbox function from releases prior to Version 2 (e.g., plotm)Map axesAutomatic reprojection
Plot geographic vector data with geoshowMap axesNo automatic reprojection; delete graphics objects prior to changing the projection and redraw them afterwards.
Plot data grids, images, and contours with geographic coordinates with geoshowMap axesAutomatic reprojection; this behavior could change in a future release
Plot projected (x-y) vector or raster map data with mapshow or with a MATLAB graphics function (e.g., line, contour, or surf)Regular axesManual reprojection (reproject coordinates with minvtran /mfwdtran or projinv/projfwd); delete graphics objects prior to changing the projection and redraw them afterwards.

You can use handlem to help identify which objects to delete when manual deletion is necessary. See Determining and Manipulating Object Names for an example of its use. The following section describes reprojection behavior in more detail and illustrates some of these cases.

Changing Map Projections when Using geoshow

You can display latitude-longitude vector and raster geodata using the geoshow function (use mapshow to display preprojected coordinates and grids). When you use geoshow to display maps on a map axes, the data are projected according to the map projection assigned when axesm, worldmap, or usamap created the map axes (e.g., axesm('mapprojection','mercator')).

You can also use geoshow to display latitude-longitude data on a regular axes (created by the axes function, for example). When you do this, the latitude-longitude data are displayed using a Plate Carrée Projection, which linearly maps longitude to x and latitude to y.

If you are using geoshow with a map axes and want to change the map projection after you have displayed data in geographic coordinates, do the following, depending on whether the data are raster or vector:

Raster Data.  Change the projection using setm. For example,

load geoid
figure; axesm mercator
geoshow(geoid,geoidrefvec,'DisplayType','texturemap')

setm(gca,'mapprojection','mollweid')

Vector Data.  Obtain handles to the line or patch graphic objects, delete the objects from the axes, change the projection using setm, and replot the vector data using geoshow:

figure; axesm miller
h = geoshow('landareas.shp')

delete(h)
setm(gca,'mapprojection','ortho')
geoshow('landareas.shp')

In the above example, h is a handle to an hggroup object, which geoshow constructs when plotting point, line, and polygon data.

If you need to change projections when displaying both raster and vector geodata, you can combine these techniques; removing the vector graphic objects does not affect raster data already displayed.

Placing Geographic and Nongeographic Objects in a Map Axes

Here is an example of how the two types of functions can interact when you place text objects:

  1. Make a Miller map axes with a latitude-longitude grid:

    axesm miller; framem on; gridm on; mlabel on; plabel on;
    showaxes; grid off;

    These function calls create a map axes object, a map frame enclosing the region of interest, and geographic grid lines. The x-y axes, which are normally hidden, are displayed, and the axes x-y grid is turned off. The Mapping Toolbox function gridm constructs lines to illustrate the latitude-longitude grid, unlike the MATLAB function grid, which draws an x-y grid for the underlying projected map coordinates. Depending on the type of projection, a latitiude-longitude grid (or graticule) can contain curves while a MATLAB grid never does. For more information about graticules, see The Map Grid.

  2. Now place a standard MATLAB text object and a mapped text object, using the two separate coordinate systems:

    text(-2,-1,'Standard text object at x = -2, y = -1')
    textm(70,-150,'Mapped text object at lat = 70, lon = -150')

    In the figure, shown below, a standard text object is placed at x=-2 and y=-1, while a mapped text object is placed at (70ºN,150ºW) in the Miller projection.

  3. Now change the projection to sinusoidal. The standard text object remains at the same Cartesian position, which alters its latitude-longitude position. The mapped text object remains at the same geographic location, so its x-y position is altered. Also, the frame and grid lines reflect the new map projection:

    setm(gca,'MapProjection','sinusoid')
    showaxes; grid off; mlabel off

Similarly, vector and matrix data can be displayed using either mapping or standard functions (e.g., plot/plotm, surf/surfm). See Displaying Vector Data with Mapping Toolbox Functions for information on plotting vector geodata, and Displaying Data Grids for information on plotting raster geodata.

Was this topic helpful?