Main Content

axesm

Create axesm-based map

collapse all in page

Syntax

axesm
axesm(Name,Value)
axesm(projid,Name,Value)

Description

The axesm function creates an axesm-based map (previously referred to as map axes) into which both vector and raster geographic data can be projected using functions such as plotm and geoshow. Properties specific to axesm-based maps can be assigned upon creation with axesm, and for an existing axesm-based map they can be queried and changed using getm and setm. Use the standard get and set methods to query and control the standard MATLAB® axes properties of an axesm-based map.

An axesm-based map is a standard MATLAB axes with different default settings for some properties and a MATLAB structure for storing projection parameters and other data. The main differences in default settings are:

  • Axes properties XGrid, YGrid, XTick, YTick are set to 'off'.

  • The hold mode is 'on'.

The map projection structure stores the properties of the axesm-based map, which, in addition to the special standard axes settings, allow Mapping Toolbox™ functions to recognize an axes or an opened FIG-file as an axesm-based map. See axesm-Based Map Properties for descriptions of the axesm-based map properties.

axesm with no input arguments, initiates the axesmui graphical user interface, which can be used to set the properties of the axesm-based map. This is detailed on the axesmui reference page.

example

axesm(Name,Value) creates an axesm-based map and modifies the appearance using name-value pairs to set properties. You can specify multiple name-value pairs. Enclose each property name in quotes. For example, 'FontSize',14 sets the font size for the map text. Properties may be specified in any order, but the MapProjection property must be included. For a full list of properties, see axesm-Based Map Properties.

axesm(projid,Name,Value) specifies which map projection to use. projid should match one of the entries in the last column displayed by the maps function. You can also find these listed in Summary and Guide to Projections.

Examples

collapse all

Create an axesm-based map for a Mercator projection, with selected latitude limits:

axesm('MapProjection','mercator','MapLatLimit',[-70 80])

All properties not explicitly addressed in the call are set to either fixed or calculated defaults. The file mercator.m defines a projection function, so the same result could have been achieved with the function.

axesm('mercator','MapLatLimit',[-70 80])

Each projection function includes default values for all properties. Any following property name/property value pairs are treated as overrides.

In either of the above examples, data displayed in the given map is in a Mercator projection. Any data falling outside the prescribed limits is not displayed.

Open Live Script

Similar to accessing and manipulating standard axes properties by using the get and set functions, you can access and manipulate the properties of axesm-based maps by using the getm and setm functions.

Use the axesm function only to create an axesm-based map. Use the setm function to modify an existing axesm-based map.

Create an axesm-based map that contains no map data. Note that you specify MapProjection ID values in lowercase.

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

Figure contains an axes object. The axes object contains an object of type patch.

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. 

getm(gca,'FLineWidth')
ans = 
2

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)

Figure contains an axes object. The axes object contains an object of type patch.

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,'Grid','on','MapProjection','robinson')

Figure contains an axes object. The axes object contains 3 objects of type patch, line.

getm(gca,'FLineWidth')
ans = 
3

getm(gca,'MapProjection')
ans = 
'robinson'

Inspect the entire set of map properties at their current settings. Note that the list of properties includes both those particular to axesm-based maps and general ones that apply to all MATLAB® axes.

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

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,'FontUnits')
FontUnits                   [ inches | centimeters | normalized | {points} | pixels ]

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

In the same way, getm displays the current value of any axes property.

getm(gca,'FontUnits')
ans = 
'points'

getm(gca,'MapProjection')
ans = 
'robinson'

getm(gca,'Frame')
ans = 
'on'

getm(gca,'FixedOrient')
ans =

     []

To identify which properties apply to a given map projection, see the reference page for that projection.

Input Arguments

collapse all

Map projection ID, specified as a string scalar or character vector. projid should match one of the entries in the last column displayed by the maps function. You can also find these listed in Summary and Guide to Projections.

Note

The names of projection files are case sensitive. The projection files included in Mapping Toolbox software use only lowercase letters and Arabic numerals.

Example: 'eqdcylin'

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: axesm('MapProjection','pcarree','Frame','on') creates a map with a Plate Carree projection, and makes the map frame visible.

Note

The properties listed here are only a subset. For a full list, see axesm-Based Map Properties.

Map projection, specified as a string scalar or character vector. MapProjection sets the projection, and hence all transformation calculations, for the map. It must be a member of the recognized projection set, which you can list by typing getm('MapProjection') or maps. For more information on projections, see the Mapping Toolbox User's Guide. Some projections set their own defaults for other properties, such as parallels and trim limits.

Geographic latitude limits of the display area, specified as a two-element vector of the form [southern_limit northern_limit]. This property can be set for many typical projections and geometries, but cannot be used with oblique projections or with globe, for example.

When applicable, the MapLatLimit property may affect the origin latitude if the Origin property is not set explicitly when calling axesm. It may also determine the value used for FLatLimit.

Geographic longitude limits of the display area, specified as a two-element vector of the form [western_limit eastern_limit]. This property can be set for many typical projections and geometries, but cannot be used with oblique projections or with globe, for example.

When applicable, the MapLonLimit property may affect the origin longitude if the Origin property is not set explicitly when calling axesm. It may also determine the value used for FLonLimit.

Tips

  • In general, after re-opening a saved figure that contains an axesm-based map, you should not attempt to modify the projection properties of that map.

  • When you create an axesm-based map with axesm and right click in the axes, a context menu appears. If you do not need the menu or it interferes with your application, you can disable it by resetting the 'ButtonDownFcn' property of the axes:

    ax = axesm('mercator');     % Right-clicking brings up context menu.
set(ax,'ButtonDownFcn',[])  % Context menu has been disabled.

  • By default, axesm does not clip graticules or labels that occur outside the boundaries of the axes. Enable clipping by setting the 'Clipping' property of these objects.

    objects = [handlem('grid'); handlem('mlabel'); handlem('plabel')];
set(objects,'Clipping','on');

Version History

Introduced before R2006a

See Also

Properties

Functions

Topics