PyGeodesy

Warnings

• gotcha Some powerful functionalities, like those in `ellipsoidalKarney` and `css` modules, critically depend on the `geographiclib` library. While `pygeodesy` itself is pure Python, `geographiclib` is a Python wrapper around a C++ library. Users expecting a fully pure-Python solution for all features might encounter `ImportError` if `geographiclib` is not installed for these specific use cases.
  Fix: Ensure `geographiclib` is installed (`pip install geographiclib`) if you plan to use features that rely on it. Check the documentation for specific module dependencies.
• gotcha PyGeodesy extensively uses lazy importing, organizing classes like `LatLon` and `Cartesian` within specific model submodules (e.g., `ellipsoidalVincenty`, `sphericalTrigonometry`). Attempting to import these classes directly from the top-level `pygeodesy` package (e.g., `from pygeodesy import LatLon`) will typically fail or lead to unexpected behavior.
  Fix: Always import classes from their specific submodules, for example: `from pygeodesy.ellipsoidalVincenty import LatLon` or `from pygeodesy.sphericalNvector import LatLon`.
• gotcha Certain advanced features, such as some `azimuthal` projections or calculations in `rhumb.solve`, can leverage external Karney's C++ utilities (`GeodSolve`, `RhumbSolve`). While optional, configuring these executables via environment variables (`PYGEODESY_GEODSOLVE`, `PYGEODESY_RHUMBSOLVE`) can provide improved performance or access to specific capabilities not available in the pure Python implementation.
  Fix: Consult the PyGeodesy documentation for details on setting up and configuring external Karney C++ utilities if enhanced performance or specific functionality is required.
• gotcha PyGeodesy defines a comprehensive set of specific exception types within its `pygeodesy.errors` module (e.g., `GeodesicError`, `RangeError`, `IntersectionError`). Catching a generic `Exception` may obscure the root cause of issues, such as convergence failures in geodesic calculations, out-of-range coordinate values, or unresolved geometric intersections.
  Fix: Implement specific exception handling for relevant `pygeodesy.errors` classes to robustly manage common geodetic failure scenarios and provide clearer diagnostics. For example, `try...except GeodesicError:`.

Install

• pip install pygeodesy Install stable version

Imports

• LatLon
  wrong:

  from pygeodesy import LatLon

  correct:

  from pygeodesy.ellipsoidalVincenty import LatLon

  PyGeodesy employs lazy importing and organizes classes within specific submodule models (e.g., `ellipsoidalVincenty`, `ellipsoidalKarney`, `sphericalTrigonometry`). Directly importing a class like `LatLon` from the top-level `pygeodesy` package is incorrect and will result in an `ImportError` or unexpected behavior.
• GeoidKarney

  from pygeodesy import GeoidKarney

  Some top-level utilities are available directly from the `pygeodesy` package, but most geometric classes are found in specific model submodules.

Quickstart

This quickstart calculates the geodesic distance between two points using the Vincenty formulae, which is suitable for ellipsoidal earth models. It demonstrates the direct import of the `LatLon` class from a specific ellipsoidal model submodule and its `distanceTo` method.

from pygeodesy.ellipsoidalVincenty import LatLon

# Define two geographic points (latitude, longitude)
point1 = LatLon(41.49008, -71.312796) # Newport, RI
point2 = LatLon(41.499498, -81.695391) # Cleveland, OH

# Calculate the geodesic distance between the two points
distance = point1.distanceTo(point2)

print(f"Distance between Newport, RI and Cleveland, OH: {distance:,.2f} meters")