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

Syntax

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.

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

name — Name of the reference ellipsoid

'Unit Sphere' (default) | character vector | string scalar

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

Data Types: char | string

code — Numerical EPSG code

[] (default) | integer between 7000 and 8000

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

lengthUnit — Length unit

'' (default) | character vector | string scalar

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

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

Code — Numerical EPSG code

[] (default) | integer between 7000 and 8000

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 — Name of the reference ellipsoid

'Unit Sphere' (default) | character vector | string scalar

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

LengthUnit — Unit of length for the ellipsoid axes

'' (default) | character vector | string scalar

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

SemimajorAxis — Equatorial radius of ellipsoid

1 (default) | positive, finite scalar

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

SemiminorAxis — Distance from center of ellipsoid to pole

1 (default) | nonnegative, finite scalar

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

InverseFlattening — Reciprocal of flattening

Inf (default) | positive scalar in the range [1, Inf]

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

Eccentricity — First eccentricity of ellipsoid

0 (default) | nonnegative scalar in the range [0, 1]

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(a² - b²)/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

Flattening — Flattening of ellipsoid

nonnegative scalar in the range [0, 1]

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

ThirdFlattening — Third flattening of ellipsoid

nonnegative scalar in the range [0, 1]

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

MeanRadius — Mean radius of the ellipsoid

positive, finite scalar

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

SurfaceArea — Surface area of the ellipsoid

positive, finite scalar

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

Volume — Volume of the ellipsoid

positive, finite scalar

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

Construct GRS80 Reference Ellipsoid

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 Custom Model for Planet

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

Get Reference Ellipsoid from Coordinate Reference System

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

Names of EPSG Ellipsoids

All of the nearly 60 codes in the EPSG ellipsoid table are supported. A subset of these ellipsoids can be created by specifying their name. The short and long names of these ellipsoids, along with their corresponding code, appear in the table. You can create a reference ellipsoid by specifying either its code, short name, or long name.

EPSG Code	Short Name	Long Name
—	'unitsphere'	'Unit Sphere'
7035	'sphere'	'Sphere'
7019	'grs80'	'GRS 1980'
7030	'wgs84'	'WGS 84'
7015	'everest'	'Everest 1830 (1837 Adjustment)'
7004	'bessel'	'Bessel 1841'
7001	'airy1830'	'Airy 1830'
7002	'airy1849'	'Airy Modified 1849'
7008	'clarke66'	'Clarke 1866'
7012	'clarke80'	'Clarke 1880 (RGS)'
7022	'international'	'International 1924'
7024	'krasovsky'	'Krassowsky 1940'
7043	'wgs72'	'WGS 72'
—	'wgs60'	'World Geodetic System 1960'
—	'iau65'	'International Astronomical Union 1965'
—	'wgs66'	'World Geodetic System 1966'
—	'iau68'	'International Astronomical Union 1968'
7030	'earth'	'WGS 84'
—	'sun'	'Sun'
—	'moon'	'Moon'
—	'mercury'	'Mercury'
—	'venus'	'Venus'
—	'mars'	'Mars'
—	'jupiter'	'Jupiter'
—	'saturn'	'Saturn'
—	'uranus'	'Uranus'
—	'neptune'	'Neptune'
—	'pluto'	'Pluto'

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

R2020b: Name property for some ReferenceEllipsoid objects has changed

Starting in R2020b, the Name property of referenceEllipsoid objects always contains the names of the ellipsoids as they appear in the EPSG Geodetic Database. In R2020a and previous releases, the value of the Name property depended on the name or code you used to create the object.

For example, create two referenceEllipsoid objects using the WGS84 reference system. Create the first object by specifying its EPSG code, and create the second object by specifying its name. In R2020b and later releases the value of the Name property is the same for both referenceEllipsoid objects. In R2020a and earlier releases the value of the Name property is not the same.

r1 = referenceEllipsoid(7030);
r2 = referenceEllipsoid('World Geodetic System 1984');
r1.Name
r2.Name

R2020b and later	R2020a and earlier
ans = 'WGS 84' ans = 'WGS 84'	ans = 'WGS 84' ans = 'World Geodetic System 1984'

If you have existing code in which you create a reference ellipsoid object by specifying a name to the referenceEllipsoid creation function, you do not need to update your code to correspond to a name in the EPSG Geodetic Database.

For more information about the EPSG Geodetic Database, see the EPSG home page.