Main Content

referenceEllipsoid

Reference ellipsoid

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

There are several ways to create reference ellipsoid objects, including:

  • Create a geocrs object, and then query its Spheroid property.

  • Create a projcrs object, access the geocrs object contained in its GeographicCRS property, and then query the Spheroid property of the geocrs.

  • Create a reference ellipsoid for the World Geodetic System of 1984 (WGS84) by using the wgs84Ellipsoid function.

  • Use the referenceEllipsoid function (described here).

Description

example

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

Input Arguments

expand all

Name of the reference ellipsoid, specified as one of the values in the Names of EPSG Ellipsoids table.

Data Types: char | string

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. For information on valid EPSG codes, see the EPSG home page.

Data Types: double

Length unit, specified as a character vector or string scalar. You can specify any length unit that is supported by the validateLengthUnit function.

ValueUnit Name
"m", "meter", "meters", "metre", "metres"Meters
"cm", "centimeter", "centimeters", "centimetre", "centimetres"Centimeters
"mm", "millimeter", "millimeters", "millimetre", "millimetres"Millimeters
"micron", "microns"Microns
"km", "kilometer", "kilometers", "kilometre", "kilometers"Kilometers
"nm", "naut mi", "nautical mile", "nautical miles"Nautical miles
"ft", "international ft", "foot", "international foot", "feet", "international feet"Feet
"in", "inch", "inches"Inches
"yd", "yds", "yard", "yards"Yards
"mi", "mile", "miles", "international mile", "international miles"Miles
"sf", "survey ft", "US survey ft", "U.S. survey ft", "survey foot", "US survey foot", "U.S. survey foot", "survey feet", "US survey feet", "U.S. survey feet"U.S. survey feet
"sm", "survey mile", "survey miles", "statute mile", "statute miles", "US survey mile", "US survey miles", "U.S. survey mile(s)", "U.S. survey miles"U.S. survey miles (statute miles)
"Clarke's foot", "Clarkes foot"Clarke's feet
"German legal metre", "German legal meter"German legal metres
"Indian foot"Indian feet

Data Types: char | string

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. For information on valid EPSG codes, see the EPSG home page.

When the reference ellipsoid represents the unit sphere or a custom ellipsoid, Code is an empty vector ([]).

Example: 7030

Data Types: double

Name of the reference ellipsoid, specified as a character vector or string scalar. 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 | string

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

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

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

Create a custom reference ellipsoid by modifying the properties of a default reference ellipsoid.

customPlanet = referenceEllipsoid;
customPlanet.Name = 'Tiny Planet';
customPlanet.LengthUnit = 'meter';
customPlanet.SemimajorAxis = 8000;
customPlanet.SemiminorAxis = 7900
customPlanet = 
referenceEllipsoid with defining properties:

                 Code: []
                 Name: 'Tiny Planet'
           LengthUnit: 'meter'
        SemimajorAxis: 8000
        SemiminorAxis: 7900
    InverseFlattening: 80
         Eccentricity: 0.157619002661481

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

You can get a reference ellipsoid from a geographic coordinate reference system (CRS) or a projected CRS.

Get Ellipsoid from Geographic CRS

Read a shapefile containing world cities into the workspace as a geospatial table. The table represents the cities using shape objects in geographic coordinates.

GT = readgeotable("worldcities.shp");

Get a geographic CRS from the shape objects by querying the GeographicCRS property. Then, get the reference ellipsoid by querying the Spheroid property of the CRS.

gcrs1 = GT.Shape.GeographicCRS;
E1 = gcrs1.Spheroid
E1 = 
referenceEllipsoid with defining properties:

                 Code: 7030
                 Name: 'WGS 84'
           LengthUnit: 'meter'
        SemimajorAxis: 6378137
        SemiminorAxis: 6356752.31424518
    InverseFlattening: 298.257223563
         Eccentricity: 0.0818191908426215

  and additional properties:

    Flattening
    ThirdFlattening
    MeanRadius
    SurfaceArea
    Volume

Get Ellipsoid from Projected CRS

Get information about a GeoTIFF image of Boston by using the georasterinfo function. The file contains raster data in projected coordinates.

info = georasterinfo("boston.tif");

Get a projected CRS from the returned RasterInfo object by querying the CoordinateReferenceSystem property. Get the geographic CRS from the projected CRS by querying the GeographicCRS property. Then, get the reference ellipsoid by querying the Spheroid property of the geographic CRS.

pcrs = info.CoordinateReferenceSystem;
gcrs2 = pcrs.GeographicCRS;
E2 = gcrs2.Spheroid
E2 = 
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.

Version History

Introduced in R2012a

expand all