Mapping Toolbox    
axesm

Define map axes and set map properties

Syntax

Description

The axesm function creates a map axes object complete with a map data structure. Maps must be displayed in map axes. All standard MATLAB axes properties of map axes are controlled by the axes command, along with set and get. Map axes properties are defined on creation with axesm and may be queried and changed after creation of a map axes using getm and setm.

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

axesm(handle) makes the map axes with the given handle the current map axes.

axesm(PropertyName,PropertyValue,...) creates map axes with the specified property values. The MapProjection property must be the first input pair.

axesm(ProjectionFile,PropertyName,PropertyValue,...) allows omission of the MapProjection property name. The first input must be the identifying string of an available projection.

Axes Definition

Map axes are standard MATLAB axes with different default settings for some properties and with a map data structure in the UserData slot. The main differences are:

The map structure is assigned to the UserData property. Do not overwrite this entry if map axes are desired. The map structure contains the map axes properties which, in addition to the special standard axes settings described here, constitute a map axes. The map axes properties are described later.

Examples

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

In the above example, all properties not explicitly addressed in the call are set to either fixed or calculated defaults. The M-file mercator.m is a projection file, so the same result could have been achieved with the command:

A projection file will include default data 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 will be in a Mercator projection. Any data falling outside the prescribed frame limits would not be displayed.

Note: the names of projection files are case sensitive. The projection files included in the Mapping Toolbox use only lower-case letters and Arabic numerals.

Object Properties

Properties that control the map

MapProjection                projection_name {no default}

Map projection - This property sets the projection, and hence all transformation calculations, for the map axes object. It is required in the creation of map axes. The projection name is a string corresponding to an M-file appropriate to the projection. It must be a member of the recognized projection set, which can be listed 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.

Zone                         ZoneSpec | {[] or 31N}

Zone for certain projections - This property 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 which 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.

AngleUnits                   {degrees} | radians | dms

Angular unit of measure - This property 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 a more detailed description of the angle unit options, see the Mapping Toolbox User's Guide.

Aspect                       {normal} | transverse

Display aspect - This property 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 projections calculations - This property modifies the position of the map within the axes. The projected coordinates are shifted in the x-direction by amount of FalseEasting. The FalseEasting is in the same units as the projected coordinates, i.e. the units of first element of the Geoid map axes property. False eastings and northings are sometimes used to ensure non-negative 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 projections calculations - This property modifies the position of the map within the axes. The projected coordinates are shifted in the y-direction by amount of FalseNorthing. The FalseNorthing is in the same units as the projected coordinates, i.e. the units of first element of the Geoid map axes property. False eastings and northings are sometimes used to ensure non-negative 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]

Planet geoid definition - This property sets the geoid for calculating the projections of any displayed map objects. In the Mapping Toolbox, the geoid is approximated by a spheroid. The default geoid is a sphere with a radius of 1. This is represented as [1 0]. Any semimajor axis, in any distance units, can be entered; eccentricity lies between 0 and 1. For more information on the geoid definition, see the geoid vector reference page in this section.

MapLatLimit                  [south north] | [north south]

Latitude limits of the displayed map - This property sets the north and south latitude limits of the map data. This information is useful for two purposes. The default extents for the texture mapping commands meshm, surfm, surfacem, surflm, pcolorm and imagem are set for the map axes; if the latitude limits match the actual matrix map data limits, no graticule definitions are required when calling the above commands. Secondly, establishing map latitude limits sets the absolute limit on the extent of displayed meridians, regardless of the values of the meridian limits or the meridian exceptions. For non-azimuthal projections in the normal aspect, the map limits are truncated to the smaller of the map and frame limits. The default map latitude limits for most projections are at the poles, [-90 90].

MapLonLimit                  [east west] | [west east]

Longitude limits of the displayed map - This property sets the east and west longitude limits of the map data. This information is useful for two purposes. The default extents for the texture mapping commands meshm, surfm, surfacem, surflm, pcolorm and imagem are set for the map axes; if the longitude limits match the actual matrix map data limits, no graticule definitions are required when calling the above commands. Secondly, establishing map longitude limits sets the absolute limit on the extent of displayed parallels, regardless of the values of the parallel limits or the parallel exceptions. For non-azimuthal projections in the normal aspect, the map limits are truncated to the smaller of the map and frame limits. The default map longitude limits for most projections are at the International Date Line, [-180 180].

MapParallels                 [lat] | [lat1 lat2]

Projection standard parallels - This property 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 will bias the projection towards 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 will be set to [15 75]). For azimuthal projections, the MapParallels property will always contain an empty vector and cannot be altered.

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

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.

Origin                       [latitude longitude orientation]

Origin and orientation for projection calculations - This property 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 will be centered on the map longitude limits. For more information on the origin, see the Mapping Toolbox User's Guide.

ScaleFactor                  scalar {1}

Scale factor for projection calculations - This property 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.

TrimLat                      [south north] (read-only, projection-dependent)

Latitude trimming for certain projections - This read-only property indicates the limits in latitude beyond which no plotting is attempted. This property is set by the projection and is usually used to avoid blow-ups to infinity. For example, the Mercator projection will trim all data outside the range [-86 86]. It is [-90 90] for most projections.

TrimLon                      [west east] (read-only, projection-dependent)

Longitude trimming for certain projections - This read-only property indicates the limits in longitude beyond which no plotting is attempted. This property is set by the projection and is usually used to avoid blow-ups to infinity. It is less commonly used than the latitude trimming and is
[-180 180] for most projections.

Properties that control the frame

Frame                        on | {off}

Frame visibility - This property 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 which 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 - This property sets the number of points to be used in plotting the frame for display. The default value is 100, which for a rectangular frame would result 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 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 - This property specifies the color used for the displayed frame. You can specify a color using a vector of RGB values or one of MATLAB's predefined names. By default, the frame edge is displayed in black ([0 0 0]).

FFaceColor                   ColorSpec | {none}

Color of the displayed frame face - This property specifies the color used for the displayed frame face. You can specify a color using a vector of RGB values or one of MATLAB's predefined names. 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                    [south north] | [north south]

Latitude limits of the base projection frame - This property sets the north and south latitude limits of the map frame. Latitudes refer to the base projection, and are [-90 90] by default for most projections. The frame latitude limits determine where data will be trimmed in a north-south sense. Data lying outside the latitude limits will not be displayed. Also, these limits determine the latitude positions of the frame for its own display.

For non-azimuthal projections in the normal aspect, the frame limits are truncated to the smaller of the map and frame limits. Frame limits for non-azimuthal projections are specified in Cartesian coordinates with respect to the map origin specified in the Origin property. Frame latitude limits for azimuthal projections are specified by -Inf and a radius in polar coordinates with respect to the map origin specified in the Origin property.

FLineWidth                   scalar {2}

Frame edge line width - This property sets the line width of the displayed frame edge. The value is a scalar representing points, which is 2 by default.

FLonLimit                    [east west] | [west east]

Longitude limits of the base projection frame - This property sets the east and west longitude limits of the map frame. Longitudes refer to the base projection, and are [-180 180] by default for most projections. The frame longitude limits determine where data will be trimmed in a east-west sense. Data lying outside the longitude limits will not be displayed. Also, these limits determine the longitude positions of the frame for its own display.

For non-azimuthal projections in the normal aspect, the frame limits are truncated to the smaller of the map and frame limits. Frame limits for non-azimuthal projections are specified in Cartesian coordinates with respect to the map origin specified in the Origin property. Frame longitude limits are ignored for azimuthal projections.

Properties that control the grid

Grid                         on | {off}

Grid visibility - This property 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 - This property sets the z-axis location for the grid when displayed. Its default value is infinity, which displays above all other map objects. However, this can be set to some other value for stacking objects above the grid, if desired.

GColor                       ColorSpec | {[0 0 0]}

Color of the displayed grid - This property specifies the color used for the displayed grid. You can specify a color using a vector of RGB values or one of MATLAB's predefined names. By default, the map grid is displayed in black ([0 0 0]).

GLineStyle                   LineStyle {:}

Grid line style - This property determines the style of line used when the grid is displayed. Any line style supported by the MATLAB line command can be specified. The default line style is a dotted line (i.e., ':').

GLineWidth                   scalar {0.5}

Grid line width - This property 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 - This property 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 will 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 - This property 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 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 - This property 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 will extend 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 - This property establishes the interval between displayed grid meridians. When a scalar interval is entered in the map axes MLineLocation, meridians will be displayed, starting at 0º longitude and repeating every interval in both directions, which by default is 30º. Alternatively, a vector of longitudes can be entered, in which case a meridian will be displayed for each element of the vector.

PLineException               vector of latitudes {[]}

Exceptions to grid parallel limits - This property 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 will extend from western to 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 - This property 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 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 - This property 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 will extend 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 - This property establishes the interval between displayed grid parallels. When an scalar interval is entered in the map axes PLineLocation, parallels will be displayed, starting at 0º latitude and repeating every interval in both directions, which by default is 15º. Alternatively, a vector of latitudes can be entered, in which case a parallel will be 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 - This property 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 - This property sets the color of all displayed grid labels. ColorSpec is a three-element vector specifying an RGB triple, or a predefined MATLAB color string.

FontName                     courier | {helvetica} | symbol | times

Font family name for all grid labels - This property 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

Labelling format for grid - This property 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 will precede eastern and northern (positive) labels.

LabelRotation                 on | {off}

Label Rotation - This property determines whether the meridian and parallel labels are displayed without rotation (the default), or rotated to align to the graticule.

LabelUnits                   {degrees} | radians | dms | dm

Specify units for labels - Grid labels will be displayed in the desired angular units as specified in LabelUnits, regardless of the map axes AngleUnits. The default value, however, does match the AngleUnits property.

MeridianLabel                on | {off}

Toggle display of meridian labels - This property 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 will be 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 will be 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 - This property specifies the latitude location of the displayed meridian labels. If a latitude is specified, all meridian labels will be 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 - This property specifies to which power of ten the displayed labels will be rounded. For example, if MLabelRound is -1, labels will be displayed down to the tenths. The default value of MLabelRound is 0, i.e., displayed labels have no decimal places, being rounded to the ones column (100).

ParallelLabel                on | {off}

Toggle display of parallel labels - This property 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 will be 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 will be 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 - This property specifies the longitude location of the displayed parallel labels. If a longitude is specified, all parallel labels will be 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 - This property specifies to which power of ten the displayed labels will be rounded. For example, if PLabelRound is -1, labels will be displayed down to the tenths. The default value of PLabelRound is 0, i.e., displayed labels have no decimal places, being rounded to the ones column (100).

See Also
gcm
 Get current map structure
getm
 Get map object properties
setm
 Set map object properties


  axes2ecc axesscale