{"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":"python","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,"search_vec":"'/longitude':34 '26.3.26':69 'across':58 'activ':73 'approxim':29 'area':52 'base':26 'bear':53 'cartesian':37 'certain':41 'comput':50 'convers':57 'coordin':44,60,85 'current':66 'distanc':51,82 'earth':16,63 'ecef':36 'ellipsoid':13,43,83 'ellipt':22 'exact':21 'frequent':76 'function':48 'geocentr':35 'geodesi':9,78 'geodet':32 'geospati':79 'implement':7 'intersect':54 'iter':27 'lat':33 'latitud':80 'librari':46 'local':38 'longitud':81 'ltp':39 'maintain':74 'method':30 'model':17,64 'offer':19 'precis':20 'provid':47 'pure':5 'pygeodesi':1,2 'python':6 'resect':55 'spheric':15,84 'system':61 'tool':10 'triaxial':42 'trigonometr':23 'updat':77 'various':12,59 'vector':25 'vector-bas':24 'version':67","created_at":"2026-04-15T18:43:21.324779+00:00","updated_at":"2026-04-16T18:27:46.812660+00:00","problems":[{"fix":"Install the package using pip: `pip install pygeodesy`","cause":"The 'pygeodesy' package is not installed in the current Python environment, or there's a typo in the import statement.","error":"ModuleNotFoundError: No module named 'pygeodesy'"},{"fix":"Validate input coordinates to ensure latitudes are between -90 and 90 degrees and longitudes are between -180 and 180 degrees, and conform to any specific function documentation regarding limits.","cause":"Input latitude or longitude values provided to a pygeodesy function or class constructor are outside their valid geodetic range (e.g., latitude > 90 or < -90, longitude > 180 or < -180) or exceed specific function limits.","error":"RangeError: lat- or longitude values outside the clip, clipLat, clipLon"},{"fix":"Refer to the official pygeodesy documentation for the specific class or module being used to verify the correct method names and available attributes, ensuring compatibility with the chosen earth model or coordinate type.","cause":"An attempt was made to access a non-existent method or attribute on a pygeodesy object (e.g., a LatLon instance), or to set a read-only property defined by the library.","error":"AttributeError: 'LatLon' object has no attribute 'some_method'"},{"fix":"Install the 'geographiclib' package using pip: `pip install geographiclib`","cause":"Certain pygeodesy modules or classes, particularly those using Karney's exact geodesic methods (e.g., `ellipsoidalKarney`), require the 'geographiclib' package, which is not installed.","error":"ModuleNotFoundError: No module named 'geographiclib'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"26.6.12","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://GitHub.com/mrJean1/PyGeodesy","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pygeodesy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}