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

  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 following 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 

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