axesm

Define map axes and set map properties

Syntax

axesm
axesm(PropertyName,PropertyValue,...)
axesm(projid,PropertyName,PropertyValue,...)

Description

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(PropertyName,PropertyValue,...) creates a map axes using the specified properties. Properties may be specified in any order, but the MapProjection property must be included.

axesm(projid,PropertyName,PropertyValue,...) uses the string projid to designate 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 a list of these strings in the User's Guide section Summary and Guide to Projections.

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.

Axes Definition

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 described here, allow Mapping Toolbox™ functions to recognize an axes or an opened FIG-file as a map axes. See Map Axes Object Properties, below, for descriptions of the map axes properties.

    Note:   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.

    Note:   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. 

Examples

Create map axes for a Mercator projection, with selected latitude limits:

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

In the preceding example, 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.

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

Map Axes Object Properties

Properties That Control the Map Projection

AngleUnits

{degrees} | radians

Angular unit of measure — Controls the units of measure used for angles (including latitudes and longitudes) in the map axes. All input data are assumed to be in the given units; 'degrees' is the default. For more information on angle units, see Working with Angles: Units and Representations in the Mapping Toolbox User's Guide.

Aspect

{normal} | transverse

Display aspect — Controls the orientation of the base projection of the map. When the aspect is 'normal' (the default), north in the base projection is up. In a transverse aspect, north is to the right. A cylindrical projection of the whole world would look like a landscape display under a 'normal' aspect, and like a portrait under a 'transverse' aspect. Note that this property is not the same as projection aspect, which is controlled by the Origin property vector discussed later.

FalseEasting

scalar {0}

Coordinate shift for projection calculations — Modifies the position of the map within the axes. The projected coordinates are shifted in the x-direction by the amount of FalseEasting. The FalseEasting is in the same units as the projected coordinates, that is, the units of the first element of the Geoid map axes property. False eastings and northings are sometimes used to ensure nonnegative values of the projected coordinates. For example, the Universal Transverse Mercator uses a false easting of 500,000 meters.

FalseNorthing

scalar {0}

Coordinate shift for projection calculations — Modifies the position of the map within the axes. The projected coordinates are shifted in the y-direction by the amount of FalseNorthing. The FalseNorthing is in the same units as the projected coordinates, that is, the units of the first element of the Geoid map axes property. False eastings and northings are sometimes used to ensure nonnegative values of the projected coordinates. For example, the Universal Transverse Mercator uses a false northing of 0 in the northern hemisphere and 10,000,000 meters in the southern.

FixedOrient

scalar {[]} (read-only)

Projection-based orientation — This read-only property fixes the orientation of certain projections (such as the Cassini and Wetch). When empty, which is true for most projections, the user can alter the orientation of the projection using the third element of the Origin property. When fixed, the fixed orientation is always used.

Geoid

[semimajor_axis eccentricity] or spheroid object

Reference spheroid definition — The spheroid (ellipsoid or sphere) for calculating the projections of any displayed map objects. It can be an referenceSphere, referenceEllipsoid, or oblateSpheroid object, or a vector of the form [semimajor_axis eccentricity]. The default value is an ellipsoid vector representing the unit sphere: [1 0].

MapLatLimit

[southern_limit northern_limit]

Geographic latitude limits of the display area — Expressed 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. See Accessing and Manipulating Map Axes Properties for a more complete description of the applicability of MapLatLimit and its interaction with the origin, frame limits, and other properties.

MapLonLimit

[western_limit eastern_limit]

Geographic longitude limits of the display area — Expressed 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. See Accessing and Manipulating Map Axes Properties for a more complete description of the applicability of MapLonLimit and its interaction with the origin, frame limits, and other properties.

MapParallels

[lat] | [lat1 lat2]

Projection standard parallels — Sets the standard parallels of projection. It can be an empty, one-, or two-element vector, depending upon the projection. The elements are in the same units as the map axes AngleUnits. Many projections have specific, defining standard parallels. When a map axes object is based upon one of these projections, the parallels are set to the appropriate defaults. For conic projections, the default standard parallels are set to 15ºN and 75ºN, which biases the projection toward the northern hemisphere.

For projections with one defined standard parallel, setting the parallels to an empty vector forces recalculation of the parallel to the middle of the map latitude limits. For projections requiring two standard parallels, setting the parallels to an empty vector forces recalculation of the parallels to one-sixth the distance from the latitude limits (e.g., if the map latitude limits correspond to the northern hemisphere [0 90], the standard parallels for a conic projection are set to [15 75]). For azimuthal projections, the MapParallels property always contains an empty vector and cannot be altered.

See the Mapping Toolbox User's Guide for more information on standard parallels.

MapProjection

projection_name {no default}

Map projection — Sets the projection, and hence all transformation calculations, for the map axes object. It is required in the creation of map axes. 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.

Origin

[latitude longitude orientation]

Origin and orientation for projection calculations — Sets the map origin for all projection calculations. The latitude, longitude, and orientation should be in the map axes AngleUnits. Latitude and longitude refer to the coordinates of the map origin; orientation refers to an angle of skewness or rotation about the axis running through the origin point and the center of the earth. The default origin is 0º latitude and a longitude centered between the map longitude limits. If a scalar is entered, it is assumed to refer to the longitude; if a two-element vector is entered, the default orientation is 0º, a normal projection. If an empty origin vector is entered, the origin is centered on the map longitude limits. For more information on the origin, see the Mapping Toolbox User's Guide.

Parallels

0, 1, or 2 (read-only, projection-dependent)

Number of standard parallels — This read-only property contains the number of standard parallels associated with the projection. See the Mapping Toolbox User's Guide for more information on standard parallels.

ScaleFactor

scalar {1}

Scale factor for projection calculations — Modifies the size of the map in projected coordinates. The geographic coordinates are transformed to Cartesian coordinates by the map projection equations and multiplied by the scale factor. Scale factors are sometimes used to minimize the scale distortion in a map projection. For example, the Universal Transverse Mercator uses a scale factor of 0.996 to shift the line of zero scale distortion to two lines on either side of the central meridian.

Zone

ZoneSpec | {[] or 31N}

Zone for certain projections — Specifies the zone for certain projections. A zone is a region on the globe that has a special set of projection parameters. In the Universal Transverse Mercator Projection, the world is divided into quadrangles that are generally 6 degrees wide and 8 degrees tall. The number in the zone designation refers to the longitude range, while the letter refers to the latitude range. Most projections use the same parameters for the entire globe, and do not require a zone.

Properties That Control the Frame

Frame

on | {off}

Frame visibility — Controls the visibility of the display frame box. When the frame is 'off' (the default), the frame is not displayed. When the frame is 'on', an enclosing frame is visible. The frame is a patch that is plotted as the lowest layer of displayed map objects. Regardless of its display status, the frame always operates in terms of trimming map data.

FFill

scalar plotting point density {100}

Frame plotting precision — Sets the number of points to be used in plotting the frame for display. The default value is 100, which for a rectangular frame results in a plot with 100 points for each side, or a total of 400 points. The number of points required for a reasonable display varies with the projection. Cylindrical projections such as the Miller require very few. Projections resulting in more complex frames, such as the Werner, look better with higher densities. The default value is generally sufficient.

FEdgeColor

ColorSpec | {[0 0 0]}

Color of the displayed frame edge — Specifies the color used for the displayed frame. You can specify a color using a vector of RGB values or a MATLAB colorspec name. By default, the frame edge is displayed in black ([0 0 0]).

FFaceColor

ColorSpec | {none}

Color of the displayed frame face — Specifies the color used for the displayed frame face. You can specify a color using a vector of RGB values or a MATLAB colorspec name. By default, the frame face is 'none', meaning no face color is filled in. Another useful color is 'cyan' ([0 1 1]), which looks like water.

FLatLimit

[southern_limit northern_limit]

Latitude limits of map frame relative to projection origin — The map frame encloses the area in which data and graticule lines are plotted and beyond which they are trimmed. For non-oblique and non-azimuthal projections, which have quadrangular frames, this property controls the north-south extent of the frame. If a projection is made oblique by the inclusion of a non-zero rotation angle (the third element of the Origin vector), FLatLimit still applies, but in the rotated latitude-longitude system rather than in the geographic system. In the case of azimuthal projections, which have circular frames, FLatLimit takes the special form [-Inf radius] where radius is the spherical distance (in degrees or radians, depending on the AngleUnits property of the projection) from the projection origin to the edge of the frame.

    Note:   In most common situations, including non-oblique cylindrical and conic projections and polar azimuthal projections, there is no need to set FLatLimit; use MapLatLimit instead.

FLineWidth

scalar {2}

Frame edge line width — Sets the line width of the displayed frame edge. The value is a scalar representing points, which is 2 by default.

FLonLimit

[western_limit eastern_limit]

Latitude limits of map frame relative to projection origin — The map frame encloses the area in which data and graticule lines are plotted and beyond which they are trimmed. For non-oblique and non-azimuthal projections, which have quadrangular frames, this property controls the east-west extent of the frame. If a projection is made oblique by the inclusion of a non-zero rotation angle (the third element of the Origin vector), FLonLimit still applies, but in the rotated latitude-longitude system rather than in the geographic system. The FLonLimit property is ignored for azimuthal projections.

    Note:   In most common situations, including non-oblique cylindrical and conic projections, there is no need to set FLonLimit; use MapLonLimit instead.

TrimLat

[southern_limit northern_limit]
(read-only, projection-dependent)

Bounds on FLatLimit — This read-only property sets bounds on the values that axesm and setm will accept for the MapLatLimit and FLatLimit properties, which is necessary because some map projections cannot display the entire globe without extending to infinity. For example, TrimLat is [-90 90] degrees for most cylindrical projections and [-86 86] degrees for the Mercator projection because the north-south scale becomes infinite as one approaches either pole.

TrimLon

[western_limit eastern_limit]
(read-only, projection-dependent)

Bounds on FLonLimit — This read-only property sets bounds on the values that axesm and setm will accept for the MapLonLimit and FLonLimit properties, which is necessary because some map projections cannot display the entire globe without extending to infinity. For example, TrimLon is [-135 135] degrees for most conic projections.

Properties That Control the Grid

Grid

on | {off}

Grid visibility — Controls the visibility of the display grid. When the grid is 'off' (the default), the grid is not displayed. When the grid is 'on', meridians and parallels are visible. The grid is plotted as a set of line objects.

GAltitude

scalar z-axis value {Inf}

Grid z-axis setting — Sets the z-axis location for the grid when displayed. Its default value is infinity, which is displayed above all other map objects. However, you can set this to some other value for stacking objects above the grid, if desired.

GColor

ColorSpec | {[0 0 0]}

Color of the displayed grid — Specifies the color used for the displayed grid. You can specify a color using a vector of RGB values or one of the MATLAB colorspec names. By default, the map grid is displayed in black ([0 0 0]).

GLineStyle

LineStyle {:}

Grid line style — Determines the style of line used when the grid is displayed. You can specify any line style supported by the MATLAB line function. The default line style is a dotted line (that is, ':').

GLineWidth

scalar {0.5}

Grid line width — Sets the line width of the displayed grid. The value is a scalar representing points, which is 0.5 by default.

MLineException

vector of longitudes {[]}

Exceptions to grid meridian limits — Allows specific meridians of the displayed grid to extend beyond the grid meridian limits to the poles. The value must be a vector of longitudes in the appropriate angle units. For longitudes so specified, grid lines extend from pole to pole regardless of the existence of any grid meridian limits. This vector is empty by default.

MLineFill

scalar plotting point density {100}

Grid meridian plotting precision — Sets the number of points to be used in plotting the grid meridians. The default value is 100 points. The number of points required for a reasonable display varies with the projection. Cylindrical projections such as the Miller require very few. Projections resulting in more complex shapes, such as the Werner, look better with higher densities. The default value is generally sufficient.

MLineLimit

[north south] | [south north] {[]}

Grid meridian limits — Establishes latitudes beyond which displayed grid meridians do not extend. By default, this property is empty, so the meridians extend to the poles. There are two exceptions to the meridian limits. No meridian extends beyond the map latitude limits, and exceptions to the meridian limits for selected meridians are allowed (see above).

MLineLocation

scalar interval or specific vector {30º}

Grid meridian interval or specific locations — Establishes the interval between displayed grid meridians. When a scalar interval is entered in the map axes MLineLocation, meridians are displayed, starting at 0º longitude and repeating every interval in both directions, which by default is 30º. Alternatively, you can enter a vector of longitudes, in which case a meridian is displayed for each element of the vector.

PLineException

vector of latitudes {[]}

Exceptions to grid parallel limits — Allows specific parallels of the displayed grid to extend beyond the grid parallel limits to the International Date Line. The value must be a vector of latitudes in the appropriate angle units. For latitudes so specified, grid lines extend from the western to the eastern map limit, regardless of the existence of any grid parallel limits. This vector is empty by default.

PLineFill

scalar plotting point density {100}

Grid parallel plotting precision — Sets the number of points to be used in plotting the grid parallels. The default value is 100. The number of points required for a reasonable display varies with the projection. Cylindrical projections such as the Miller require very few. Projections resulting in more complex shapes, such as the Bonne, look better with higher densities. The default value is generally sufficient.

PLineLimit

[east west] | [west east] {[]}

Grid parallel limits — Establishes longitudes beyond which displayed grid parallels do not extend. By default, this property is empty, so the parallels extend to the date line. There are two exceptions to the parallel limits. No parallel extends beyond the map longitude limits, and exceptions to the parallel limits for selected parallels are allowed (see above).

PLineLocation

scalar interval or specific vector {15º}

Grid parallel interval or specific locations — Establishes the interval between displayed grid parallels. When a scalar interval is entered in the map axes PLineLocation, parallels are displayed, starting at 0º latitude and repeating every interval in both directions, which by default is 15º. Alternatively, you can enter a vector of latitudes, in which case a parallel is displayed for each element of the vector.

Properties That Control Grid Labeling

FontAngle

{normal} | italic | oblique

Select italic or normal font for all grid labels — Selects the character slant for all displayed grid labels. 'normal' specifies nonitalic font. 'italic' and 'oblique' specify italic font.

FontColor

ColorSpec | {black}

Text color for all grid labels — Sets the color of all displayed grid labels. ColorSpec is a three-element vector specifying an RGB triple or a predefined MATLAB color string (colorspec).

FontName

courier | {helvetica} | symbol | times

Font family name for all grid labels — Sets the font for all displayed grid labels. To display and print properly, FontName must be a font that your system supports.

FontSize

scalar in units specified in FontUnits {9}

Font size — An integer specifying the font size to use for all displayed grid labels, in units specified by the FontUnits property. The default point size is 9.

FontUnits

{points} | normalized | inches | centimeters | pixels

Units used to interpret the FontSize property — When set to normalized, the toolbox interprets the value of FontSize as a fraction of the height of the axes. For example, a normalized FontSize of 0.1 sets the text characters to a font whose height is one-tenth of the axes' height. The default units (points) are equal to 1/72 of an inch.

FontWeight

bold | {normal}

Select bold or normal font — The character weight for all displayed grid labels.

LabelFormat

{compass} | signed | none

Labeling format for grid — Specifies the format of the grid labels. If 'compass' is employed (the default), meridian labels are suffixed with an "E" for east and a "W" for west, and parallel labels are suffixed with an "N" for north and an "S" for south. If 'signed' is used, meridian labels are prefixed with a "+" for east and a "-" for west, and parallel labels are suffixed with a "+" for north and a "-" for south. If 'none' is selected, straight latitude and longitude numerical values are employed, so western meridian labels and southern parallel labels will have a "-", but no symbol precedes eastern and northern (positive) labels.

LabelRotation

on | {off}

Label Rotation — Determines whether the meridian and parallel labels are displayed without rotation (the default) or rotated to align to the graticule. This option is not available for the Globe display.

LabelUnits

{degrees} | dm | dms | radians

Specify units and formatting for grid labels — The display of meridian and parallel labels is controlled by the map axes LabelUnits property, as described in the following table.

LabelUnits valueLabel format
'degrees'decimal degrees
'dm'degrees/decimal minutes
'dms'degrees/minutes/decimal seconds
'radians'decimal radians

LabelUnits does not have a default of its own; instead it defaults to the value of AngleUnits at the time the map axes is constructed, which itself defaults to degrees. Although you can specify 'dm' and 'dms' for LabelUnits, these values are not accepted when setting AngleUnits.

MeridianLabel

on | {off}

Toggle display of meridian labels — Specifies whether the meridian labels are visible or not.

MLabelLocation

scalar interval or vector of longitudes

Specify meridians for labeling — Meridian labels need not coincide with the displayed meridian lines. Labels are displayed at intervals if a scalar in the map axes MLabelLocation is entered, starting at the prime meridian and repeating at every interval in both directions. If a vector of longitudes is entered, labels are displayed at those meridians. The default locations coincide with the displayed meridian lines, as specified in the MLineLocation property.

MLabelParallel

{north} | south | equator | scalar latitude

Specify parallel for meridian label placement — Specifies the latitude location of the displayed meridian labels. If a latitude is specified, all meridian labels are displayed at that latitude. If 'north' is specified, the maximum of the MapLatLimit is used; if 'south' is specified, the minimum of the MapLatLimit is used. If 'equator' is specified, a latitude of 0º is used.

MLabelRound

integer scalar {0}

Specify significant digits for meridian labels — Specifies to which power of ten the displayed labels are rounded. For example, if MLabelRound is -1, labels are displayed down to the tenths. The default value of MLabelRound is 0; that is, displayed labels have no decimal places, being rounded to the ones column (100).

ParallelLabel

on | {off}

Toggle display of parallel labels — Specifies whether the parallel labels are visible or not.

PLabelLocation

scalar interval or vector of latitudes

Specify parallels for labeling — Parallel labels need not coincide with the displayed parallel lines. Labels are displayed at intervals if a scalar in the map axes PLabelLocation is entered, starting at the equator and repeating at every interval in both directions. If a vector of latitudes is entered, labels are displayed at those parallels. The default locations coincide with the displayed parallel lines, as specified in the PLineLocation property.

PLabelMeridian

east | {west} | prime | scalar longitude

Specify meridian for parallel label placement — Specifies the longitude location of the displayed parallel labels. If a longitude is specified, all parallel labels are displayed at that longitude. If 'east' is specified, the maximum of the MapLonLimit is used; if 'west' is specified, the minimum of the MapLonLimit is used. If 'prime' is specified, a longitude of 0º is used.

PLabelRound

integer scalar {0}

Specify significant digits for parallel labels — Specifies to which power of ten the displayed labels are rounded. For example, if PLabelRound is -1, labels are displayed down to the tenths. The default value of PLabelRound is 0; that is, displayed labels have no decimal places, being rounded to the ones column (100).

See Also

| | |

Was this topic helpful?