Main Content

axesm-Based Maps

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 the axes function, called the axesm function. Maps created with the axesm function, called axesm-based maps (previously referred to as map axes) share all properties associated with regular axes, and they include 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, scale, and other properties. For complete descriptions of all axesm-based map properties, see the axesm-Based Map Properties reference page.

The syntax of axesm 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 an axesm-based map.

The figure window created using axesm contains the same set of tools and menus as any MATLAB figure. By default, the figure window is 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.

Most axesm-based map functions are similar to MATLAB plotting functions, except they accept data with geographic/geodetic coordinates (latitudes and longitudes) instead of Cartesian and polar coordinates. axesm-based map functions typically have the same names as their MATLAB counterparts, with the addition of an 'm' suffix (for maps). For example, the axesm-based map analog to the plot function is plotm.

axesm-based maps manage most of the details in displaying a map. They project your data, cut and trim the data to specified limits, and display the maps at various scales. With the toolbox you can also add customary cartographic elements, such as a frame, grid lines, coordinate labels, and text labels, to your displayed map. If you change your projection properties, or even the projection itself, some map displays are automatically redrawn with the new settings, undoing any cuts or trims if necessary.

Note

In its current implementation, the toolbox maintains the map projection and display properties by storing special data in the UserData property of the axesm-based map. The toolbox also takes over the UserData property of objects projected on axesm-based maps. Therefore, never attempt to set the UserData property of an axesm-based map or an object projected onto an axesm-based map. Do not apply the MATLAB get function to axes UserData, depend on the contents of UserData in any way, or apply functions that set or get UserData to the axesm-based map or the objects mapped on an axesm-based map. Only use the getm and setm to obtain and modify the properties of axesm-based maps.

Tips to Working with axesm-Based Maps

  • You can list all the names, classes, and IDs of map projections supported by axesm-based maps with the maps function.

  • You can place many types of objects in an axesm-based map, 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. See the handlem reference page for a list of the objects that can occupy an axesm-based map and how to query for them.

  • You can define multiple independent figures containing axesm-based maps, but only one can be active at any one time. Use axes(obj) to activate an existing axesm-based map.

  • axesm-based maps 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 axesm-based map properties:

    p = getm(h)
    

See Also

| |