{"id":6796,"library":"pygeodesy","title":"PyGeodesy","description":"PyGeodesy is a pure Python implementation of geodesy tools for various ellipsoidal and spherical earth models. It offers precision exact, elliptic, trigonometric, vector-based, iterative, and approximate methods for geodetic (lat-/longitude), geocentric (ECEF cartesian), local (LTP), and certain triaxial ellipsoidal coordinates. The library provides functionalities for computing distance, area, bearing, intersections, resections, and conversions across various coordinate systems and earth models. The current version is 26.3.26, and it is actively maintained with frequent updates.","status":"active","version":"26.3.26","language":"en","source_language":"en","source_url":"https://github.com/mrJean1/PyGeodesy","tags":["geodesy","geospatial","latitude","longitude","distance","ellipsoid","spherical","coordinates"],"install":[{"cmd":"pip install pygeodesy","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for certain advanced functionalities like Cassini-Soldner classes (`css`) and some features within `ellipsoidalKarney` (e.g., LatLon/Cartesian classes and `areaOf`/`perimeterOf` functions). While PyGeodesy is pure Python, `geographiclib` is a Python wrapper around C++ code.","package":"geographiclib","optional":true},{"reason":"Used for optimized array operations and certain geometric calculations. Can be excluded from import via `PYGEODESY_XPACKAGES` environment variable.","package":"numpy","optional":true},{"reason":"Used for some interpolation and scientific computing tasks. Can be excluded from import via `PYGEODESY_XPACKAGES` environment variable.","package":"scipy","optional":true}],"imports":[{"note":"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.","wrong":"from pygeodesy import LatLon","symbol":"LatLon","correct":"from pygeodesy.ellipsoidalVincenty import LatLon"},{"note":"Some top-level utilities are available directly from the `pygeodesy` package, but most geometric classes are found in specific model submodules.","symbol":"GeoidKarney","correct":"from pygeodesy import GeoidKarney"}],"quickstart":{"code":"from pygeodesy.ellipsoidalVincenty import LatLon\n\n# Define two geographic points (latitude, longitude)\npoint1 = LatLon(41.49008, -71.312796) # Newport, RI\npoint2 = LatLon(41.499498, -81.695391) # Cleveland, OH\n\n# Calculate the geodesic distance between the two points\ndistance = point1.distanceTo(point2)\n\nprint(f\"Distance between Newport, RI and Cleveland, OH: {distance:,.2f} meters\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions where `geographiclib`-dependent features are used."},{"fix":"Always import classes from their specific submodules, for example: `from pygeodesy.ellipsoidalVincenty import LatLon` or `from pygeodesy.sphericalNvector import LatLon`.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Consult the PyGeodesy documentation for details on setting up and configuring external Karney C++ utilities if enhanced performance or specific functionality is required.","message":"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.","severity":"gotcha","affected_versions":"All versions supporting external C++ utility integration."},{"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:`.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}