proj-rust

Pure-Rust coordinate transformation library. The default library surface has no C libraries, no build scripts, and no unsafe code.

Crates

• proj-core: CRS definitions, operation selection, projection math, datum shifts, grid sampling, and transforms.
• proj-epsg-format: the zero-dependency binary layout shared by the embedded EPSG registry reader and generator.
• proj-wkt: parsing for EPSG codes, WKT, PROJ strings, PROJJSON, and a small Proj compatibility facade.

Usage

use proj_core::{Bounds, Transform};

let t = Transform::new("EPSG:4326", "EPSG:3857").unwrap();
let (x, y) = t.convert((-74.006, 40.7128)).unwrap();

let inv = t.inverse().unwrap();
let (lon, lat) = inv.convert((x, y)).unwrap();

let coords = vec![(-74.006, 40.7128); 1000];
let projected = t.convert_batch(&coords).unwrap();

let (x3, y3, z3) = t.convert_3d((-74.006, 40.7128, 15.0)).unwrap();

let bounds = Bounds::new(-74.3, 40.45, -73.65, 40.95);
let projected_bounds = t.transform_bounds(bounds, 8).unwrap();

Coordinates use CRS-native units:

• Geographic CRS coordinates are longitude/latitude in degrees.
• Projected CRS coordinates use the CRS linear unit, such as metres or US survey feet.
• Without explicit vertical components, convert_3d() treats z as ellipsoidal height: projection-only paths preserve it, while horizontal datum shifts can change it. Explicit vertical components preserve, convert, or transform z according to their declared reference frames and units.

Strict transform constructors reject a compound-to-2D CRS pair because that would silently discard an explicit vertical reference. For an intentionally XY-only operation, use Transform::new_horizontal("EPSG:5845", "EPSG:4326"); the returned transform uses EPSG:5845's EPSG:3006 horizontal component.

With the default geo-types feature, Transform also supports geo_types::Coord<f64> and full 2D geometry conversion through convert_geometry().

CRS Input

proj-core accepts registry-backed EPSG codes such as "EPSG:4326" and "EPSG:3857".

proj-wkt accepts:

• EPSG authority codes, bare EPSG numbers, EPSG URNs, and OGC CRS:84.
• Common PROJ strings for the implemented projection families, including legacy +init=epsg:XXXX.
• WKT1 and supported WKT2 geographic/projected CRS definitions.
• WKT1 COMPD_CS and WKT2 COMPOUNDCRS definitions with explicit vertical components.
• Basic PROJJSON geographic, projected, and compound CRS definitions.

Custom definitions are accepted only when they map to this library's CRS model: longitude/east, latitude/north geographic axes in degrees with a Greenwich prime meridian, and projected easting/northing axes in a single linear unit. EPSG-tagged WKT1 definitions may use the authority-native axis order; a pure axis permutation is canonicalized to the library's coordinate order after the embedded definition is validated against the registry. Unsupported custom axis order, axis directions, prime meridian, angular unit, projection, or vertical transformation semantics return errors.

Supported CRS

Transform::new() and Transform::from_crs_defs() select the best supported operation for a CRS pair. Use Transform::with_selection_options() or Transform::from_crs_defs_with_selection_options() to set an area of interest, require grid-backed operations, require exact area matches, provide a GridProvider, select an explicit registry operation, or provide explicit custom horizontal CoordinateOperation candidates.

Operation selection candidates come only from the embedded registry, deterministic generated-registry records, explicit caller/parser-provided coordinate operations, and internal identity/no-datum-operation behavior. Selection does not synthesize Helmert, grid, or WGS84-compatible identity operations from datum metadata. CRS pairs without a registry/generated-registry operation, explicit operation, or identity path fail during transform construction.

Grids

Horizontal NTv2 grid shifts are supported through embedded registry operations, parsed PROJ +nadgrids definitions built with proj-wkt transform helpers or the Proj facade, EmbeddedGridProvider, FilesystemGridProvider, and custom GridProvider implementations.

Vertical GTX geoid operations are supported for registry-backed ellipsoidal-to-gravity height pairs and explicit VerticalGridOperation values. Grid files are resolved through a caller-provided FilesystemGridProvider or custom GridProvider; geoid grid files are not bundled.

With the geotiff feature, PROJ-format GeoTIFF/COG grids (.tif, as distributed on the PROJ CDN) are decoded for both horizontal (NTv2-equivalent latitude/longitude offsets, including nested subgrids) and vertical (geoid undulation) shifts. This enables grid-based transforms such as RDNAPTRANS™2018 — ETRS89/WGS 84 3D (EPSG:4979) to RD New + NAP height (EPSG:7415) — matching PROJ to sub-millimetre. Supply the nl_nsgi_rdtrans2018.tif and nl_nsgi_nlgeo2018.tif grids through a FilesystemGridProvider:

use std::sync::Arc;
use proj_core::{FilesystemGridProvider, SelectionOptions, Transform};

let provider = Arc::new(FilesystemGridProvider::new(vec!["/path/to/grids".into()]));
let options = SelectionOptions::new().with_grid_provider(provider);
let t = Transform::with_selection_options("EPSG:4979", "EPSG:7415", options).unwrap();
let (rd_x, rd_y, nap) = t.convert_3d((6.605585, 53.294378, 50.0)).unwrap();

Grid diagnostics expose selected operation metadata and resolved grid SHA-256 checksums.

Feature Flags

Development

cargo test --workspace
cargo test -p proj-core --no-default-features
cargo clippy --workspace --all-targets -- -D warnings

The optional c-proj-compat feature and gen-reference tool intentionally use bundled C PROJ/sqlite for reference comparisons and registry generation; they are not part of the default library surface.

The embedded EPSG registry is generated from the bundled PROJ proj.db:

cargo run --manifest-path gen-reference/Cargo.toml --bin gen-registry
./scripts/check-registry-generation.sh

During generation, supported PROJ grid alternatives can be composed with known zero/identity bridge operations to create deterministic generated coordinate operations when EPSG source or target CRS definitions need bridging.

Reference comparisons and benchmark results are in docs/benchmark-report.md.

License

MIT OR Apache-2.0