Skip to main content

Crate oxigeo_proj

Crate oxigeo_proj 

Source
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-compat feature

§Features

  • std (default): Enable standard library support and OxiProj EPSG/ProjJSON features
  • proj-db: Enable SQLite PROJ.db reader for ~7500 EPSG codes. Implies std: the reader opens a file-system database (std::path, std::env) through oxisql-sqlite-compat’s blocking API, which drives a tokio runtime.
  • proj4rs-compat: Add From<proj4rs::errors::Error> for Error for backward compatibility. Does not imply std — the conversion needs only alloc, so it is usable from no_std builds 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 Transformer instances 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§

NAME
Library name
VERSION
Library version

Functions§

info
Returns library information.