egm96geoid

R2026b

Geoid height from Earth Gravitational Model 1996 (EGM96)

Syntaxes of the egm96geoid function that return referencing vectors have been removed. Use a syntax that returns a reference object instead. For more information, see Version History.

Syntax

N = egm96geoid(lat,lon)

N = egm96geoid(R)

[N,globalR] = egm96geoid

Description

N = egm96geoid(lat,lon) returns the height in meters of the geoid at the specified latitude and longitude from the Earth Gravitational Model of 1996 (EGM96). Specify latitude and longitude in degrees.

N = egm96geoid(R) returns geoid heights at the cell center or posting locations specified by the raster reference object R.

[N,globalR] = egm96geoid returns geoid heights for the entire globe as a 721-by-1441 matrix spaced at 15-minute intervals with latitude limits [-90 90] and longitude limits [0 360]. The function also returns a raster reference object for the geoid heights.

Examples

Geoid Height from Latitude and Longitude

Find geoid heights from EGM96 by specifying latitude and longitude values in degrees. The result is returned in meters.

lat = 27.988056;
lon = 86.925278;
N = egm96geoid(lat,lon)

N = 
-28.7444

Geoid Heights within Limits

View geoid heights from EGM96 for a region including Europe.

Create a GeographicPostingsReference object that associates each geoid height with a location in geographic coordinates. Specify the latitude and longitude limits of the region in degrees. Specify the raster size as the number of rows and columns to include in the grid of geoid heights. Create the object by using the georefpostings function.

latlim = [30 72];
lonlim = [-25 45];
rasterSize = [100 100];
R = georefpostings(latlim,lonlim,rasterSize);

Create a grid of geoid heights for the region by specifying the reference object as input to the egm96geoid function.

N = egm96geoid(R);

Set up a map using an area of interest (AOI) created from the reference object. Display the geoid heights and global coastlines on the map.

figure
aoi = aoiquad(R);
newmap(aoi)
hold on

geopcolor(N,R)
load coastlines
geoplot(coastlat,coastlon,Color="k",AffectAutoLimits="off")

Add a title and a color bar. Apply a cartographic map layout.

title("Geoid Heights (m)")
colorbar

mx = gca;
mx.MapLayout = "cartographic";

Geoid Heights for Entire Globe

View geoid heights from EGM96 for the entire globe.

Return the geoid heights and a reference object for the globe. The geoid heights are spaced at 15-minute intervals.

[N,R] = egm96geoid;

Display the geoid heights on a world map.

figure
newmap
geopcolor(N,R)
hold on

Display global land areas on the same map. Add a title and a color bar.

land = readgeotable("landareas.shp");
geoplot(land,FaceColor="none")

title("Geoid Heights (m)")
colorbar

Input Arguments

lat — Latitude

scalar | vector | matrix

Latitude in degrees, specified as a scalar, vector, or matrix. The dimension of lat depends on the dimension of the geoid heights you want to find.

• To find a single geoid height, specify lat and lon as scalars.

• To find several geoid heights, specify lat and lon as vectors of the same length.

• To find a p-by-q grid of geoid heights, specify lat and lon as p-by-q matrices.

Data Types: single | double

lon — Longitude

scalar | vector | matrix

Longitude in degrees, specified as a scalar, vector, or matrix. The dimension of lon depends on the dimension of the geoid heights you want to find.

• To find a single geoid height, specify lat and lon as scalars.

• To find several geoid heights, specify lat and lon as vectors of the same length.

• To find a p-by-q grid of geoid heights, specify lat and lon as p-by-q matrices.

Data Types: single | double

R — Raster reference for N

GeographicPostingsReference object | GeographicCellsReference object

Raster reference for N, specified as a GeographicPostingsReference object or a GeographicCellsReference object. The raster reference associates each element of N with a location in geographic coordinates.

The RasterSize property of the reference object determines the size of the data grid, size(N).

Output Arguments

N — Geoid height

scalar | vector | matrix

Geoid height in meters, returned as a scalar, vector, or matrix.

The size of N depends on the syntax:

Syntax	Size of N
N = egm96geoid(lat,lon)	Size of lat and lon
N = egm96geoid(R)	R.RasterSize
[N,globalR] = egm96geoid	721-by-1441 matrix

Data Types: double

globalR — Global raster reference

GeographicPostingsReference object

Global raster reference, returned as a GeographicPostingsReference object of size 721-by-1441 with latitude limits [-90 90] and longitude limits [0 360].

More About

Earth Gravitational Model of 1996 (EGM96)

The geoid is an equipotential surface of the Earth's gravity field that approximates global mean sea level. You can visualize the geoid as the surface of the ocean without effects such as weather, waves, and land. The Earth Gravitational Model of 1996 (EGM96) is based on the ellipsoid specified by the World Geodetic System of 1984 (WGS84), so the egm96geoid function returns heights above or below the surface of the WGS84 ellipsoid.

Version History

Introduced before R2006a

R2026b: Report 3-D geographic CRS

The egm96geoid function now reports a 3-D geographic CRS when you return geoid heights for the entire globe. The GeographicCRS property of the raster reference object globalR contains a geocrs object with a VerticalCRS property that stores a vertical CRS.

In previous releases, the geocrs object reported by the function always contains 2-D CRS information. If your code depends on 2-D CRSs, such as when comparing horizontal CRSs using the isequal function, then you can remove the vertical CRS by setting the VerticalCRS property of the object to [].

R2023b: Syntaxes that return referencing vectors have been removed

Syntaxes of the egm96geoid function that return referencing vectors have been removed. Use a syntax that returns a geographic raster reference object instead. Reference objects have several advantages over referencing vectors.

• Unlike referencing vectors, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns. For more information about reference object properties, see the GeographicCellsReference and GeographicPostingsReference objects.

• You can manipulate the limits of rasters associated with reference objects using the geocrop function.

• You can manipulate the size and resolution of rasters associated with reference objects using the georesize function.

• Most functions that accept referencing vectors as inputs also accept reference objects.

This table shows the syntaxes of the egm96geoid function that return referencing vectors and how to update your code to use syntaxes that return reference objects instead.

Removed	Recommended
[N,refvec] = egm96geoid(samplefactor);	[~,globalR] = egm96geoid; latlim = globalR.LatitudeLimits; lonlim = globalR.LongitudeLimits; globalSize = globalR.RasterSize; rasterSize = 1 + ceil((globalSize-1)/samplefactor); R = georefpostings(latlim,lonlim,rasterSize); N = egm96geoid(R);
[N,refvec] = egm96geoid(samplefactor,latlim,lonlim);	[~, globalR] = egm96geoid; spacing = samplefactor ... * globalR.SampleSpacingInLatitude; R = georefpostings(latlim,lonlim,spacing,spacing); N = egm96geoid(R);

R2022a: Syntaxes that return referencing vectors warn

Syntaxes of the egm96geoid function that return referencing vectors issue a warning that they will be removed in a future release.

R2020b: Syntaxes that return referencing vectors will be removed

Syntaxes of the egm96geoid function that return referencing vectors will be removed in a future release.

R2020a: Return geoid heights referenced to geographic reference object

Return geoid heights from EGM96 that are referenced to a geographic raster reference object. You can specify GeographicCellsReference or GeographicPostingsReference objects, or return geoid heights and a reference object for the entire globe spaced at 15-minute intervals.

R2019b: Return geoid heights at specified latitudes and longitudes

Return geoid heights from EGM96 by specifying latitude and longitude in degrees. For example, find the geoid height at a latitude of 42.3601 degrees and a longitude of -71.589 degrees:

N = egm96geoid(42.3601,-71.589);

R2019b: Improved performance

In previous releases, egm96geoid accessed geoid heights using WW15MGH.GRD, a file that you downloaded from the Internet. Starting in R2019b, a grid of geoid heights from EGM96 is included with Mapping Toolbox™, and egm96geoid no longer reads data from WW15MGH.GRD.

As a result, the egm96geoid function shows improved performance. For example, this code shows about a 15x speed-up when you return the entire grid of geoid heights:

function timingTest
N = egm96geoid(1);
end

The approximate execution times are:

• R2019a: 0.1838 s

• R2019b: 0.0121 s

This code was timed on a Windows^® 10 test system with a 3.6-GHz Intel^® Xeon^® W-2133 CPU using the timeit function:

timeit(@timingTest)