Crate coordtransform

Expand description

High-accuracy, dependency-free coordinate transforms for WGS 84, GCJ-02, BD-09, and Web Mercator (EPSG:3857).

The crate is designed for mobile applications, navigation, track processing, and other high-frequency workloads. It has no third-party crate dependencies and performs no heap allocation on the scalar conversion hot path.

§Coordinate systems

WGS 84: global longitude/latitude coordinates used by GNSS and most GIS data.
GCJ-02: the coordinate system commonly used by map services in mainland China.
BD-09: Baidu’s coordinate system, derived from GCJ-02.
EPSG:3857: Web Mercator coordinates in metres.

§GCJ-02 transform region

The traditional implementation only checks a large rectangle and therefore applies GCJ-02 offsets to locations in nearby countries. This implementation instead embeds a small, simplified, OSM-derived geographic mask directly in the binary. No boundary crate, parser, file I/O, lazy initialization, or heap allocation is needed at runtime.

The embedded mask is deliberately approximate. It is intended only to decide whether the GCJ-02 transform should be dispatched for ordinary land-based map and navigation positions. It is not a legal, cadastral, maritime, or surveying boundary. Hong Kong and Macau are carved out of the mask, and Taiwan is outside the main ring.

The embedded ring is a simplified and quantized transform-dispatch mask based on the OpenStreetMap China boundary relation (relation 270056), simplified and quantized offline for transform dispatch. Remote offshore geometry south of 18 N is intentionally ignored because this crate targets ordinary mainland/Hainan app navigation rather than maritime boundary classification. The mask is intentionally approximate near borders and must not be used for administrative decisions. The embedded geographic data remains subject to the Open Database License (ODbL); attribution: (c) OpenStreetMap contributors. See https://www.openstreetmap.org/copyright.

§Accuracy

The commonly published GCJ-02 formula does not provide an exact inverse. gcj02_to_wgs84 uses a fast inverse seed followed by fixed numerical refinement. bd09_to_gcj02 similarly refines the conventional analytical approximation against the forward BD-09 formula.

Fast single-pass variants are also provided when throughput is more important than the smallest possible round-trip residual.

§Performance

Region lookup uses three stages:

A broad bounding-box rejection.
A precomputed 1-degree raster. Interior and exterior cells return in O(1).
Only cells touched by the simplified boundary run a point-in-polygon test.

The polygon itself is stored as quantized u16 coordinates at 0.001-degree resolution. The region data is static, requires no initialization, and is only a few kilobytes. Callers that already know a stream stays inside the transform region can use the *_in_mainland functions and skip region lookup entirely.

§Quick start

use coordtransform::{gcj02_to_wgs84, wgs84_to_gcj02};

let wgs = (116.404, 39.915);
let gcj = wgs84_to_gcj02(wgs.0, wgs.1);
let restored = gcj02_to_wgs84(gcj.0, gcj.1);

assert!((restored.0 - wgs.0).abs() < 1e-9);
assert!((restored.1 - wgs.1).abs() < 1e-9);

Enums§

ProjectionError: Errors returned by strict Web Mercator conversion functions.

Constants§

MAX_LATITUDE: Maximum absolute latitude representable in the canonical finite EPSG:3857 world.
OSM_ATTRIBUTION: Attribution text for the embedded OpenStreetMap-derived transform-region mask.

Functions§

bd09_to_epsg3857: Converts BD-09 longitude/latitude to Web Mercator metres through WGS 84.
bd09_to_gcj02: Converts BD-09 longitude/latitude to GCJ-02 longitude/latitude with numerical refinement for tight forward/reverse consistency.
bd09_to_gcj02_fast: Converts BD-09 longitude/latitude to GCJ-02 using the traditional single-pass inverse approximation.
bd09_to_wgs84: Converts BD-09 longitude/latitude to WGS 84 longitude/latitude.
bd09_to_wgs84_in_place: Converts a mutable slice of BD-09 points to WGS 84 in place.
epsg3857_to_bd09: Converts Web Mercator metres to BD-09 longitude/latitude through WGS 84.
epsg3857_to_gcj02: Converts Web Mercator metres to GCJ-02 longitude/latitude through WGS 84.
epsg3857_to_wgs84: Converts Web Mercator (EPSG:3857) metres to WGS 84 longitude/latitude.
gcj02_to_bd09: Converts GCJ-02 longitude/latitude to BD-09 longitude/latitude.
gcj02_to_epsg3857: Converts GCJ-02 longitude/latitude to Web Mercator metres through WGS 84.
gcj02_to_wgs84: Converts GCJ-02 longitude/latitude to WGS 84 longitude/latitude using a refined numerical inverse.
gcj02_to_wgs84_fast: Converts GCJ-02 longitude/latitude to WGS 84 using only the traditional one-step inverse approximation after the region check.
gcj02_to_wgs84_in_mainland: Converts a GCJ-02 position known to belong to the mainland transform region to WGS 84 without performing the region lookup.
gcj02_to_wgs84_in_mainland_in_place: Converts GCJ-02 points known to belong to the mainland transform region to WGS 84 in place without running region lookup for each point.
gcj02_to_wgs84_in_place: Converts a mutable slice of GCJ-02 points to WGS 84 in place.
is_in_gcj02_region: Returns true when a WGS 84 coordinate belongs to the approximate GCJ-02 transform region used by this crate.
is_in_mainland_china: Returns true when a WGS 84 coordinate is inside the approximate mainland GCJ-02 transform region.
is_out_of_china: Returns true when a coordinate is outside this crate’s GCJ-02 transform region.
try_epsg3857_to_wgs84: Strictly converts Web Mercator metres to WGS 84 longitude/latitude.
try_wgs84_to_epsg3857: Strictly converts WGS 84 longitude/latitude to Web Mercator metres.
warm_up: Compatibility no-op retained from versions that lazily initialized a boundary index.
wgs84_to_bd09: Converts WGS 84 longitude/latitude to BD-09 longitude/latitude.
wgs84_to_bd09_in_place: Converts a mutable slice of WGS 84 points to BD-09 in place.
wgs84_to_epsg3857: Converts WGS 84 longitude/latitude to Web Mercator (EPSG:3857) metres.
wgs84_to_epsg3857_clamped: Validates a WGS 84 coordinate and converts it to Web Mercator with explicit latitude clamping.
wgs84_to_gcj02: Converts WGS 84 longitude/latitude to GCJ-02 longitude/latitude.
wgs84_to_gcj02_in_mainland: Converts a WGS 84 position known to be in the mainland transform region to GCJ-02 without performing the region lookup.
wgs84_to_gcj02_in_mainland_in_place: Converts WGS 84 points known to be inside the mainland transform region to GCJ-02 in place without running region lookup for each point.
wgs84_to_gcj02_in_place: Converts a mutable slice of WGS 84 points to GCJ-02 in place.