Expand description
Pure Rust coordinate transformation and projection support for OxiGeo.
This crate provides comprehensive coordinate reference system (CRS) and projection capabilities for the OxiGeo library. It includes support for:
- EPSG code database with common coordinate reference systems
- WKT (Well-Known Text) parsing
- PROJ string support
- Coordinate transformations between different CRS
- Pure Rust implementation by default using OxiProj (COOLJAPAN cartographic engine)
- proj4rs retained as optional fallback via the
proj4rs-compatfeature
§Features
std(default): Enable standard library support and OxiProj EPSG/ProjJSON featuresproj-db: Enable SQLite PROJ.db reader for ~7500 EPSG codes. Impliesstd: the reader opens a file-system database (std::path,std::env) throughoxisql-sqlite-compat’s blocking API, which drives a tokio runtime.proj4rs-compat: AddFrom<proj4rs::errors::Error> for Errorfor backward compatibility. Does not implystd— the conversion needs onlyalloc, so it is usable fromno_stdbuilds of this crate.
§Examples
§Transform coordinates from WGS84 to Web Mercator
use oxigeo_proj::{Crs, Coordinate, Transformer};
// Create CRS from EPSG codes
let wgs84 = Crs::from_epsg(4326)?;
let web_mercator = Crs::from_epsg(3857)?;
// Create transformer
let transformer = Transformer::new(wgs84, web_mercator)?;
// Transform a coordinate (London: 0°, 51.5°N)
let london = Coordinate::from_lon_lat(0.0, 51.5);
let transformed = transformer.transform(&london)?;
println!("Transformed: {}", transformed);§Use convenience functions
use oxigeo_proj::{Coordinate, transform_epsg};
let coord = Coordinate::from_lon_lat(-122.4194, 37.7749); // San Francisco
let transformed = transform_epsg(&coord, 4326, 3857)?;
println!("Transformed: {}", transformed);§Work with bounding boxes
use oxigeo_proj::{BoundingBox, Coordinate, Transformer, Crs};
let bbox = BoundingBox::new(-10.0, -10.0, 10.0, 10.0)?;
let transformer = Transformer::from_epsg(4326, 3857)?;
let transformed_bbox = transformer.transform_bbox(&bbox)?;
println!("Original: {:?}", bbox);
println!("Transformed: {:?}", transformed_bbox);§Use common CRS constants
use oxigeo_proj::Crs;
let wgs84 = Crs::wgs84();
let web_mercator = Crs::web_mercator();
let nad83 = Crs::nad83();
let etrs89 = Crs::etrs89();§EPSG Database
The crate includes an embedded database of ~140 common EPSG codes, including:
- WGS84 (EPSG:4326)
- Web Mercator (EPSG:3857)
- All WGS84 UTM zones (EPSG:32601-32660 North, 32701-32760 South)
- Common national datums (NAD83, ETRS89, GDA94, JGD2000, etc.)
- Common projected systems (British National Grid, US National Atlas, etc.)
§Pure Rust Implementation
By default, this crate uses the pure Rust OxiProj library for coordinate transformations.
This ensures:
- No C/C++ dependencies
- Cross-platform compatibility
- Memory safety guarantees
- Easy integration with Rust projects
§Accuracy and Limitations
The pure Rust implementation using OxiProj provides accurate transformations for most common use cases. However, it may have limitations compared to the full PROJ library:
- Limited support for some exotic projections
- No dynamic datum grid shift support
- Simplified datum transformations
For higher-fidelity CRS coverage, enable the proj-db feature: it adds the pure-Rust
oxisql PROJ.db reader (~7500 EPSG codes) on top of the embedded registry.
proj-db is additive only. The process-wide registry behind
lookup_epsg / Crs::from_epsg is unchanged by it — population from a
system PROJ.db is explicit, via
EpsgDatabase::populate_from_system_proj_db on a database you own — and
coordinate transforms resolve every CRS through this crate’s own PROJ
strings in all feature configurations, so enabling proj-db never changes
a number the default build already produces.
Re-exports§
pub use area_of_use::AreaOfUse;pub use area_of_use::area_of_use_for_epsg;pub use cache::TransformerCache;pub use cache::TransformerKey;pub use crs::Crs;pub use crs::CrsSource;pub use crs_identify::CrsFingerprint;pub use crs_identify::fingerprint_from_proj;pub use crs_identify::fingerprint_from_wkt;pub use crs_identify::identify_epsg_from_proj;pub use crs_identify::identify_epsg_from_wkt;pub use epsg::CrsType;pub use epsg::EpsgDefinition;pub use epsg::ProjDb;pub use epsg::ProjDbEntry;pub use epsg::default_proj_db_paths;pub use epsg::populate_from_proj_db;pub use epsg::available_epsg_codes;pub use epsg::contains_epsg;pub use epsg::lookup_epsg;pub use error::Error;pub use error::Result;pub use geocentric::EcefCoordinate;pub use geocentric::EcefTransformer;pub use geocentric::GeocentricCrs;pub use geocentric::GeocentricEllipsoid;pub use geocentric::ecef_to_geographic;pub use geocentric::ecef_to_geographic_iterative;pub use geocentric::geographic_to_ecef;pub use geocentric::geographic_to_geographic_via_ecef;pub use geodesic::GeodesicError;pub use geodesic::GeodesicParams;pub use geodesic::VincentyDirectResult;pub use geodesic::VincentyResult;pub use geodesic::haversine_distance_m;pub use geodesic::vincenty_direct;pub use geodesic::vincenty_inverse;pub use geodesic::wgs84_direct;pub use geodesic::wgs84_haversine_m;pub use geodesic::wgs84_inverse;pub use geoid::load_egm_grid;pub use geoid::GeoidGrid;pub use geoid::GeoidModel;pub use geoid::VerticalDatumKind;pub use geoid::classify_vertical_datum;pub use geoid::synthetic_grid;pub use geoid::synthetic_height_m;pub use geoid_formats::Egm96AsciiHeader;pub use geoid_formats::Egm2008BinaryHeader;pub use geoid_formats::load_geoid_auto;pub use geoid_formats::parse_egm96_ascii_file;pub use geoid_formats::parse_egm96_ascii_header;pub use geoid_formats::parse_egm96_ascii_str;pub use geoid_formats::parse_egm2008_binary_25;pub use geoid_formats::parse_egm2008_binary_25_file;pub use geoid_formats::parse_egm2008_binary_25_header;pub use grid_shift::DHDN_TO_ETRS89;pub use grid_shift::Helmert7Params;pub use grid_shift::NAD27_TO_NAD83;pub use grid_shift::NTF_TO_RGF93;pub use grid_shift::NtV2Grid;pub use grid_shift::OSGB36_TO_ETRS89;pub use grid_shift::dhdn_etrs89_helmert;pub use grid_shift::helmert_3d;pub use grid_shift::helmert_7param;pub use grid_shift::nad27_nad83_poly;pub use grid_shift::ostn15_approx;pub use grid_shift::rgf93_approx;pub use operation_selection::CandidateOperation;pub use operation_selection::OperationRanking;pub use operation_selection::area_coverage_fraction;pub use operation_selection::operation_score;pub use operation_selection::rank_operations;pub use operation_selection::select_best_operation;pub use pipeline::EllipsoidParams;pub use pipeline::GridRegistry;pub use pipeline::HelmertConvention;pub use pipeline::HelmertParams;pub use pipeline::HelmertRateParams;pub use pipeline::ParsedStep;pub use pipeline::Pipeline;pub use pipeline::PipelineStep;pub use pipeline::ShiftDirection;pub use pipeline::StepKind;pub use pipeline::Unit;pub use pipeline::parse_pipeline;pub use transform::AreaOfUseCheck;pub use transform::AreaOfUseWarning;pub use transform::AzimuthalEquidistant;pub use transform::CassineSoldner;pub use transform::EckertIV;pub use transform::EckertVI;pub use transform::EquidistantConic;pub use transform::GaussKruger;pub use transform::Gnomonic;pub use transform::LambertAzimuthalEqualArea;pub use transform::LambertConformalConic;pub use transform::Mollweide;pub use transform::Robinson;pub use transform::Sinusoidal;pub use transform::Transformer;pub use transform::TransverseMercator;pub use transform::VerticalDatumWarning;pub use transform::transform_coordinate;pub use transform::transform_epsg;pub use transform::cylindrical::EllipsoidalTransverseMercator;pub use transform::cylindrical::SphericalTransverseMercator;pub use transform::BoundingBox;pub use transform::Coordinate;pub use transform::Coordinate3D;pub use ups_projection::PolarStereographicParams;pub use ups_projection::UpsCoordinate;pub use ups_projection::UpsHemisphere;pub use ups_projection::polar_stereo_w;pub use ups_projection::polar_stereographic_forward;pub use ups_projection::polar_stereographic_inverse;pub use ups_projection::ups_from_geographic;pub use ups_projection::ups_to_geographic;pub use ups_projection::ups_zone_letter;pub use wkt::WktNode;pub use wkt::WktParser;pub use wkt::parse_wkt;
Modules§
- area_
of_ use - Area-of-use validation for CRS definitions.
- cache
- Thread-safe LRU cache for
Transformerinstances keyed by(src_epsg, dst_epsg). - crs
- Coordinate Reference System (CRS) definitions and operations.
- crs_
identify - CRS auto-identification from WKT and PROJ strings.
- crs_
registry - CRS Registry — comprehensive coordinate reference system lookup and metadata.
- datum_
transform - Geodetic datum transformation algorithms.
- epsg
- EPSG code database with common coordinate reference systems.
- error
- Error types for projection and coordinate transformation operations.
- geocentric
- Geocentric (Earth-Centred, Earth-Fixed) coordinate reference system support.
- geodesic
- Vincenty geodetic distance and azimuth calculations on an arbitrary ellipsoid.
- geoid
- Geoid model loading + bilinear-interpolation undulation queries for vertical CRS transformations.
- geoid_
formats - Real-world EGM geoid distribution-format parsers.
- grid_
shift - Datum grid shift transformations.
- operation_
selection - Coordinate operation selection by accuracy and area-of-use coverage.
- pipeline
- Coordinate operation pipeline — chains multiple projection steps.
- pipeline_
grid - Grid registry and grid-shift step evaluators for
crate::pipeline. - proj_
string - PROJ string parser and builder.
- projections
- Pure Rust implementations of map projections.
- transform
- Coordinate transformation operations.
- ups_
projection - Universal Polar Stereographic (UPS) projection.
- wkt
- Well-Known Text (WKT) parser for CRS definitions.
- wkt_
to_ proj - WKT → PROJ-string conversion.
Constants§
Functions§
- info
- Returns library information.