Main Content

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`

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

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

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 area 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 additional 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`

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.