GeographicLib

2.1 · active · verified Fri Apr 10

GeographicLib is a Python implementation of the geodesic routines from the larger C++ GeographicLib library. It provides accurate algorithms for solving direct and inverse geodesic problems, as well as calculating areas on an ellipsoid model of the Earth. The current version is 2.1, and it maintains a regular release cadence with updates tagged in its GitHub repository.

Common errors

```
ModuleNotFoundError: No module named 'geographiclib'
```
cause The `geographiclib` Python package is not installed in your current Python environment, or the environment where you're running your code is not the one where it was installed.

fix Install the library using pip: `pip install geographiclib`
```
ImportError: No module named geographiclib.geodesic
```
cause The `geographiclib` package is either not installed or not correctly installed, preventing the `geodesic` submodule from being found.

fix Ensure the library is installed with `pip install geographiclib`. If already installed, there might be an environment issue, or a conflict; try reinstalling or checking your Python path.
```
ValueError: Equatorial radius is not positive
```
cause This error occurs when initializing a `Geodesic` object with an equatorial radius (parameter `a`) that is not a positive finite number.

fix Ensure that the `a` (equatorial radius) and `f` (flattening) parameters provided to `Geodesic` are valid positive floating-point numbers, for example, `Geodesic(a=6378137, f=1/298.257223563)`.
```
GeographicLib.GeographicException: Error reading ... egm96-5.pgm: Index was outside the bounds of the array.
```
cause This error typically occurs when performing geoid height calculations using `Geoid` models, indicating that the required geoid data file (e.g., `egm96-5.pgm`) is either missing, corrupted, or not correctly accessible at the specified path, or the coordinates requested are outside the bounds of the loaded geoid model data.

fix Ensure the geoid data files are correctly downloaded and placed in a directory where `GeographicLib` can find them. For C++ GeographicLib, this is often `/usr/share/GeographicLib/geoids` or a custom path. For Python, ensure the `Geoid` constructor is pointed to the correct data directory if not using the default. Also, if using `NETGeographicLib` in a multi-threaded context, pre-caching the geoid file using `CacheAll()` can resolve concurrency issues.

Warnings

breaking Version 2.0 dropped support for Python 2.x. Users must upgrade to Python 3.7 or newer to use `geographiclib` version 2.0 and later.
Fix: Migrate your Python environment to Python 3.7+.
gotcha Since version 1.48, the default range for returned longitudes and azimuths changed from `[-180°, 180°)` to `(-180°, 180°]`. Code relying on the exact boundary behavior (e.g., expecting -180° instead of 180° for certain cases) might need adjustment.
Fix: Review code that processes longitude or azimuth values near the ±180° boundary and adjust for the new range if necessary.
breaking Version 2.1 fixed an issue where the `Geodesic.WGS84` attribute might not have been accessible. If you had workarounds for this, they might now be obsolete or cause unexpected behavior.
Fix: Remove any custom workarounds for `Geodesic.WGS84` attribute access and use it directly as intended.
gotcha Version 2.0 introduced a more careful treatment of ±0° and ±180° for longitudes and azimuths. Positive values (+0°, +180°) are now reckoned as east-going, while negative values (-0°, -180°) are west-going. This can subtly affect calculations involving these edge cases.
Fix: Be aware of the directional implications of positive and negative zero/180° in your calculations, especially for precise azimuth tracking or area computations involving `LONG_UNROLL`.

Install

pip install geographiclib Install with pip

Imports

Geodesic
```
from geographiclib.geodesic import Geodesic
```
Primary class for geodesic calculations.
GeodesicLine
```
from geographiclib.geodesicline import GeodesicLine
```
For creating geodesic lines and computing waypoints.
PolygonArea
```
from geographiclib.polygonarea import PolygonArea
```
For measuring areas of geodesic polygons.

Quickstart

This quickstart demonstrates how to use the `Geodesic` class to calculate the inverse (distance and azimuth between two points) and direct (finding a point given a starting point, azimuth, and distance) geodesic problems using the WGS84 ellipsoid.

from geographiclib.geodesic import Geodesic

# Define the WGS84 ellipsoid
geod = Geodesic.WGS84

# Solve the inverse geodesic problem (distance and azimuth between two points)
# From Wellington, NZ (-41.32, 174.81) to Salamanca, Spain (40.96, -5.50)
g = geod.Inverse(-41.32, 174.81, 40.96, -5.50)
print(f"The distance is {g['s12']:.3f} meters.")

# Solve the direct geodesic problem (find a point at a given distance and azimuth)
# 20000 km SW of Perth, Australia (-32.06, 115.74)
g = geod.Direct(-32.06, 115.74, 225, 20000e3)
print(f"The position is ({g['lat2']:.8f}, {g['lon2']:.8f}).")

view raw JSON →