proj_core/
lib.rs

1#![forbid(unsafe_code)]
2
3//! Pure-Rust coordinate transformation library.
4//!
5//! No C dependencies, no unsafe, WASM-compatible.
6//!
7//! The primary type is [`Transform`], which provides CRS-to-CRS coordinate
8//! transformation using authority codes (e.g., `"EPSG:4326"`).
9//! For area-aware or policy-constrained selection, use
10//! [`Transform::with_selection_options`] and inspect
11//! [`Transform::selected_operation`] /
12//! [`Transform::selection_diagnostics`].
13//! The default [`SelectionPolicy::BestAvailable`] policy does not synthesize
14//! approximate Helmert datum-shift fallbacks; opt in with
15//! [`SelectionOptions::allow_approximate_helmert_fallback`] when that
16//! last-resort behavior is acceptable.
17//! The [`registry`], [`operation`], and [`grid`] modules expose the embedded
18//! operation catalog, selection metadata, and NTv2 grid-provider interfaces.
19//! `convert_3d` preserves `z` when no explicit vertical CRS is present or when
20//! source and target compound CRS definitions have identical vertical
21//! components. It converts `z` units when both vertical components use the same
22//! vertical reference frame with different linear units. Registry-backed GTX
23//! geoid operations can be selected for supported ellipsoidal-to-gravity height
24//! CRS pairs, while grid files still resolve through caller-supplied grid
25//! providers.
26//! Geographic antimeridian AOIs use
27//! [`AreaOfInterest::geographic_wrapped_bounds`], while ordinary projected and
28//! source/target bounds keep strict `min <= max` validation.
29//! With the default `geo-types` feature, [`Transform::convert_geometry`]
30//! transforms whole 2D `geo-types` geometries and fails on the first invalid
31//! coordinate without returning partial results.
32//!
33//! # Example
34//!
35//! ```
36//! use proj_core::Transform;
37//!
38//! // Create a transform from WGS84 geographic to Web Mercator
39//! let t = Transform::new("EPSG:4326", "EPSG:3857").unwrap();
40//!
41//! // Transform NYC coordinates (lon, lat in degrees) → (x, y in meters)
42//! let (x, y) = t.convert((-74.006, 40.7128)).unwrap();
43//! assert!((x - (-8238310.0)).abs() < 100.0);
44//!
45//! // Inverse: Web Mercator → WGS84
46//! let inv = Transform::new("EPSG:3857", "EPSG:4326").unwrap();
47//! let (lon, lat) = inv.convert((x, y)).unwrap();
48//! assert!((lon - (-74.006)).abs() < 1e-6);
49//! ```
50
51pub mod coord;
52pub mod crs;
53pub mod datum;
54pub mod ellipsoid;
55mod epsg_db;
56pub mod error;
57mod geocentric;
58pub mod grid;
59mod helmert;
60pub mod operation;
61mod projection;
62pub mod registry;
63mod selector;
64pub mod transform;
65
66pub use coord::{
67    Bounds, Coord, Coord3D, Transformable, Transformable3D, MAX_BOUNDS_DENSIFY_POINTS,
68};
69pub use crs::{
70    CompoundCrsDef, CrsDef, GeographicCrsDef, HorizontalCrsDef, LinearUnit, ProjectedCrsDef,
71    ProjectionMethod, VerticalCrsDef, VerticalCrsKind,
72};
73pub use datum::{Datum, DatumGridShift, DatumGridShiftEntry, DatumToWgs84, HelmertParams};
74pub use ellipsoid::Ellipsoid;
75pub use error::{Error, Result};
76pub use grid::{
77    EmbeddedGridProvider, FilesystemGridProvider, GridDefinition, GridError, GridFormat,
78    GridHandle, GridProvider, GridSample, VerticalGridSample,
79};
80pub use operation::{
81    AreaOfInterest, AreaOfInterestCrs, AreaOfUse, CoordinateOperation, CoordinateOperationId,
82    CoordinateOperationMetadata, GridCoverageMiss, GridId, GridInterpolation, GridShiftDirection,
83    OperationAccuracy, OperationMatchKind, OperationMethod, OperationSelectionDiagnostics,
84    OperationStep, OperationStepDirection, SelectionOptions, SelectionPolicy, SelectionReason,
85    SkippedOperation, SkippedOperationReason, TransformOutcome, VerticalGridOffsetConvention,
86    VerticalGridOperation, VerticalGridProvenance, VerticalTransformAction,
87    VerticalTransformDiagnostics,
88};
89pub use registry::{
90    lookup_authority_code, lookup_datum_epsg, lookup_epsg, lookup_operation, lookup_vertical_epsg,
91    lookup_vertical_grid_operation, operation_candidates_between,
92    operation_candidates_between_with_selection_options, operations_between,
93    vertical_grid_operations_between,
94};
95pub use transform::Transform;
96#[cfg(feature = "geo-types")]
97pub use transform::TransformableGeometry;
proj_core/lib.rs

proj_core/
lib.rs
