referenceEllipsoid

Reference ellipsoid

expand all in page

Description

A referenceEllipsoid object encapsulates a reference ellipsoid, modeled as an oblate spheroid with three additional properties: name, unit of length of the semi-major and semi-minor axes, and a numerical EPSG code.

Creation

You can create a general referenceEllipsoid object with the referenceEllipsoid function described here. You can also create a referenceEllipsoid with properties specific to the World Geodetic System 1984 reference ellipsoid using the wgs84Ellipsoid function.

E = referenceEllipsoid
E = referenceEllipsoid(name)
E = referenceEllipsoid(code)
E = referenceEllipsoid(name,lengthUnit)
E = referenceEllipsoid(code,lengthUnit)

Description

E = referenceEllipsoid creates a referenceEllipsoid object that represents the unit sphere.

example

E = referenceEllipsoid(name) creates a referenceEllipsoid object corresponding to name. name is case-insensitive. The values of the SemimajorAxis and SemiminorAxis properties are in meters.

E = referenceEllipsoid(code) creates a referenceEllipsoid object corresponding to the numerical EPSG code, code. All of the nearly 60 codes in the EPSG ellipsoid table are supported. The unit of length used for the SemimajorAxis and SemiminorAxis properties depends on the ellipsoid selected, and is indicated in the property LengthUnit.

E = referenceEllipsoid(name,lengthUnit) and

E = referenceEllipsoid(code,lengthUnit) create a referenceEllipsoid object with the SemimajorAxis and SemiminorAxis properties in the specified unit of length, LengthUnit. The unit of length can be any length unit supported by the validateLengthUnit function.

Properties

expand all

Numerical EPSG code, specified as an empty vector or an integer between 7000 and 8000, although not all integers in this range are valid numerical EPSG codes. The code indicates a row in the EPSG ellipsoid table corresponding to the referenceEllipsoid.

When the reference ellipsoid represents the unit sphere, Code is an empty vector, [].

Example: 7030

Data Types: double

Name of the reference ellipsoid, specified as a character vector. When you create a reference ellipsoid by specifying its name, use one of the values in the Names of EPSG Ellipsoids table.

When the reference ellipsoid represents the unit sphere, Name is the character vector 'Unit Sphere'.

Example: 'World Geodetic System 1984'

Data Types: char

Unit of length for the ellipsoid axes, specified as a character vector. The character vector can be empty, or it can be any unit of length accepted by the validateLengthUnit function.

When the reference ellipsoid represents the unit sphere, LengthUnit is the empty character vector ''.

Example: 'km'

Data Types: char

Equatorial radius of ellipsoid, specified as a positive, finite scalar. The SemimajorAxis property is expressed in units of length specified by LengthUnit.

When the SemimajorAxis property is changed, the SemiminorAxis property scales as needed to preserve the shape of the ellipsoid and the values of shape-related properties including InverseFlattening and Eccentricity. The only way to change the SemimajorAxis property is to set it directly, using dot notation.

Example: 6378137

Data Types: double

Distance from center of ellipsoid to pole, specified as a nonnegative, finite scalar. The value of SemiminorAxis is always less than or equal to SemimajorAxis, and is expressed in units of length specified by LengthUnit.

When the SemiminorAxis property is changed, the SemimajorAxis property remains unchanged, but the shape of the ellipsoid changes, which is reflected in changes in the values of InverseFlattening, Eccentricity, and other shape-related properties.

Example: 6356752

Data Types: double

Reciprocal of flattening, specified as positive scalar in the range [1, Inf].

The value of inverse flattening, 1/f, is calculated using SemimajorAxis value a and SemiminorAxis value b according to 1/f = a/(a-b). A value 1/f of Inf designates a perfect sphere. As 1/f approaches 1, the reference ellipsoid approaches a flattened disk.

When the InverseFlattening property is changed, other shape-related properties update, including Eccentricity. The SemimajorAxis property remains unchanged, but the value of SemiminorAxis adjusts to reflect the new shape.

Example: 300

Data Types: double

First eccentricity of the ellipsoid, specified as nonnegative scalar in the range [0, 1].

The value of eccentricity, ecc, is calculated using SemimajorAxis value a and SemiminorAxis value b according to ecc = sqrt(a2 - b2)/a. A value ecc of 0 designates a perfect sphere.

When the Eccentricity property is changed, other shape-related properties update, including InverseFlattening. The SemimajorAxis property remains unchanged, but the value of SemiminorAxis adjusts to reflect the new shape.

Example: 0.08

Data Types: double

This property is read-only.

Flattening of the ellipsoid, specified as nonnegative scalar in the range [0, 1].

The value of flattening, f, is calculated using SemimajorAxis value a and SemiminorAxis value b according to f = (a-b)/a.

Data Types: double

This property is read-only.

Third flattening of the ellipsoid, specified as nonnegative scalar in the range [0, 1].

The value of the third flattening, n, is calculated using SemimajorAxis value a and SemiminorAxis value b according to n = (a-b)/(a+b).

Data Types: double

This property is read-only.

Mean radius of the ellipsoid, specified as positive, finite scalar. The MeanRadius property is expressed in units of length specified by LengthUnit.

The mean radius of the ellipsoid, r, is calculated using SemimajorAxis value a and SemiminorAxis value b according to r = (2a+b)/3.

Data Types: double

This property is read-only.

Surface area of the ellipsoid, specified as positive, finite scalar. The SurfaceArea property is expressed in units of area consistent the unit of length specified by the LengthUnit property.

Data Types: double

This property is read-only.

Volume of the ellipsoid, specified as positive, finite scalar. The Volume property is expressed in units of volume consistent with the unit of length specified by the LengthUnit property.

Data Types: double

Examples

collapse all

Open Live Script

Create a reference ellipsoid object by specifying the name of the ellipsoid.

e = referenceEllipsoid('GRS 1980')
e = 
referenceEllipsoid with defining properties:

                 Code: 7019
                 Name: 'GRS 1980'
           LengthUnit: 'meter'
        SemimajorAxis: 6378137
        SemiminorAxis: 6356752.31414036
    InverseFlattening: 298.257222101
         Eccentricity: 0.0818191910428158

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

Create the same reference ellipsoid object by specifying the EPSG code 7019.

e = referenceEllipsoid(7019)
e = 
referenceEllipsoid with defining properties:

                 Code: 7019
                 Name: 'GRS 1980'
           LengthUnit: 'meter'
        SemimajorAxis: 6378137
        SemiminorAxis: 6356752.31414036
    InverseFlattening: 298.257222101
         Eccentricity: 0.0818191910428158

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

Create a reference ellipsoid object, specifying the units. For length unit, you can specify any unit of length accepted by the validateLengthUnit function.

e = referenceEllipsoid('GRS80','km')
e = 
referenceEllipsoid with defining properties:

                 Code: 7019
                 Name: 'GRS 1980'
           LengthUnit: 'kilometer'
        SemimajorAxis: 6378.137
        SemiminorAxis: 6356.75231414036
    InverseFlattening: 298.257222101
         Eccentricity: 0.0818191910428158

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

Create a reference ellipsoid, specifying the GeoTIFFCodes.Ellipsoid field from a file.

info = geotiffinfo('boston.tif');
e = referenceEllipsoid(info.GeoTIFFCodes.Ellipsoid)
e = 
referenceEllipsoid with defining properties:

                 Code: 7019
                 Name: 'GRS 1980'
           LengthUnit: 'meter'
        SemimajorAxis: 6378137
        SemiminorAxis: 6356752.31414036
    InverseFlattening: 298.257222101
         Eccentricity: 0.0818191910428158

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

More About

expand all

Tips

  • When you define an ellipsoid in terms of semimajor and semiminor axes (rather than semimajor axis and inverse flattening, or semimajor axis and eccentricity), a small loss of precision in the last few digits of Flattening, Eccentricity, and ThirdFlattening may occur. This is unavoidable, but does not affect the results of practical computation.

Compatibility Considerations

expand all

Behavior changed in R2020b

See Also

| | | |

Introduced in R2012a

Mapping Toolbox Documentation

Support