# 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.

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: ''

SemimajorAxis
SemiminorAxis
InverseFlattening
Eccentricity
Flattening
ThirdFlattening
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'

SemimajorAxis
SemiminorAxis
InverseFlattening
Eccentricity
Flattening
ThirdFlattening
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'

SemimajorAxis
SemiminorAxis
InverseFlattening
Eccentricity
Flattening
ThirdFlattening
SurfaceArea
Volume

or specify the length unit at the time of construction:

referenceSphere('Earth','km')
ans =

referenceSphere with defining properties:

Name: 'Earth'
LengthUnit: 'kilometer'

SemimajorAxis
SemiminorAxis
InverseFlattening
Eccentricity
Flattening
ThirdFlattening
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 referenceEllipsoidand 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

Flattening
ThirdFlattening
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

Flattening
ThirdFlattening
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

Flattening
ThirdFlattening
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

Flattening
ThirdFlattening
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
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

Flattening
ThirdFlattening
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

Flattening
ThirdFlattening
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.