axesm

Create map axes

Syntax

axesm

axesm(Name,Value)

axesm(projid,Name,Value)

Description

The axesm function creates a map axes into which both vector and raster geographic data can be projected using functions such as plotm and geoshow. Properties specific to map axes can be assigned upon creation with axesm, and for an existing map axes 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 a map axes.

Map axes are 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 map axes properties, which, in addition to the special standard axes settings, allow Mapping Toolbox™ functions to recognize an axes or an opened FIG-file as a map axes. See Map Axes Properties for descriptions of the map axes properties.

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

axesm(Name,Value) creates a map axes and modifies the map axes 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 axes text. Properties may be specified in any order, but the MapProjection property must be included. For a full list of properties, see Map Axes 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

Create Map Axes for Mercator Projection

Create map axes 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 axes is in a Mercator projection. Any data falling outside the prescribed limits is not displayed.

Access and Change Map Axes Properties

Similar to accessing and manipulating standard axes properties by using the get and set functions, you can access and manipulate map axes properties by using the getm and setm functions.

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

Create a map axes object that contains no map data. Note that you specify MapProjection ID values in lowercase.

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

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)

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')

getm(gca,'FLineWidth')

ans = 3

getm(gca,'MapProjection')

ans = 
'robinson'

Inspect the entire set of map axes properties at their current settings. Note that the list of properties includes both those particular to map axes 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: [0.1500 0.1500 0.1500]
        ffacecolor: 'none'
         flatlimit: [-90 90]
        flinewidth: 3
         flonlimit: [-180 180]
              grid: 'on'
         galtitude: Inf
            gcolor: [0.1500 0.1500 0.1500]
        glinestyle: ':'
        glinewidth: 0.5000
    mlineexception: []
         mlinefill: 100
        mlinelimit: []
     mlinelocation: 30
      mlinevisible: 'on'
    plineexception: []
         plinefill: 100
        plinelimit: []
     plinelocation: 15
      plinevisible: 'on'
         fontangle: 'normal'
         fontcolor: [0.1500 0.1500 0.1500]
          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

projid — Map projection ID

character vector | string scalar

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 comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: axesm('MapProjection','pcarree','Frame','on') creates a map axes 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 Map Axes Properties.

MapProjection — Map projection

character vector | string scalar

Map projection, specified as a string scalar or character vector. MapProjection sets the projection, and hence all transformation calculations, for the map axes object. 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.

MapLatLimit — Geographic latitude limits of the display area

two-element vector

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.

MapLonLimit — Geographic longitude limits of the display area

two-element vector

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 a map axes, you should not attempt to modify the projection properties of that map axes.

• When you create a map axes 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');