# 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 Spherical Coordinates

### Spheres, Spheroids, and Geoids

Working with geospatial data involves geographic concepts (such as geographic and plane coordinates, spherical geometry) and geodetic concepts (such as ellipsoids and datums). The following sections explain some concepts that underlie geometric computations on spherical surfaces.

Although the Earth is very round, it is an oblate spheroid rather than a perfect sphere. This difference is so small (only one part in 300) that modeling the Earth as spherical is sufficient for making small-scale (world or continental) maps. However, making accurate maps at larger scale demands that a spheroidal model be used. Such models are essential, for example, when you are mapping high-resolution satellite or aerial imagery, or when you are working with coordinates from the Global Positioning System (GPS). This section addresses how Mapping Toolbox™ software accurately models the shape, or figure, of the Earth and other planets.

### Geoid and Ellipsoid

Literally, geoid means Earth-shaped. The geoid is an empirical approximation of the figure of the Earth (minus topographic relief), its "lumpiness." Specifically, it is an equipotential surface with respect to gravity, more or less corresponding to mean sea level. It is approximately an oblate ellipsoid, but not exactly so because local variations in gravity create minor hills and dales (which range from -100 m to +60 m across the Earth). This variation in height is on the order of 1 percent of the differences between the semimajor and semiminor ellipsoid axes used to approximate the Earth's shape, as described in Reference Spheroids.

The shape of the geoid is important for some purposes, such as calculating satellite orbits, but need not be taken into account for every mapping application. However, knowledge of the geoid is sometimes necessary, for example, when you compare elevations given as height above mean sea level to elevations derived from GPS measurements. Geoid representations are also inherent in datum definitions. To see a visualization of the geoid, see Map the Geoid.

You can define ellipsoids in several ways. They are usually specified by a semimajor and a semiminor axis, but are often expressed in terms of a semimajor axis and either inverse flattening (which for the Earth, as mentioned above, is one part in 300) or eccentricity. Whichever parameters are used, as long as an axis length is included, the ellipsoid is fully constrained and the other parameters are derivable. The components of an ellipsoid are shown in the following diagram.

The toolbox includes ellipsoid models that represent the figures of the Sun, Moon, and planets, as well as a set of the most common ellipsoid models of the Earth. For more information, see Reference Spheroids.

### Map the Geoid

This example maps the figure of the Earth using the geoid data set.

Load the geoid data set and map the geoid.

```load geoid; load coastlines figure; axesm robinson geoshow(geoid,geoidlegend,'DisplayType','texturemap') colorbar('southoutside') geoshow(coastlat,coastlon,'color','k') ```

### Reference Spheroids

When the Earth (or another roughly spherical body such as the Moon) is modeled as a sphere having a standard radius, it is called a reference sphere. Likewise, when the model is a flattened (oblate) ellipsoid of revolution, with a standard semimajor axis and standard inverse flattening, semiminor axis, or eccentricity, it is called a reference ellipsoid. Both models are spheroidal in shape, so each can be considered to be a type of reference spheroid. Mapping Toolbox supports several representations for reference spheroids: `referenceSphere`, `referenceEllipsoid`, and `oblateSpheroid` objects, and an older representation, ellipsoid vector.

#### `referenceSphere` Objects

When using a strictly spherical model, you should generally use a `referenceSphere` object (although both `referenceEllipsoid` and `oblateSpheroid` can represent a perfect sphere).

By default, `referenceSphere` returns a dimensionless unit sphere:

`referenceSphere`
```ans = referenceSphere with defining properties: Name: 'Unit Sphere' LengthUnit: '' Radius: 1 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume ```

You can request a specific body by name, and the radius will be in meters by default:

`earth = referenceSphere('Earth')`
```earth = referenceSphere with defining properties: Name: 'Earth' LengthUnit: 'meter' Radius: 6371000 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

You can reset the length unit if desired (and the radius is rescaled appropriately) :

`earth.LengthUnit = 'kilometer'`
```earth = referenceSphere with defining properties: Name: 'Earth' LengthUnit: 'kilometer' Radius: 6371 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

or specify the length unit at the time of construction:

`referenceSphere('Earth','km')`
```ans = referenceSphere with defining properties: Name: 'Earth' LengthUnit: 'kilometer' Radius: 6371 and additional properties: SemimajorAxis SemiminorAxis InverseFlattening Eccentricity Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

Any length unit supported by `validateLengthUnit` can be used. A variety of abbreviations are supported for most length units, see `validateLengthUnit` for a complete list.

One thing to note about `referenceSphere` is that only the defining properties are displayed, in order to reduce clutter at the command line. (This approach saves a small amount of computation as well.) In particular, don't overlook the dependent `SurfaceArea` and `Volume` properties, even though they are not displayed. The surface area of the spherical earth model, for example, is easily obtained through the `SurfaceArea` property:

`earth.SurfaceArea`
```ans = 5.1006e+08 ```

This result is in square kilometers, because the `LengthUnit` property of the object earth has value `'kilometer'`.

When programming with Mapping Toolbox it may help to be aware that `referenceSphere` actually includes all the geometric properties of `referenceEllipsoid`and `oblateSpheroid` (`SemimajorAxis`, `SemiminorAxis`, `InverseFlattening`, `Eccentricity`, `Flattening`, `ThirdFlattening`, and `MeanRadius`, as well as `SurfaceArea`, and `Volume`). None of these properties can be set on a `referenceSphere`, and some have values that are fixed for all spheres. `Eccentricity` is always `0`, for example. But they provide a flexible environment for programming because any geometric computation that accepts a `referenceEllipsoid` will also run properly given a `referenceSphere`. This is a type of polymorphism in which different classes support common, or strongly overlapping interfaces.

#### `referenceEllipsoid` Objects

When using an oblate spheroid to represent the Earth (or another roughly spherical body), you should generally use a `referenceEllipsoid` object. An important exception occurs with certain small-scale map projections, many of which are defined only on the sphere. However, all important projections used for large-scale work, including Transverse Mercator and Lambert Conformal Conic, are defined on the ellipsoid as well as the sphere.

Like `referenceSphere`, `referenceEllipsoid` returns a dimensionless unit sphere by default:

`referenceEllipsoid`
```ans = referenceEllipsoid with defining properties: Code: [] Name: 'Unit Sphere' LengthUnit: '' SemimajorAxis: 1 SemiminorAxis: 1 InverseFlattening: Inf Eccentricity: 0 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

More typically, you would request a specific ellipsoid by name, resulting in an object with semimajor and semiminor axes properties in meters. For example, the following returns a `referenceEllipsoid` with `SemimajorAxis` and `InverseFlattening` property settings that match the defining parameters of Geodetic Reference System 1980 (GRS 80).

`grs80 = referenceEllipsoid('Geodetic Reference System 1980')`
```grs80 = referenceEllipsoid with defining properties: Code: 7019 Name: 'Geodetic Reference System 1980' LengthUnit: 'meter' SemimajorAxis: 6378137 SemiminorAxis: 6356752.31414036 InverseFlattening: 298.257222101 Eccentricity: 0.0818191910428158 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

In general, you should use the reference ellipsoid corresponding to the geodetic datum to which the coordinates of your data are referenced. For instance, the GRS 80 ellipsoid is specified for use with coordinates referenced to the North American Datum of 1983 (NAD 83).

As in the case of `referenceSphere`, you can reset the length unit if desired:

`grs80.LengthUnit = 'kilometer'`
```grs80 = referenceEllipsoid with defining properties: Code: 7019 Name: 'Geodetic Reference System 1980' LengthUnit: 'kilometer' SemimajorAxis: 6378.137 SemiminorAxis: 6356.75231414036 InverseFlattening: 298.257222101 Eccentricity: 0.0818191910428158 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

or specify the length unit at the time of construction:

`referenceEllipsoid('Geodetic Reference System 1980','km')`
```ans = referenceEllipsoid with defining properties: Code: 7019 Name: 'Geodetic Reference System 1980' LengthUnit: 'kilometer' SemimajorAxis: 6378.137 SemiminorAxis: 6356.75231414036 InverseFlattening: 298.257222101 Eccentricity: 0.0818191910428158 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

Any length unit supported by `validateLengthUnit` can be used.

The command-line display includes four geometric properties: `SemimajorAxis`, `SemiminorAxis`, `InverseFlattening`, and `Eccentricity`. Any pair of these properties, as long as at least one is an axis length, is sufficient to fully define a oblate spheroid; the four properties constitute a mutually dependent set. Parameters `InverseFlattening` and `Eccentricity` as a set are not sufficient to define an ellipsoid because both are dimensionless shape properties. Neither of those parameters provides a length scale, and, furthermore, are mutually dependent: ```ecc = sqrt((2 - f) * f)```.

In addition, there are five dependent properties that are not displayed, in order to reduce clutter on the command line: `Flattening`, `ThirdFlattening`, `MeanRadius`, `SurfaceArea`, and `Volume`. `SurfaceArea` and `Volume` work the same way as their `referenceSphere` counterparts. To continue the preceding example, the surface area of the GRS 80 ellipsoid in square kilometers (because `LengthUnit` is `'kilometer'`), is easily obtained as follows:

`grs80.SurfaceArea`
```ans = 5.1007e+08```

See the `referenceEllipsoid` reference page for definitions of the shape properties, permissible values for the `Name` property, and information on the `Code` property.

#### World Geodetic System 1984

Due in part to widespread use of the U.S. NAVSTAR Global Positioning System (GPS), which is tied to World Geodetic System 1984 (WGS 84), the WGS 84 reference ellipsoid is often the appropriate choice. For both convenience and speed (obtained by bypassing a table look-up step), it's a good idea in this case to use the `wgs84Ellipsoid` function, for example,

`wgs84 = wgs84Ellipsoid;`

The preceding line is equivalent to:

`wgs84 = referenceEllipsoid('wgs84');`

but it is easier to type and faster to run. You can also specify a length unit. `wgs84Ellipsoid(lengthUnit)`, is equivalent to `referenceEllipsoid('wgs84',lengthUnit)`, where `lengthUnit` is any unit value accepted by the `validateLengthUnit` function.

For example, the follow two commands show that the surface are of the WGS 84 ellipsoid is a little over 5 x 10^14 square meters: >> s = wgs84Ellipsoid s = referenceEllipsoid with defining properties: Code: 7030 Name: 'World Geodetic System 1984' LengthUnit: 'meter' SemimajorAxis: 6378137 SemiminorAxis: 6356752.31424518 InverseFlattening: 298.257223563 Eccentricity: 0.0818191908426215 and derived properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume >> s.SurfaceArea ans = 5.1007e+14

```s = wgs84Ellipsoid s.SurfaceArea ans = 5.1007e+14 ```
```s = referenceEllipsoid with defining properties: Code: 7030 Name: 'World Geodetic System 1984' LengthUnit: 'meter' SemimajorAxis: 6378137 SemiminorAxis: 6356752.31424518 InverseFlattening: 298.257223563 Eccentricity: 0.0818191908426215 and derived properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume ```
```s.SurfaceArea ```
```ans = 5.1007e+14 ```

#### Ellipsoid Vectors

An ellipsoid vector is simply a 2-by-1 double of the form: ```[semimajor_axis eccentricity]```. Unlike a spheroid object (any instance of `referenceSphere`, `referenceEllipsoid`, or `oblateSpheroid`), an ellipsoid vector is not self-documenting. Ellipsoid vectors are not even self-identifying. You have to know that a given 2-by-1 vector is indeed an ellipsoid vector to make any use of it. This representation does not validate that `semimajor_axis` is real and positive, for example, you have to do such validations for yourself.

Many toolbox functions accept ellipsoid vectors as input, but such functions accept spheroid objects as well and, for the reasons just stated, spheroid objects are recommended over ellipsoid vectors. In case you have written a function of your own that requires an ellipsoid vector as input, or have received such a function from someone else, note that you can easily convert any spheroid object `s` into an ellipsoid vector as follows:

`[s.SemimajorAxis s.Eccentricity]`

This means that you can construct a spheroid object using any of the three class constructors, or the `wgs84Ellipsoid` function, and hand off the result in the form of an ellipsoid vector if necessary.

#### `oblateSpheroid` Objects

`oblateSpheroid` is the superclass of `referenceEllipsoid`. An `oblateSpheroid` object is just like a `referenceEllipsoid` object minus its `Code`, `Name`, and `LengthUnit` properties. In fact, the primary role of the `oblateSpheroid` class is to provide the purely geometric properties and behaviors needed by the `referenceEllipsoid` class.

For most purposes, you can simply ignore this distinction, and the `oblateSpheroid` class itself, as a matter of internal software composition. No harm will come about, because a `referenceEllipsoid` object can do anything and be used anywhere that an `oblateSpheroid` can.

However, you can use `oblateSpheroid` directly when dealing with an ellipsoid vector that lacks a specified name or length unit. For example, compute the volume of a ellipsoid with a semimajor axis of 2000 and eccentricity of 0.1, as shown in the following.

```e = [2000 0.1]; s = oblateSpheroid; s.SemimajorAxis = e(1); s.Eccentricity = e(2) s.Volume```
```s = oblateSpheroid with defining properties: SemimajorAxis: 2000 SemiminorAxis: 1989.97487421324 InverseFlattening: 199.498743710662 Eccentricity: 0.1 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume ans = 3.3342e+10```

Of course, since the length unit of `e` is unspecified, the unit of `s.Volume` is likewise unspecified.

#### Working with Reference Spheroids

Reference spheroids are needed in three main contexts: map projections, curves and areas on the surface of a spheroid, and 3-D computations involving geodetic coordinates.

1. Map Projections

You can set the value of the `Geoid` property of a new map axes (which is actually a Spheroid property) using any type of reference spheroid representation when constructing the map axes with `axesm`. Except in the case of UTM and UPS, the default value is an ellipsoid vector representing the unit sphere: `[1 0]`. It is also the default value when using the `worldmap` and `usamap` functions.

You can reset the `Geoid` property of an existing map axes to any type of reference spheroid representation by using `setm`. For example, `worldmap` always sets up a projection based on the unit sphere but you can subsequently use `setm` to switch to the spheroid of your choice. To set up a map of North America for use with Geodetic Reference System 1980, for instance, follow `worldmap` with a call to `setm`, like this:

```ax = worldmap('North America'); setm(ax,'geoid',referenceEllipsoid('grs80'))```

When projecting or unprojecting data without a map axes, you can set the `geoid` field of a map projection structure (`mstruct`) to any type of reference spheroid representation. Remember to follow all `mstruct` updates with a second call to `defaultm` to ensure that all properties are set to legitimate values. For example, to use the Miller projection with WGS 84 in kilometers, start with:

```mstruct = defaultm('miller'); mstruct.geoid = wgs84Ellipsoid('km'); mstruct = defaultm(mstruct);```

You can inspect the `mstruct` to ensure that you are indeed using the WGS 84 ellipsoid:

`mstruct.geoid`
```ans = referenceEllipsoid with defining properties: Code: 7030 Name: 'World Geodetic System 1984' LengthUnit: 'kilometer' SemimajorAxis: 6378.137 SemiminorAxis: 6356.75231424518 InverseFlattening: 298.257223563 Eccentricity: 0.0818191908426215 and additional properties: Flattening ThirdFlattening MeanRadius SurfaceArea Volume```

See Map Axes Object Properties for definitions of the fields found in `mstructs`.

2. Curves and Areas

Another important context in which reference spheroids appear is the computation of curves and areas on the surface of a sphere or oblate spheroid. The `distance` function, for example, assumes a sphere by default, but accepts a reference spheroid as an optional input. `distance` is used to compute the length of the geodesic or rhumb line arc between a pair of points with given latitudes and longitudes. If a reference spheroid is provided through the `ellipsoid` argument, then the unit used for the arc length output matches the `LengthUnit` property of the spheroid.

Other functions for working with curves and areas that accept reference spheroids include `reckon`, `scircle1`, `scircle2`, `ellipse1`, `track1`, `track2`, and `areaquad`, to name just a few. When using such functions without their `ellipsoid` argument, be sure to check the individual function help if you are unsure about which reference spheroid is assumed by default.

3. 3-D Coordinate Transformations

The third context in which reference spheroids frequently appear is the transformation of geodetic coordinates (latitude, longitude, and height above the ellipsoid) to other coordinate systems. For example, the `geodetic2ecef` function, which converts point locations from a geodetic system to a geocentric (Earth-Centered Earth-Fixed) Cartesian system, requires a reference spheroid object (or an ellipsoid vector) as input. And the `elevation` function, which converts from geodetic to a local spherical system (azimuth, elevation, and slant range) also accepts a reference spheroid object or ellipsoid vector, but uses the GRS 80 ellipsoid by default if none is provided.