geomodels package

Geographic data models.

Geoid model

class geomodels.GeoidModel

Bases: object

Geoid model.

Parameters:
  • name – the name of the geoid
  • path – (optional) directory for data file
  • cubic – (optional) interpolation method; false means bilinear, true (the default) means cubic.
  • threadsafe – (optional), if true, construct a thread safe object. The default is false
Raises:
  • GeographicErr – if the data file cannot be found, is unreadable, or is corrupt
  • GeographicErr – if threadsafe is True but the memory necessary for caching the data can’t be allocated.

The data file is formed by appending “.pgm” to the name. If path is specified (and is non-empty), then the file is loaded from directory, path. Otherwise the path is given by default_geoid_path(). If the threadsafe parameter is True, the data set is read into memory, the data file is closed, and single-cell caching is turned off; this results in a Geoid object which is thread safe.

cache()

Return true if a data cache is active.

cache_all()

Cache all the data.

Raises:
  • GeographicErr – if the memory necessary for caching the data can’t be allocated (in this case, you will have no cache and can try again with a smaller area).
  • GeographicErr – if there’s a problem reading the data.
  • GeographicErr – if this is called on a threadsafe Geoid.

On most computers, this is fast for data sets with grid resolution of 5’ or coarser. For a 1’ grid, the required RAM is 450MB; a 2.5’ grid needs 72MB; and a 5’ grid needs 18MB.

cache_area()

Set up a cache.

Parameters:
  • south (float) – south latitude (degrees) of the south edge of the cached area.
  • west – west longitude (degrees) of the west edge of the cached area.
  • north – north latitude (degrees) of the north edge of the cached area.
  • east – east longitude (degrees) of the east edge of the cached area.
Raises:
  • GeographicErr – if the memory necessary for caching the data can’t be allocated (in this case, you will have no cache and can try again with a smaller area).
  • GeographicErr – if there’s a problem reading the data.
  • GeographicErr – if this is called on a threadsafe Geoid.

Cache the data for the specified “rectangular” area bounded by the parallels south and north and the meridians west and east. east is always interpreted as being east of west, if necessary by adding 360 deg; to its value. south and north should be in the range [-90 deg, +90 deg].

cache_clear()

Clear the cache.

This never throws an error. This does nothing with a thread safe Geoid.

cache_east()

East edge of the cached area.

The cache excludes this edge.

cache_north()

North edge of the cached area.

The cache includes this edge.

cache_south()

South edge of the cached area.

The cache excludes this edge unless it’s the south pole.

cache_west()

West edge of the cached area.

The cache includes this edge.

convert_height()

Convert a height above the geoid to a height above the ellipsoid and vice versa.

Parameters:
  • lat – latitude of the point (degrees).
  • lon – longitude of the point (degrees).
  • h – height of the point (meters).
  • direction – a EHeightConvDir specifying the direction of the conversion; EHeightConvDir.GEOIDTOELLIPSOID means convert a height above the geoid to a height above the ellipsoid; Geoid.ELLIPSOIDTOGEOID means convert a height above the ellipsoid to a height above the geoid.
Raises:

GeographicErr – if there’s a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.

Returns:

converted height (meters).

datetime()

Return date of the data file.

If absent, return “UNKNOWN”.

static default_geoid_name()

The default name for the geoid.

This is the value of the environment variable GEOGRAPHICLIB_GEOID_NAME, if set; otherwise, it is “egm96-5”. The GeoidModel class does not use this function; it is just provided as a convenience for a calling program when constructing a GeoidModel object.

static default_geoid_path()

The default path for geoid data files.

This is the value of the environment variable GEOGRAPHICLIB_GEOID_PATH, if set; otherwise, it is ${GEOGRAPHICLIB_DATA}/geoids if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default.

description()

Return geoid description, if available, in the data file.

If the geoid description is absent in the data file return “NONE”.

equator_radius()

The equatorial radius of the ellipsoid (meters).

(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.)

flattening()

The flattening of the ellipsoid.

(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.

geoid_directory()

Return the directory used to load the geoid data.

geoid_file()

Return full file name used to load the geoid data.

geoid_name()

Return the “name” used to load the geoid data.

“name” is the first argument of the constructor.

interpolation()

Return interpolation method (“cubic” or “bilinear”).

max_error()

Return an estimate of the maximum interpolation and quantization error [m].

This relies on the value being stored in the data file. If the value is absent, return -1.

offset()

Offset (meters).

This in used in converting from the pixel values in the data file to geoid heights.

rms_error()

Return an estimate of the RMS interpolation and quantization error [m].

This relies on the value being stored in the data file. If the value is absent, return -1.

scale()

Scale (meters).

This in used in converting from the pixel values in the data file to geoid heights.

threadsafe()

Return true if the object is constructed to be thread safe.

class geomodels.EHeightConvDir

Bases: enum.IntEnum

An enumeration.

ELLIPSOIDTOGEOID = -1
GEOIDTOELLIPSOID = 1
NONE = 0

Graviti model

class geomodels.GravityModel

Bases: object

Gravity model.

Parameters:
  • name (str) – the name of the model
  • path – (optional) directory for data file
Raises:
  • GeographicErr – if the data file cannot be found, is unreadable, or is corrupt
  • MemoryError – if the memory necessary for storing the model can’t be allocated

A filename is formed by appending “.egm” (World Gravity Model) to the name. If path is specified (and is non-empty), then the file is loaded from directory, path. Otherwise the path is given by default_gravity_path().

This file contains the metadata which specifies the properties of the model. The coefficients for the spherical harmonic sums are obtained from a file obtained by appending “.cof” to metadata file (so the filename ends in “.egm.cof”).

angular_velocity()

The angular velocity of the model and the reference ellipsoid.

[\omega] = rad/s

datetime()

Date of the gravity model.

If absent, return “UNKNOWN”.

static default_gravity_name()

The default name for the gravity model.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_NAME, if set; otherwise, it is “egm96”. The GravityModel class does not use this function; it is just provided as a convenience for a calling program when constructing a GravityModel object.

static default_gravity_path()

the default path for gravity model data files.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/gravity if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default.

description()

The description of the gravity model.

If the gravity model description is absent in the data file return “NONE”.

disturbance()

Evaluate the gravity disturbance vector at an arbitrary point above (or below) the ellipsoid.

Parameters:
  • lat – the geographic latitude (degrees)
  • lon – the geographic longitude (degrees)
  • h – the height above the ellipsoid (meters)
Returns:

  • T the corresponding disturbing potential ([m**2 / s**2])
  • deltax the easterly component of the disturbance vector ([m / s**2])
  • deltay the northerly component of the disturbance vector ([m / s**2])
  • deltaz the upward component of the disturbance vector ([m / s**2])

equatorial_radius()

The equatorial radius of the ellipsoid (meters).

flattening()

The flattening of the ellipsoid.

geoid_height()

Evaluate the geoid height.

Parameters:
  • lat – the geographic latitude (degrees)
  • lon – the geographic longitude (degrees)
Returns:

N the height of the geoid above the reference ellipsoid (meters)

Some approximations are made in computing the geoid height so that the results of the NGA codes are reproduced accurately.

gravity()

Evaluate the gravity at an arbitrary point above (or below) the ellipsoid.

The function includes the effects of the earth’s rotation.

Parameters:
  • lat – the geographic latitude (degrees)
  • lon – the geographic longitude (degrees)
  • h – the height above the ellipsoid (meters)
Returns:

  • W the sum of the gravitational and centrifugal potentials ([m**2 / s**2])
  • gx the easterly component of the acceleration ([m / s**2])
  • gy the northerly component of the acceleration ([m / s**2])
  • gz the upward component of the acceleration ([m / s**2]); this is usually negative

gravity_file()

Full file name used to load the gravity model.

gravity_model_directory()

Return the directory used to load the gravity model.

gravity_model_name()

Return the “name” used to load the gravity model.

“name” is the first argument of the constructor, but this may be overridden by the model file).

mass_constant()

The mass constant of the model ([GM] = m**3 /s**2).

It is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth’s atmosphere).

phi()

Evaluate the centrifugal acceleration in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
Returns:

  • Phi, the centrifugal potential ([m**2 / s**2])
  • fx the x component of the centrifugal acceleration (m / s**2])
  • fy the y component of the centrifugal acceleration (m / s**2])

reference_mass_constant()

The mass constant of the reference ellipsoid.

[GM] = m**3 / s**2.

spherical_anomaly()

Evaluate the components of the gravity anomaly vector using the spherical approximation.

Parameters:
  • lat – the geographic latitude (degrees)
  • lon – the geographic longitude (degrees)
  • h – the height above the ellipsoid (meters)
Returns:

  • Dg01 the gravity anomaly ([m / s**2])
  • xi the northerly component of the deflection of the vertical (degrees)
  • eta the easterly component of the deflection of the vertical (degrees).

The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used so that the results of the NGA codes are reproduced accurately.

t()

Evaluate disturbing potential in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
  • z – geocentric coordinate of point (meters)
Returns:

T = W - U, the disturbing potential (also called the anomalous potential) ([m**2 / s**2])

t_components()

Evaluate the components of the gravity disturbance in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
  • z – geocentric coordinate of point (meters)
Returns:

  • T = W - U, the disturbing potential (also called the anomalous potential) ([m**2 / s**2])
  • deltaX the x component of the gravity disturbance ([m / s**2])
  • deltaY the Y component of the gravity disturbance ([m / s**2])
  • deltaZ the Z component of the gravity disturbance ([m / s**2])

u()

Evaluate the components of the acceleration due to normal gravity and the centrifugal acceleration in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
  • z – geocentric coordinate of point (meters)
Returns:

  • U = V0 + Phi, the sum of the normal gravitational and centrifugal potentials ([m**2 / s**2])
  • gammaX the x component of the normal acceleration ([m / s**2])
  • gammaY the y component of the normal acceleration ([m / s**2])
  • gammaZ the z component of the normal acceleration ([m / s**2])

v()

Evaluate the components of the gravity disturbance in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
  • z – geocentric coordinate of point (meters)
Returns:

  • V = W - Phi, the gravitational potential ([m**2 / s**2])
  • gx the x component of the acceleration ([m / s**2])
  • gy the y component of the acceleration ([m / s**2])
  • gz the z component of the acceleration ([m / s**2])

w()

Evaluate the components of the acceleration due to gravity and the centrifugal acceleration in geocentric coordinates.

Parameters:
  • x – geocentric coordinate of point (meters)
  • y – geocentric coordinate of point (meters)
  • z – geocentric coordinate of point (meters)
Returns:

  • W = V + Phi, the sum of the gravitational and centrifugal potentials ([m**2 / s**2])
  • gx the x component of the acceleration ([m / s**2])
  • gy the y component of the acceleration ([m / s**2])
  • gz the z component of the acceleration ([m / s**2])

Magnetic filed model

class geomodels.MagneticFieldModel

Bases: object

Magnetic Field Model.

Parameters:
  • name (str) – the name of the model
  • path – (optional) directory for data file
Raises:
  • GeographicErr – if the data file cannot be found, is unreadable, or is corrupt
  • MemoryError – if the memory necessary for storing the model can’t be allocated

A filename is formed by appending “.wmm” (World Magnetic Model) to the name. If path is specified (and is non-empty), then the file is loaded from directory, path. Otherwise the path is given by the MagneticFieldModel.default_magnetic_path().

This file contains the metadata which specifies the properties of the model. The coefficients for the spherical harmonic sums are obtained from a file obtained by appending “.cof” to metadata file (so the filename ends in “.wwm.cof”).

The model is not tied to a particular ellipsoidal model of the earth. The final earth argument to the constructor specifies an ellipsoid to allow geodetic coordinates to the transformed into the spherical coordinates used in the spherical harmonic sum.

datetime()

Return date of the model.

Return date of the model, if available, from the ReleaseDate field in the data file; if absent, return “UNKNOWN”.

static default_magnetic_name()

The default name for the magnetic model.

This is the value of the environment variable GEOGRAPHICLIB_MAGNETIC_NAME, if set; otherwise, it is “wmm2015”. The MagneticFieldModel class does not use this function; it is just provided as a convenience for a calling program when constructing a MagneticFieldModel object.

static default_magnetic_path()

Return the default path for magnetic model data files.

This is the value of the environment variable GEOGRAPHICLIB_MAGNETIC_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/magnetic if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default.

description()

Return the description of the magnetic model.

Return the description of the magnetic model if available, from the MagneticFieldModel.description() file in the data file; if absent, return “NONE”.

static field_components()

Compute various quantities dependent on the magnetic field.

Parameters:
  • Bx (float) – the x (easterly) component of the magnetic field (nT)
  • By (float) – the y (northerly) component of the magnetic field (nT)
  • Bz (float) – the z (vertical, up positive) component of the magnetic field (nT)
Returns:

  • H the horizontal magnetic field (nT)
  • F the total magnetic field (nT)
  • D the declination of the field (degrees east of north)
  • I the inclination of the field (degrees down from horizontal)

flattening()

The flattening of the ellipsoid.

This is the value inherited from the Geocentric object used in the constructor.

magnetic_file()

Full file name used to load the magnetic model.

magnetic_model_directory()

Directory used to load the magnetic model.

magnetic_model_name()

Name used to load the magnetic model.

The ‘name’ used to load the magnetic model (from the first argument of the constructor, but this may be overridden by the model file).

major_radius()

The equatorial radius of the ellipsoid (meters).

This is the value of ‘a’ inherited from the Geocentric object used in the constructor.

max_height()

Maximum height.

The maximum height above the ellipsoid (in meters) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed heights, no check of t argument is made by the MagneticFieldModel.__call__() operator.

max_time()

The maximum time (in years) for which this model should be used.

Because the model will typically provide useful results slightly outside the range of allowed times, no check of the t argument is made by the MagneticFieldModel.__call__() operator.

min_height()

Minimum height.

The minimum height above the ellipsoid (in meters) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed heights, no check of t argument is made by the MagneticFieldModel.__call__() operator.

min_time()

The minimum time (in years) for which this model should be used.

Because the model will typically provide useful results slightly outside the range of allowed times, no check of t argument is made by the MagneticFieldModel.__call__() operator.

Functions

geomodels.lib_version_info()

Return the (major, minor, patch) version of GeographicLib.

Note

the returned information refers to the version of the GeographicLib library used at build time. The version of the shared library actually used at runtime could be different.

geomodels.lib_version_str()

Return the version string of GeographicLib.

Note

the returned information refers to the version of the GeographicLib library used at build time. The version of the shared library actually used at runtime could be different.

geomodels.test(verbosity: int = 1, failfast: bool = False)[source]

Run the test suite for the geomodels package.

Parameters:
  • verbosity (int) – verbosity level (higher is more verbose). Default: 1.
  • failfast (bool) – stop the test run on the first error or failure. Default: False.