Worksite Coordinate Engine
A C++17 library that converts WGS84 geographic positions into local worksite coordinates, calibrates site grids from paired controls, and validates numerical behavior through automated reference and integration tests.
Project gallery
Captures of the synthetic demonstration report; no field measurements or machine deployment are represented. 3 images. Select an image to view it full size.
My contribution
I built the C++17 library, its C and Python interfaces, and its validation suite as an independent work sample, with Codex assistance on implementation and documentation. The demonstration data is synthetic; the library has not been validated with field GNSS observations or deployed on a machine.
Result: Recorded runs pass 38,612 native numerical assertions on Windows and Linux and 40 Python tests, and the PROJ reference comparison recorded 47,536 assertions with zero failures. In the synthetic demonstration, one corrupted control raised the maximum withheld-point error from 3.401 mm to 64.844 mm.
Tools
- C++17
- C ABI
- Python
- Geodesy
- Coordinate transformations
- Numerical validation
- PROJ / pyproj (validation only)
- GitHub Actions
This is an engineering prototype with synthetic data. It has not been validated with field GNSS observations, deployed on an autonomous machine, or tested through QGIS or ROS integration. Agreement with a reference implementation is not a positioning-accuracy specification, and the library reports a bad control without removing it.
A clean conversion is not a good calibration
Small conversion errors do not guarantee a well-calibrated grid. Incorrect control coordinates can distort the fitted transform even when the numerical conversion is internally consistent. The project makes that distinction visible through residuals and withheld checkpoints.
One core, three ways in
The numerical core implements documented mathematical formulas. PROJ is used through pyproj only for independent comparisons during validation; it is not a runtime dependency of the coordinate engine.
- Geographic coordinates: forward and reverse latitude, longitude, and ellipsoidal height (LLH) and Earth-centered, Earth-fixed (ECEF) conversions.
- Local frames: East-North-Up (ENU) and North-East-Down (NED) with an explicit geographic origin.
- Worksite grid: reversible horizontal rotation, positive scale, and translation, with a separate vertical offset.
- Control calibration: weighted fitting from paired local and site controls, with residuals, RMSE, and control-spread diagnostics.
- Projected coordinates: bounded WGS84 UTM with an explicit zone, plus projection scale and meridian convergence.
- Integration: a C++ API, a versioned C ABI that contains C++ exceptions, a typed Python interface, site-definition JSON, and a CSV workflow that writes to temporary files so existing data survives a failed run.
Demonstration: one bad control point
A synthetic site near 33° N, 97° W is fitted from eight controls, with two more withheld from fitting and 361 simulated machine positions forming a trajectory. A second fit adds a known error to one control while keeping every control in the fit.
With clean controls, the horizontal RMSE is 6.744 mm and the largest error at the withheld points is 3.401 mm. With one corrupted control, the largest withheld-point error rises to 64.844 mm. The errors are measured against known synthetic truth; the library reports the effect but does not remove the corrupted control.
How the numbers are checked
Calibration uses anchored scaling and compensated sums to reduce cancellation and overflow, and the tests cover extreme weights, degeneracy, boundaries, and reordered controls. Seeded fixtures and source and artifact hashes tie recorded results to their inputs.
- Native numerical suite: 38,612 assertions passed in recorded Windows and Linux runs.
- Python suite: 40 tests covering integration, validation workflows, and review-package integrity.
- PROJ reference comparison: 47,536 assertions with zero failures in the recorded Windows report.
- Hosted CI: the numerical validation workflow passed on windows-2025 and ubuntu-24.04.
- Integration: installed C and C++ consumers and an installed Python wheel passed recorded smoke checks.
Technical details
Independent work sample · Codex-assisted prototype · Version 0.1.1, synthetic demonstration
A geographic position and a worksite coordinate describe location in different ways. Latitude, longitude, and ellipsoidal height locate a point on and above an Earth model; a site grid describes it relative to a local origin, orientation, scale, and offset. Connecting them requires explicit conventions and reliable forward and reverse transformations.
- Implement forward and reverse conversions between LLH, ECEF, and local ENU and NED frames from documented formulas.
- Build a reversible site grid with horizontal rotation, positive scale, translation, and a separate vertical offset.
- Fit site grids from paired controls with weighted calibration, reporting residuals, RMSE, and control-spread diagnostics.
- Expose the core through a C++ API, a versioned C ABI, a typed Python interface, site-definition JSON, and a CSV workflow.
- Validate against analytical fixtures, boundary cases, invalid inputs, round trips, and PROJ reference comparisons in CI on Windows and Ubuntu.