## Distances on the Sphere

Many geospatial domains (seismology, for example) describe distances between points on the surface of the earth as angles. This is simply the result of dividing the length of the shortest great-circle arc connecting a pair points by the radius of the Earth (or whatever planet one is measuring). This gives the angle (in radians) subtended by rays from each point that join at the center of the Earth (or other planet). This is sometimes called a "spherical distance." You can thus call the resulting number a "distance in radians." You could also call the same number a "distance in earth radii." When you work with transformations of geodata, keep this in mind.

You can easily convert that angle from radians to degrees. For example, you can call `distance` to compute the distance in meters from London to Kuala Lumpur:

```latL = 51.5188; lonL = -0.1300; latK = 2.9519; lonK = 101.8200; earthRadiusInMeters = 6371000; distInMeters = distance(latL, lonL,... latK, lonK, earthRadiusInMeters) distInMeters = 1.0571e+007```
Then convert the result to an angle in radians:
```distInRadians = distInMeters / earthRadiusInMeters distInRadians = 1.6593```
Finally, convert to an angle in degrees:
```distInDegrees = rad2deg(distInRadians) distInDegrees = 95.0692```
This really only makes sense and produces accurate results when we approximate the Earth (or planet) as a sphere. On an ellipsoid, one can only describe the distance along a geodesic curve using a unit of length.

Mapping Toolbox™ software includes a set of six functions to conveniently convert distances along the surface of the Earth (or another planet) from units of kilometers (km), nautical miles (nm), or statute miles (sm) to spherical distances in degrees (deg) or radians (rad):

• `km2deg`, `nm2deg`, and `sm2deg` go from length to angle in degrees

• `km2rad`, `nm2rad`, and `sm2rad` go from length to angle in radians

You could replace the final two steps in the preceding example with

```distInKilometers = distInMeters/1000; earthRadiusInKm = 6371; km2deg(distInKilometers, earthRadiusInKm) ans = 95.0692```
Because these conversion can be reversed, the toolbox includes another six convenience functions that convert an angle subtended at the center of a sphere, in degrees or radians, to a great-circle distance along the surface of that sphere:

• `deg2km`, `deg2nm`, and `deg2sm` go from angle in degrees to length

• `rad2km`, `rad2nm`, and `rad2sm` go from angle in radians to length

When given a single input argument, all 12 functions assume a radius of 6,371,000 meters (6371 km, 3440.065 nm, or 3958.748 sm), which is widely-used as an estimate of the average radius of the Earth. An optional second parameter can be used to specify a planetary radius (in output length units) or the name of an object in the Solar System.

### Arc Length as an Angle in the distance and reckon Functions

Certain syntaxes of the `distance` and `reckon` functions use angles to denote distances in the way described above. In the following statements, the range argument, `arclen`, is in degrees (along with all the other inputs and outputs):

```[arclen, az] = distance(lat1, lon1, lat2, lon2) [latout, lonout] = reckon(lat, lon, arclen, az)```
By adding the optional `units` argument, you can use radians instead:
```[arclen, az] = distance(lat1, lon1, lat2, lon2, 'radians') [latout, lonout] = reckon(lat, lon, arclen, az, 'radians')```
If an `ellipsoid` argument is provided, however, then `arclen` has units of length, and they match the units of the semimajor axis length of the reference ellipsoid. If you specify `ellipsoid = [1 0]` (the unit sphere), `arclen` can be considered to be either an angle in radians or a length defined in units of earth radii. It has the same value either way. Thus, in the following computation, `lat1`, `lon1`, `lat2`, `lon2`, and `az` are in degrees, but `arclen` will appear to be in radians:

```[arclen, az] = distance(lat1, lon1, lat2, lon2, [1 0]) ```

### Summary: Available Distance and Angle Conversion Functions

The following table shows the Mapping Toolbox unit-to-unit distance and arc conversion functions. They all accept scalar, vector, and higher-dimension inputs. The first two columns and rows involve angle units, the last three involve distance units:

The angle conversion functions along the major diagonal, `toDegrees`, `toRadians`, `fromDegrees`, and `fromRadians`, can have no-op results. They are intended for use in applications that have no prior knowledge of what angle units might be input or desired as output.