## Documentation |

On this page… |
---|

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.

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 following figure, made using the `geoid` data
set, maps the figure of the Earth. To execute these commands, select
them all by dragging over the list in the Help browser, then right—click
and choose `Evaluate Selection`:

load geoid; load coast figure; axesm robinson geoshow(geoid,geoidlegend,'DisplayType','texturemap') colorbar('southoutside') geoshow(lat,long,'color','k')

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.

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.

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

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.

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, 1/f, `(where `f` is `Flattening`)
and `Eccentricity, ecc, ` 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.

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 string accepted by `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

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

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.

**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`.**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-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.

Was this topic helpful?