# Driftless coordinate transformations

Open `/transform` from the file checker or a job’s coordinate settings. This is an advanced English-language tool in the free proof-of-concept phase. Payment collection remains disabled.

## Workflow

1. Choose the exact source and target EPSG definitions from the survey records. Search by code, name or region. The catalog contains 7,199 non-deprecated EPSG definitions; listing a definition does not guarantee a usable operation.
2. Enter geographic job bounds, required registry operation accuracy and, for dynamic references, the observation epoch. Bounds use decimal degrees east of Greenwich. Review available operations and their effective input/output axes. Some projected systems use westing/southing or southing/westing.
3. Explicitly download any required open grid offered from PROJ. The tool refuses missing grids and ballpark operations. It does not silently choose a less accurate fallback. Registry accuracy describes the operation, not the observations or final survey accuracy; an unspecified value is identified explicitly.
4. Read a CSV/TXT file with `id,x,y,z` columns (comma, semicolon or tab delimiter; decimal point or comma; no grouping separators). Use longitude/latitude in decimal degrees east of Greenwich for geographic coordinates, regardless of the reference’s native angular units or prime meridian. Native grads, DMS or Paris-relative longitudes must first be expressed in this input convention. Projected/geocentric coordinates use the operation’s displayed axes and native linear units. Do not confuse US survey feet with international feet.
5. Transform, inspect, and download both the CSV and JSON operation report. Preserve the source file. For existing Driftless job workflows, review the CSV and explicitly set the destination reference/units when importing; this tool does not rewrite existing jobs automatically. Geographic or geocentric output is not a planar surface/quantity input.

Horizontal mode requires two-dimensional references and preserves the supplied Z without converting its units or vertical datum. Three-dimensional mode requires explicit 3D or compound references and a finite Z on every point. Supported vertical grid operations convert heights; entering a horizontal datum name alone does not define a height reference.

Observation epochs are passed to time-dependent frame operations. Propagation from one coordinate epoch to another is deliberately refused until a separately verified point-motion model is implemented. This release does not promise arbitrary epoch propagation.

## Custom site grids

Provide 3–100 fitting controls, 1–100 independent check points, both grid names/units and a tolerance in target units. Each control has source x/y and target X/Y. The model fits translation, rotation and uniform scale using a centered two-dimensional similarity. It reports fitting and independent check residuals, RMS, parameters, source controls and coverage.

All fitting/check residuals must meet the chosen tolerance. Check and application points must lie inside the fitting-control convex hull. Duplicate source positions and collinear coverage are refused. The model does not transform elevation or establish a national datum relationship. A user must ensure check points are independently observed; the tool can check distinct coordinates, not how observations were collected.

## Processing and limits

The PROJ 9.8.1 C engine runs in a dedicated WebAssembly worker on the user’s device. The raw Emscripten runtime and database are pinned from `proj-wasm@0.1.0-alpha9`; the package’s higher-level experimental JS API is not used. The EPSG database reports v12.029. `vendor/provenance.json` records exact source asset hashes; reports include the database hash, selected pipeline, accuracy, coverage, grid names/hashes, axes, angular normalization, options, epoch, and original/transformed points. The raw pipeline uses native normalized CRS units; reproduce the report’s angular pre/post conversions as well when independently replaying it.

No coordinates or files are uploaded. Requested grid filenames can reveal the region to `cdn.proj.org`. Native PROJ networking is disabled; only explicitly selected open-license grid URLs on that host are fetched, without redirects. Limits are 10 MB / 50,000 points, 32 MB per grid, 64 MB of grids per session, and a 90-second worker timeout. Required grids above those limits or unavailable/restricted grids are unsupported in this browser release. Reloading clears loaded grids, inputs and results. Tool action counts persist locally for at most 90 days and omit coordinates/CRS names; they are not centralized customer-demand evidence. Document page loads are separately counted in protected server-side daily aggregates without visitor identifiers; see `/privacy`. Feedback is a downloadable note, sent only if the user chooses to share it.

## Validation references

Automated tests exercise the actual vendored PROJ engine and pinned offline grid fixtures:

- Northern and southern UTM coordinates from the [PROJ UTM documentation](https://proj.org/en/stable/operations/projections/utm.html), within 0.01 m of the rounded examples.
- DHDN/ETRS89 BETA2007 horizontal shift and EGM96 height correction from [PROJ’s EUREF grid-shift exercise](https://proj.org/en/stable/tutorials/EUREF2019/exercises/gridshift.html), including refusal before required grids load and inverse height recovery.
- ITRF2014 observation-epoch conversion to GDA2020 against the [PROJ GDA/ICSM regression reference](https://github.com/OSGeo/PROJ/blob/9.8.1/test/gie/GDA.gie), within 0.00004 m of the rounded reference vector. This tests implementation consistency, not real-world observation accuracy.
- Paris prime-meridian/grad normalization with forward/inverse and deliberately wrong bounds; South African westing/southing and Krovak southing/westing axis reporting/round trips; US survey-foot conversion within 0.0002 m (the paired EPSG false eastings differ by 0.0001016 m).
- Analytical local similarities with held-out checks, large coordinate origins, rejected extrapolation, failed residuals and degenerate controls. Invalid coordinates, changed operations, missing heights/epochs and unsupported epoch propagation refuse output.

These are representative numerical and failure-path checks, not certification of every registry operation, browser or mobile device. Run repository tests with `npm test`. Grid fixtures are stored under `tests/fixtures/proj-grids` with upstream license notices and fixed SHA-256 checks. PROJ API behavior is documented in the [C API reference](https://proj.org/en/stable/development/reference/functions.html).

## Runtime and release

Assets live in `public/transform`, the entry route in `app/transform`, and integration links in the checker and job coordinates editor. The existing Sites/Vinext deployment serves the static worker, database and WASM; no new database schema, backend service, payment service or AI inference API is required. The existing production monitor probes the page and worker. The runtime depends on modern module-worker, WebAssembly and Web Crypto support. Browser UI/mobile acceptance remains a separate validation step.

PROJ contributors (2026), Open Source Geospatial Foundation, https://proj.org/. See `vendor/THIRD-PARTY-NOTICES.md`, `vendor/LICENSE-PROJ.txt`, and grid-specific notices for redistribution terms.