Documentation Center

  • Trial Software
  • Product Updates

Interacting with Displayed Maps

Picking Locations Interactively

You can use Mapping Toolbox™ functions and GUIs to interact with maps, both in mapview and in figures created with axesm. This section describes two useful graphic input functions, inputm and gcpmap. The inputm function (analogous to the MATLAB® ginput function) allows you to get the latitude-longitude position of a mouse click. The gcpmap function (analogous to the MATLAB function get(gca,'CurrentPoint')) returns the current mouse position, also in latitude and longitude.

Explore inputm with the following commands, which display a map axes with its grid and then request three mouse clicks, the locations of which are stored as geographic coordinates in the variable points. Then the plotm function plots the points you clicked as red markers. The display you see depends on the points you select:

axesm sinusoid
framem on; gridm on
points =
  -41.7177 -145.0293
    7.9211   -0.5332
   38.5492  149.2237

    Note   If you click outside the map frame, inputm returns a valid but incorrect latitude and longitude, even though the point you indicated is off the map.

One reason you might want to manually identify points on a map is to interactively explore how much distortion a map projection has at given locations. For example, you can feed the data acquired with inputm to the distortcalc function, which computes area and angular distortions at any location on a displayed map axes. If you do so using the points variable, the results of the previous three mouse clicks are as follows:

[areascale,angledef] = distortcalc(points(1,1),points(1,2))
areascale =
angledef =
>> [areascale,angledef] = distortcalc(points(2,1),points(2,2))
areascale =
angledef =
[areascale,angledef] = distortcalc(points(3,1),points(3,2))
areascale =
angledef =

This indicates that the current projection (sinusoidal) has the equal-area property, but exhibits variable angular distortion across the map, less near the equator and more near the poles.

To see a working application that uses the inputm function, view and run the Creating an Interactive Map for Selecting Point Features mapexfindcitymapexfindcity example.

Defining Small Circles and Tracks Interactively

Geographic line annotations such as navigational tracks and small circles can be generated interactively. Great circle tracks are the shortest distance between points, and when closed partition the Earth into equal halves; a small circle is the locus of points at a constant distance from a reference point. Use trackg and scircleg to create them by clicking on the map. Double-click the tracks or circles to modify the lines. Shift+click to type specific parameters into a control panel. The control panels also allow you to retrieve or set properties of tracks and circles (for instance, great circle distances and small circle radii).

The following example illustrates how to interactively create a great circle track from Los Angeles, California, to Tokyo, Japan, and a 1000 km radius small circle centered on the Hawaiian Islands. The track is made via the trackg function, which prompts you to select endpoints for a track with the mouse. The scircleg function prompts for two points also, a center and any point on the circumference of the small circle. The specifics of the track and the circle are then adjusted more precisely with dialog controls:

  1. Set up an orthographic view centered over the Pacific Ocean. Use the coast MAT-file:

    axesm('ortho','origin',[30 180])
    load coast
  2. Create a track with the trackg function, which prompts for two endpoints. The default track type is a great circle:

    Track1:  Click on starting and ending points

    Click near Los Angeles and Tokyo, and the track is drawn.

  3. Now create a small circle around Hawaii with the scircleg function, which prompts for a center point and a point on the perimeter. Make the circle's radius about 2000 km, but don't worry about getting the size exact:

    Circle 1:  Click on center and perimeter

    The map should look approximately like this.

  4. Adjust the size of the small circle to be 2000 km by Shift+clicking anywhere on its perimeter. The Small Circles dialog box appears.

  5. Type 2000 into the Radius field.

  6. Click Close. The small circle readjusts to be 2000 km around Hawaii.

  7. To adjust the track between Los Angeles and Tokyo, Shift+click on it. This brings up the Track dialog, with which you specify a position and initial azimuth for either endpoint, as well as the length and type of the track.

  8. Change the track type from Great Circle to Rhumb Line with the Track pop-up menu. The track immediately changes shape.

  9. Experiment with the other Track dialog controls. Also note that you can move the endpoints of the track with the mouse by dragging the red circles, and obtain the arc's length in various units of distance.

The following figure shows the Small Circles and Track dialog boxes.

Interactive Text Annotation

You can also interactively place text annotations by clicking on a map display. The textm function, which requires numerical arguments for locating a specified text string, was illustrated in Placing Geographic and Nongeographic Objects in a Map Axes. The gtextm function, which takes a text string and optional properties as arguments, interactively defines the location for the specified text object based on where you click on the map.

Try these gtextm commands to label the locations you have just annotated:

gtextm('Los Angeles')

The following figure displays the results of these gtextm commands. After you place text, you can move it interactively using the selection tool in the map figure window.

Working with Objects by Name

You can manipulate displayed map objects by name. Many Mapping Toolbox functions assign descriptive names to the Tag property of the objects they create. The namem and related functions allow you to control the display of groups of similarly named objects, determine the names and change them if desired, and use the name in the Handle Graphics® set and get functions. There is also a Mapping Toolbox graphical user interface, mobjects, to help you manage the display and control of objects.

Some mapping display functions like framem, gridm, and contourm assign object tags by default. You can also set the name upon display by assigning a string to the Tag property in mapping display functions that use property name/property value pairs. If the Tag does not contain a string, the name defaults to an object's Type property, such as 'line' or 'text'.

Determining and Manipulating Object Names

  1. Display a vector map of the world:

    f = axesm('fournier')
    framem on; gridm on;
    plabel on; mlabel('MLabelParallel',0)
    load coast

    Below is the resulting map.

  2. List the names of the objects in the current axes using namem:

    ans =
  3. The handlem function allows you to dereference graphic objects and to get or set their properties. Change the line width of the coastline with set:

  4. Change the colors of the meridian and parallel labels separately:

    set(handlem('Mlabel'),'Color',[.5 .2 0])
    set(handlem('Plabel'),'Color',[.2 .5 0])

    You can also change these labels to be the same color using setm:

    setm(f,'fontcolor', [.4 .5 .6])
  5. The handlem command with no arguments summons a UI control with a list of map axes objects. This is useful for selecting objects interactively. Try



    h = handlem
  6. Combined with set, this makes it simple to change properties such as color. Remember, however, to use the right property name. Patches, for example, have a FaceColor and EdgeColor, while most other objects simply have Color, as is the case with the Coastline object. Now use handlem to call a color picker to set the coastline to any color you like:


    The reference page for handlem lists the object names that it recognizes. Note that most of these names can be prefixed with "all", which returns an array of all handles for that class of object.

  7. Now try handlem using the all modifier:

    t = handlem('alltext')
    l = handlem('allline')

    Note that you can also use all with the hidem and showm functions:


For more information on the use of functions and tools for manipulating objects, consult the setm, getm, handlem, hidem, showm, clmo, namem, tagm, and mobjects reference pages.

Was this topic helpful?