Documentation

This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

Understanding Angles, Directions, and Distances

Positions, Azimuths, Headings, Distances, Length, and Ranges

When using spherical coordinates, distances are expressed as angles, not lengths. As there is an infinity of arcs that can connect two points on a sphere or spheroid, by convention the shortest one (the great circle distance) is used to measure how close two points are. As is explained in Working with Distances on the Sphere, you can convert angular distance on a sphere to linear distance. This is different from working on an ellipsoid, where one can only speak of linear distances between points, and to compute them one must specify which reference ellipsoid to use.

In spherical or geodetic coordinates, a position is a latitude taken together with a longitude, e.g., `(lat,lon)`, which defines the horizontal coordinates of a point on the surface of a planet. When we consider two points, e.g.,`(lat1,lon1)` and `(lat2,lon2)`, there are several ways in which their 2–D spatial relationships are typically quantified:

• The azimuth (also called heading) to take to get from `(lat1,lon1)` to `(lat2,lon2)`

• The back azimuth (also called heading) from `(lat2,lon2)` to `(lat1,lon1)`

• The spherical distance separating `(lat1,lon1)` from `(lat2,lon2)`

• The linear distance (range) separating `(lat1,lon1)` from `(lat2,lon2)`

The first three are angular quantities, while the last is a length. Mapping Toolbox™ functions exist for computing these quantities. For more information, see Directions and Areas on the Sphere and Spheroid and also Navigation for additional examples.

There is no single default unit of distance measurement in the toolbox. Navigation functions use nautical miles as a default and the `distance` function uses degrees of arc length. For many functions, the default unit for distances and positions is degrees, but you need to verify the default assumptions before using any of these functions.

 Note   When distances are given in terms of angular units (degrees or radians), be careful to remember that these are specified in terms of arc length. While a degree of latitude always subtends one degree of arc length, this is only true for degrees of longitude along the equator.

Working with Length and Distance Units

Linear measurements of lengths and distances on spheres and spheroids can use the same units they do on the plane, such as feet, meters, miles, and kilometers. They can be used for

• Absolute positions, such as map coordinates or terrain elevations

• Dimensions, such as a planet's radius or its semimajor and semiminor axes

• Distances between points or along routes, in 2-D or 3-D space or across terrain

Length units are needed to describe

• The dimensions of a reference sphere or ellipsoid

• The line-of-sight distance between points

• Distances along great circle or rhumb line curves on an ellipsoid or sphere

• X-Y locations in a projected coordinate system or map grid

• Offsets from a map origin (false eastings and northings)

• X-Y-Z locations in Earth-centered Earth-fixed (ECEF) or local vertical systems

• Heights of various types (terrain elevations above a geoid, an ellipsoid, or other reference surface)

Choosing Units of Length

Using the toolbox effectively depends on being consistent about units of length. Depending on the specific function and the way you are calling it, when you specify lengths, you could be

• Explicitly specifying a radius, reference spheroid object, or ellipsoid vector

• Relying on the function itself to specify a default radius or ellipsoid

• Relying on the reference ellipsoid associated with a map projection structure (mstruct)

Whenever you are doing a computation that involves a reference sphere or ellipsoid, make sure that the units of length you are using are the same units used to define the radius of the sphere or semimajor axis of the ellipsoid. These considerations are discussed below.

Converting Units of Length

The following Mapping Toolbox functions convert between different units of length:

• `unitsratio` computes multiplicative factors for converting between 12 different units of length as well as between degrees and radians. You can use `unitsratio` to perform conversions when neither the input units of length nor the output units of length are known until run time. See Converting Angle Units that Vary at Run Time for more information.

• `km2nm`, `km2sm`, `nm2km`, `nm2sm`, `sm2km`, and `sm2nm` perform simple and convenient conversions between kilometers, nautical miles, and statute miles.

These utility functions accept scalars, vectors, and matrices, or any shape. For an overview of these functions and angle conversion functions, see Summary: Available Distance and Angle Conversion Functions.

Compute Conversion Ratio Between Units of Length

This example shows how to use the `unitsratio` function to create a conversion factor for many different units of length, such as microns, millimeters, inches, international feet, and U.S. survey feet. The unitsratio function also lets you convert angles between degrees and radians. For more information, see `unitsratio`.

Create a conversion factor for inches to centimeters and convert 4 inches into centimeters.

```cmPerInch = unitsratio('cm','inch') cm = cmPerInch * 4 ```
```cmPerInch = 2.5400 cm = 10.1600 ```

Create the inverse conversion factor and multiply it by the `cmPerInch` conversion factor.

```inch = unitsratio('in','centimeter') * cmPerInch ```
```inch = 1 ```

Working with Angles: Units and Representations

Angular measurements have many distinct roles in geospatial data handling. For example, they are used to specify

• Absolute positions — latitudes and longitudes

• Relative positions — azimuths, bearings, and elevation angles

• Spherical distances between point locations

Absolute positions are expressed in geodetic coordinates, which are actually angles between lines or planes on a reference sphere or ellipsoid. Relative positions use units of angle to express the direction between one place on the reference body from another one. Spherical distances quantify how far two places are from one another in terms of the angle subtended along a great-circle arc. On nonspherical reference bodies, distances are usually given in linear units such as kilometers (because on them, arc lengths are no longer proportional to subtended angle).

The basic unit for angles in MATLAB® is the radian. For example, if the variable theta represents an angle and you want to take its sine, you can use `sin(theta)` if and only if the value of theta is expressed in radians. If a variable represents the value of an angle in degrees, then you must convert the value to radians before taking the sine. For example,

```thetaInDegrees = 30; thetaInRadians = thetaInDegrees * (pi/180) sinTheta = sin(thetaInRadians) ```
As shown above, you can scale degrees to radians by multiplying by `pi/180`. However, you should consider using `deg2rad` for this purpose:
`thetaInRadians = deg2rad(thetaInDegrees)`
Likewise, you can perform the opposite conversion by applying the inverse factor,
`thetaInDegrees = thetaInRadians * (180/pi)`
or by using `rad2deg`,
`thetaInDegrees = rad2deg(thetaInRadians)`
The practice of using these functions has two significant advantages:

• It reduces the likelihood of human error (e.g., you might type "pi/108" by mistake)

• It signals clearly your intent—important to do should others ever read, modify, or debug your code

The functions `rad2deg` and `deg2rad` are very simple and efficient, and operate on vector and higher-dimensioned input as well as scalars.

Default and Variable Angle Units

Unlike MATLAB trigonometric functions, Mapping Toolbox functions do not always assume that angular arguments are in units of radians.

The low-level utility functions intended as building blocks of more complex features or applications work only in units of radians. Examples include the functions `unwrapMultipart` and `meridianarc`.

Many high-level functions, including `distance`, can work in either degrees or radians. Their interpretation of angles is controlled by the `'angleunits'` input argument. (`angleunits` can be either `'degrees'` or `'radians'`, and can generally be abbreviated.) This flexibility balances convenience and efficiency, although it means that you must take care to check what assumptions each function is making about its inputs.

Degrees, Minutes, and Seconds

In all Mapping Toolbox computations that involve angles in degrees, floating-point numbers (generally MATLAB class double) are used, which allows for integer and fractional values and rational approximations to irrational numbers. However, several traditional notations, which are still in wide use, represent angles as pairs or triplets of numbers, using minutes of arc (1/60 of degree) and seconds of arc (1/60 of a minute):

• Degrees-minutes notation (DM), e.g., 35° 15', equal to 35.25°

• Degrees-minutes-seconds notation (DMS) , e.g., 35° 15' 45'', equal to 35.2625°

In degrees-minutes representation, an angle is split into three separate parts:

1. A sign

2. A nonnegative, integer-valued degrees component

3. A nonnegative minutes component, real-valued and in the half-open interval [0 60)

For example, -1 radians is represented by a minus sign (-) and the numbers [57, 17.7468...]. (The fraction in the minutes part approximates an irrational number and is rounded here for display purposes. This subtle point is revisited in the following section.)

The toolbox includes the function `degrees2dm` to perform conversions of this sort. You can use this function to export data in DM form, either for display purposes or for use by another application. For example,

```degrees2dm(rad2deg(-1)) ans = -57.0000 17.7468```
More generally, `degrees2dm` converts a single-columned input to a pair of columns. Rather than storing the sign in a separate element, `degrees2dm` applies to the first nonzero element in each row. Function `dm2degrees` converts in the opposite direction, producing a real-valued column vector of degrees from a two-column array having an integer degrees and real-valued minutes column. Thus,
```dm2degrees(degrees2dm(pi)) == pi ans = 1```
Similarly, in degrees-minutes-seconds representation, an angle is split into four separate parts:

1. A sign

2. A nonnegative integer-valued degrees component

3. A minutes component which can be any integer from 0 through 59

4. A nonnegative minutes component, real-valued and in the half-open interval [0 60)

For example, -1 radians is represented by a minus sign (-) and the numbers [57, 17, 44.8062...], which can be seen using Mapping Toolbox function `degrees2dms`,

```degrees2dms(rad2deg(-1)) ans = -57.0000 17.0000 44.8062```
`degrees2dms` works like `degrees2dm`; it converts single-columned input to three-column form, applying the sign to the first nonzero element in each row.

A fourth function, `dms2degrees`, is similar to `dm2degrees` and supports data import by producing a real-valued column vector of degrees from an array with an integer-valued degrees column, an integer-value minutes column, and a real-valued seconds column. As noted, the four functions, `degrees2dm`, `degrees2dms`, `dm2degrees`, and `dms2degrees`, are particular about the shape of their inputs; in this regard they are distinct from the other angle-conversion functions in the toolbox.

The toolbox makes no internal use of DM or DMS representation. The conversion functions `dm2degrees` and `dms2degrees` are provided only as tools for data import. Likewise, `degrees2dm` and `degrees2dms` are only useful for displaying geographic coordinates on maps, publishing coordinate values, and for formatting data to be exported to other applications. Methods for accomplishing this are discussed below, in Formatting Latitudes and Longitudes.

Converting Angle Units that Vary at Run Time

Functions `deg2rad` and `rad2deg` are simple to use and efficient, but how do you write code to convert angles if you do not know ahead of time what units the data will use? The toolbox provides a set of utility functions that help you deal with such situations at run time.

In almost all cases—even at the time you are coding—you know either the input or destination angle units. When you do, you can use one of these functions:

For example, you might wish to implement a very simple sinusoidal projection on the unit sphere, but allow the input latitudes and longitudes to be in either degrees or radians. You can accomplish this as follows:

```function [x, y] = sinusoidal(lat, lon, angleunits) [lat, lon] = toRadians(angleunits, lat, lon); x = lon .* cos(lat); y = lat; ```
Whenever `angleunits` turns out to be `'radians'` at run time, the `toRadians` function has no real work to do; all the functions in this group handle such "no-op" situations efficiently.

In the very rare instances when you must code an application or MATLAB function in which the units of both input angles and output angles remain unknown until run time, you can still accomplish the conversion by using the `unitsratio` function. For example,

```fromUnits = 'radians'; toUnits = 'degrees'; piInDegrees = unitsratio(toUnits, fromUnits) * pi piInDegrees = 180 ```

Angles as Binary and Formatted Numbers

The terms decimal degrees and decimal minutes are often used in geospatial data handling and navigation. The preceding section avoided using them because its focus was on the representation of angles within MATLAB, where they can be arbitrary binary floating-point numbers.

However, once an angle in degrees is converted to a character vector, it is often helpful to describe that value as representing the angle in decimal degrees. Thus,

```num2str(rad2deg(1)) ans = 57.2958```
gives a value in decimal degrees. In casual communication it is common to refer to a quantity such as `rad2deg(1)` as being in decimal degrees, but strictly speaking, that is not true until it is somehow converted to a character vector in base 10. That is, a binary floating-point number is not a decimal number, whether it represents an angle in degrees or not. If it does represent an angle and that number is then formatted and displayed as having a fractional part, only then is it appropriate to speak of "decimal degrees." Likewise, the term "decimal minutes" applies when you convert a degrees-minutes representation to a character vector, as in
```num2str(degrees2dm(rad2deg(1))) ans = 57 17.7468```

Formatting Latitudes and Longitudes

When a DM or DMS representation of an angle is expressed as a character vector, it is traditional to tag the different components with the special characters `d`, `m`, and `s`, or °, ', and ".

When the angle is a latitude or longitude, a letter often designates the sign of the angle:

• `N` for positive latitudes

• `S` for negative latitudes

• `E` for positive longitudes

• `W` for negative longitudes

For example, 123 degrees, 30 minutes, 12.7 seconds west of Greenwich can be written as 123d30m12.7sW, 123° 30° 12.7" W, or -123° 30° 12.7".

Use the function `str2angle` to import latitude and longitude data formatted as such character vectors. Conversely, you can format numeric degree data for display or export with `angl2str`, or combine `degrees2dms` or `degrees2dm` with `sprintf` to customize formatting.

See Degrees, Minutes, and Seconds for more details about DM and DMS representation.