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 semimajor and semiminor axes, and a numerical EPSG code.
Creation
There are several ways to create reference ellipsoid objects, including:
Create a
geocrs
object, and then query itsSpheroid
property.Create a
projcrs
object, access thegeocrs
object contained in itsGeographicCRS
property, and then query theSpheroid
property of thegeocrs
.Create a reference ellipsoid for the World Geodetic System of 1984 (WGS84) by using the
wgs84Ellipsoid
function.Use the
referenceEllipsoid
function (described here).
Syntax
Description
E = referenceEllipsoid
creates a
referenceEllipsoid
object that represents the unit
sphere.
E = referenceEllipsoid(
creates
a name
)referenceEllipsoid
object corresponding to
name
. name
is caseinsensitive.
The values of the SemimajorAxis
and
SemiminorAxis
properties are in meters.
E = referenceEllipsoid(
creates
a code
)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(
andname
,lengthUnit
)
E = referenceEllipsoid(
create a code
,lengthUnit
)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 shaperelated 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 shaperelated
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/(ab). 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
shaperelated 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^{2}

b^{2})/a. A value ecc of 0 designates a perfect
sphere.
When the Eccentricity
property is changed, other
shaperelated 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 readonly.
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 =
(ab)/a.
Data Types: double
ThirdFlattening
— Third flattening of ellipsoid
nonnegative scalar in the range [0, 1]
This property is readonly.
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 =
(ab)/(a+b).
Data Types: double
MeanRadius
— Mean radius of the ellipsoid
positive, finite scalar
This property is readonly.
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 readonly.
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 readonly.
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
, andThirdFlattening
may occur. This is unavoidable, but does not affect the results of practical computation.
Version History
Introduced in R2012aR2020b: 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.
See Also
oblateSpheroid
 referenceSphere
 validateLengthUnit
 wgs84Ellipsoid
 geocrs
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)