Struct Transformer 

pub struct Transformer { /* private fields */ }

Coordinate transformer that handles transformations between CRS.

Implementations

impl Transformer

pub fn new(source_crs: Crs, target_crs: Crs) -> Result<Self>

Creates a new transformer.

Arguments

• source_crs - Source coordinate reference system
• target_crs - Target coordinate reference system

Errors

Returns an error if the transformation cannot be initialized.

pub fn with_geoid(self, grid: Arc<GeoidGrid>) -> Self

Attaches a geoid model to this transformer.

When both the source and target CRS are CrsSource::Compound and their vertical components are of different kinds (one ellipsoidal, one orthometric), Transformer::transform_3d uses the attached grid to apply the corresponding height correction (N added or subtracted depending on direction). Without a geoid attached the vertical conversion silently passes through, preserving the legacy behaviour of pre-Slice-14 builds.

Returns the transformer by value so the call may be chained:

use std::sync::Arc;
use oxigdal_proj::{Crs, Transformer};
use oxigdal_proj::geoid::{GeoidModel, synthetic_grid};

let t = Transformer::new(Crs::wgs84(), Crs::wgs84())
    .expect("ok")
    .with_geoid(Arc::new(synthetic_grid(GeoidModel::Egm96)));
assert!(t.geoid().is_some());

pub fn geoid(&self) -> Option<&Arc<GeoidGrid>>

Returns the attached geoid model, if any.

pub fn with_strict(self, strict: bool) -> Self

Sets strict area-of-use validation.

When strict is true (the default), Transformer::transform returns Error::OutOfAreaOfUse for any point that lies outside the source CRS’s declared area of use. When false, the check is skipped silently.

pub fn is_strict(&self) -> bool

Returns whether strict area-of-use validation is enabled.

pub fn with_area_of_use_check(self, mode: AreaOfUseCheck) -> Self

Configures the per-instance area-of-use validation mode.

This is independent of the legacy with_strict/is_strict switch and applies in transform and transform_batch before the underlying projection runs. The bounds are looked up via area_of_use_for_epsg on the source EPSG; if that lookup returns None, the check is skipped silently regardless of mode.

Behaviour:

• AreaOfUseCheck::Off (default) — no validation is performed.
• AreaOfUseCheck::Warn — out-of-area points are recorded via last_warning but the transform proceeds.
• AreaOfUseCheck::Strict — out-of-area points abort the transform with Error::OutsideAreaOfUse.

pub fn area_of_use_check(&self) -> AreaOfUseCheck

Returns the currently configured area-of-use check mode.

pub fn last_warning(&self) -> Option<AreaOfUseWarning>

Returns the most recent area-of-use warning recorded under AreaOfUseCheck::Warn mode, if any.

Returns None when the check mode is AreaOfUseCheck::Off, when no out-of-area point has been seen yet, or when the source EPSG has no registered area-of-use entry.

pub fn clear_warning(&self)

Clears any previously-recorded area-of-use warning.

pub fn with_epoch(self, source_epoch: f64, target_epoch: f64) -> Result<Self>

Configure a time-dependent ITRF epoch transformation.

Both the source and target CRS must be ITRF-based (recognised by EPSG code or by frame name in the datum/CRS name), and a preset must exist for that pair in the built-in IERS table.

The Bursa-Wolf parameters are extrapolated linearly from the published reference epoch to the requested observation epochs before the Helmert transformation is applied. When source_epoch == target_epoch the correction is zero and the output equals the input.

Parameters

• source_epoch – observation epoch of the input coordinates (decimal year, e.g. 2015.0)
• target_epoch – desired output epoch (decimal year, e.g. 2020.75)

Errors

Returns Err if:

• either CRS is not an ITRF realisation, or
• no registered IERS preset exists for the source→target frame pair.

pub fn source_epoch(&self) -> Option<f64>

Returns the configured source epoch, if any.

pub fn target_epoch(&self) -> Option<f64>

Returns the configured target epoch, if any.

pub fn from_epsg(source_epsg: u32, target_epsg: u32) -> Result<Self>

Creates a transformer from EPSG codes.

Arguments

• source_epsg - Source EPSG code
• target_epsg - Target EPSG code

Errors

Returns an error if the EPSG codes are invalid or transformation cannot be initialized.

pub fn source_crs(&self) -> &Crs

Returns the source CRS.

pub fn target_crs(&self) -> &Crs

Returns the target CRS.

pub fn transform(&self, coord: &Coordinate) -> Result<Coordinate>

Transforms a single coordinate.

Arguments

• coord - Input coordinate in source CRS

Errors

Returns an error if the transformation fails, or if self.strict is true and the point lies outside the source CRS’s declared area of use.

pub fn transform_3d(&self, coord: &Coordinate3D) -> Result<Coordinate3D>

Transforms a 3D coordinate.

When both the source and target CRS are CrsSource::Compound, the horizontal pair (x, y) is transformed independently using a sub- transformer, and the vertical component (z) is handled as follows:

• If the source and target vertical CRS are equivalent, z is passed through unchanged.
• Otherwise, the vertical datums of source and target are classified via crate::geoid::classify_vertical_datum. When a geoid model has been attached via Transformer::with_geoid and the pair is orthometric ↔ ellipsoidal, the undulation correction is applied (h_ellip = h_ortho + N or h_ortho = h_ellip − N).
• In any other case (no geoid attached, or one side Unknown), z is silently passed through unchanged to preserve back-compat with pre-Slice-14 builds.

When with_epoch has been called, the ITRF epoch correction is applied using the Bursa-Wolf parameters extrapolated to the requested epochs. The coordinate convention is: coord.x = geodetic longitude (degrees), coord.y = geodetic latitude (degrees), coord.z = ellipsoidal height (metres).

pub fn transform_batch(&self, coords: &[Coordinate]) -> Result<Vec<Coordinate>>

Transforms multiple coordinates in batch.

Attempts SIMD-accelerated kernels for Transverse Mercator, Mercator, and Lambert Conformal Conic projections first. Falls back to scalar point-by-point transformation for any other projection or when the projection parameters cannot be extracted from the PROJ string.

Arguments

• coords - Input coordinates in source CRS

Errors

Returns an error if any transformation fails.

pub fn transform_bbox(&self, bbox: &BoundingBox) -> Result<BoundingBox>

Transforms a bounding box.

This transforms all four corners and creates a new bounding box from the results.

Arguments

• bbox - Input bounding box in source CRS

Errors

Returns an error if the transformation fails.