geodetic-engine

Coordinate transformations you can defend.

geodetic-engine is a Python library built on PROJ and pyproj. PROJ does the arithmetic. This package decides whether PROJ’s answer can be trusted, refuses it when it cannot, and records exactly how every coordinate was produced.

from geodetic_engine.geodesy import transform

result = transform("EPSG:4230", "EPSG:4326", (2.5, 63.5), operation="EPSG:1612")
result.coordinates      # ((2.49818..., 63.49961...),)  lon, lat in degrees
result.operation.name   # 'ED50 to WGS 84 (23)'
result.pipeline         # the exact PROJ pipeline that ran

A wrong coordinate that looks right is worse than an error, because nobody checks it again. So a datum change must name its operation, a ballpark approximation is refused, a missing grid is an error, and a time-dependent operation needs a coordinate epoch.

What the package does

• Transforms coordinates with a stated operation. Between geographic, projected, vertical, compound and engineering CRSs, from EPSG or from your own definitions. A datum change names its transformation, and the one named is the one applied.

• Refuses results it cannot vouch for. Ballpark approximations, a missing grid, a time-dependent operation without a coordinate epoch: each raises an error that says what was wrong, instead of returning a plausible number.

• Records provenance. Every result carries the applied operation, its accuracy, the grids used, the coordinate epoch, the exact PROJ pipeline, and fingerprints of the proj.db that answered, so a result can be reproduced and audited later.

• Reads and writes OSDU persistableReferences, and transforms with exactly the CRS or operation a payload states.

• Builds custom PROJ databases. Adds an organisation’s CRSs and transformations, from a Georepository register or an OSDU catalogue, to a validated copy of PROJ’s proj.db.

• Works around known PROJ and EPSG problems, such as engineering CRS axis order, and documents each workaround with the condition for removing it.

Modules

Module	Purpose
geodetic_engine.geodesy	Transformations, CRS inspection, operation lookup, results and provenance
geodetic_engine.persistablereference	Parse and emit OSDU persistableReference payloads
geodetic_engine.georepository	Authenticated client for a Georepository API
geodetic_engine.projdb	Build a proj.db from a Georepository register (geodetic-projdb)
geodetic_engine.osdudb	Build a proj.db from an OSDU catalogue (geodetic-osdudb)

PROJ does all the numerical work. The package is a layer over pyproj that decides which operation runs, checks the result, and records how it was produced. It is a library, not a service: transformations run locally and never contact the Georepository. See Architecture.

When to use it

Use it when you must be able to say which operation produced a coordinate, with what accuracy, and from which database. Use plain pyproj when PROJ may pick the operation for you and an unstated accuracy is acceptable, for example when drawing a map. Design guarantees lists what this package does differently from pyproj.

Requirements

• Python 3.13 or later.

• PROJ 9.9.0 and pyproj 3.8.0, built against each other. The EPSG dataset in proj.db is part of every answer, so the versions are pinned. The devcontainer installs both; see Installation.

• Licensed under Apache 2.0.

Start here

Getting started

Install the pinned PROJ and pyproj, transform your first point, and learn the ideas the rest of the documentation assumes you know.

Getting started

User guide

Task-oriented guides for every module: transformations, OSDU persistableReferences, the Georepository client, and custom proj.db builds.

User guide

Examples

Worked notebooks that run during every documentation build, so every number shown is real output.

Examples

API reference

Every public class and function, generated from the docstrings.

API reference

Command-line tools

geodetic-projdb and geodetic-osdudb: every option, with the example configuration files.

Command-line tools

Known issues and workarounds

What this package works around in PROJ and the EPSG dataset, why, and when each workaround can be removed.

Known issues and workarounds

Where to find what

I want to…	Go to
Transform coordinates between two CRSs	Conversions and transformations
Find out which operations exist between two CRSs	Choosing an operation
Understand why my transformation was refused	Errors and refusals
Read or write an OSDU persistableReference	Persistable references (OSDU)
Add my organisation’s CRSs and transformations to PROJ	Custom PROJ database
Know what the package does differently from plain pyproj	Design guarantees
Look up a term such as bound CRS or ballpark	Glossary