MATLAB Examples

# gdistm documentation

This function returns distances between mouse clicks on a map or cumulative distances along a path of mouse clicks on a map. Data points are entered by pressing a mouse button or any key on the keyboard except carriage return, which terminates input, or backspace, which removes the previous data point.

## Syntax

```distances = gdistm
distances = gdistm(N)
distances = gdistm('rh')
distances = gdistm(DistanceUnit)
PathDistance = gdistm('path')
distances = gdistm('color',ColorSpec)
[distances,lat,lon] = gdistm(...)```

## Description

distances = gdistm gathers an unlimited number of points until the return key is pressed. Distances between points are returned in meters by default.

distances = gdistm(N) gets N points from the current map axes and returns a vector containing the great circle distance from point to point. The cursor can be positioned using a mouse.

distances = gdistm('rh') specifies a rhumb line track. If 'rh' is not specified, a great circle track is assumed.

distances = gdistm(DistanceUnit) specifies a unit of length measurement. Can be any unit described in the documentation for validateLengthUnit.

PathDistance = gdistm('path') specifies that a cumulative path distance along several point clicks is returned. If the 'path' option is chosen, length of distances array is N and distances(1) = 0. Matlabmatically, PathDistance = [0;cumsum(distances)];

distances = gdistm('color',ColorSpec) specifies a marker and line color.

[...,lat,lon] = gdistm(...) returns arrays of clicked latitudes and longitudes equivalent to [lat,lon] = inputm(...).

## Example:

First, initialize a map of the United States:

```worldmap([25 55],[-130 -65]) states = shaperead('usastatehi', 'UseGeoCoords', true); geoshow(states) ```

With the map initialized, type gdistm and start clicking away. Perhaps you'd like to know the distance from LA to New York in meters? If so, this'll tell you:

```gdistm ```
```ans = 3.8831e+06 ```

Above, distances between click points were returned in units of meters. Note that although the great-circle path distance was calculate, the gray line is straight. That's because it's easier to code.

To get total miles along a 4-point path, maybe LA to New York, stopping by Texas and Florida along the way, do this:

```gdistm(4,'path','color','red','miles') ```
```ans = 1.0e+03 * 0 1.0868 2.1793 3.2189 ```

## Author Info

This function and supporting documentation were written by Chad A. Greene of the University of Texas at Austin's Institute for Geophysics (UTIG), November 2014.