pub struct Proj { /* private fields */ }
Expand description
A coordinate transformation object.
A Proj
can be constructed a few different ways:
Examples
use proj::{Proj, Coord};
let from = "EPSG:2230";
let to = "EPSG:26946";
let nad_ft_to_m = Proj::new_known_crs(&from, &to, None).unwrap();
let result = nad_ft_to_m
.convert((4760096.421921f64, 3744293.729449f64))
.unwrap();
assert_relative_eq!(result.x(), 1450880.29, epsilon=1.0e-2);
assert_relative_eq!(result.y(), 1141263.01, epsilon=1.0e-2);
Implementations
sourceimpl Proj
impl Proj
sourcepub fn new(definition: &str) -> Result<Proj, ProjCreateError>
pub fn new(definition: &str) -> Result<Proj, ProjCreateError>
Try to create a new transformation object
Note: for projection operations, definition
specifies
the output projection; input coordinates
are assumed to be geodetic in radians, unless an inverse projection is intended.
For conversion operations, definition
defines input, output, and
any intermediate steps that are required. See the convert
example for more details.
Examples
Construcing a Proj
from a PROJ string definition:
let transformer = proj::Proj::new(
"+proj=merc +lat_ts=56.5 +ellps=GRS80"
).unwrap();
A TryFrom
implementation is available which wraps new
:
use std::convert::TryFrom;
let transformer = proj::Proj::try_from(
"+proj=merc +lat_ts=56.5 +ellps=GRS80"
).unwrap();
Safety
This method contains unsafe code.
sourcepub fn new_known_crs(
from: &str,
to: &str,
area: Option<Area>
) -> Result<Proj, ProjCreateError>
pub fn new_known_crs(
from: &str,
to: &str,
area: Option<Area>
) -> Result<Proj, ProjCreateError>
Try to create a new transformation object that is a pipeline between two known coordinate reference systems.
from
and to
can be:
- an
"AUTHORITY:CODE"
, like"EPSG:25832"
. - a PROJ string, like
"+proj=longlat +datum=WGS84"
. When using that syntax, the unit is expected to be degrees. - the name of a CRS as found in the PROJ database, e.g
"WGS84"
,"NAD27"
, etc. - more generally, any string accepted by
new()
If you wish to alter the particular area of use, you may do so using area_set_bbox()
A Note on Coordinate Order
The required input and output coordinate order is normalised to Longitude, Latitude
/ Easting, Northing
.
This overrides the expected order of the specified input and / or output CRS if necessary. See the PROJ API
For example: per its definition, EPSG:4326 has an axis order of Latitude, Longitude. Without
normalisation, crate users would have to
remember
to reverse the coordinates of Point
or Coordinate
structs in order for a conversion operation to
return correct results.
Examples
Constructing a Proj
from a source CRS and target CRS:
let transformer = proj::Proj::new_known_crs(
"EPSG:2230",
"EPSG:26946",
None
).unwrap();
A TryFrom
implementation is available which wraps new_known_crs
:
use std::convert::TryFrom;
let transformer = proj::Proj::try_from((
"EPSG:2230",
"EPSG:26946"
)).unwrap();
Safety
This method contains unsafe code.
sourcepub fn area_set_bbox(&mut self, new_bbox: Area)
pub fn area_set_bbox(&mut self, new_bbox: Area)
Set the bounding box of the area of use
This bounding box will be used to specify the area of use
for the choice of relevant coordinate operations.
In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees),
west
must be greater than east
.
Safety
This method contains unsafe code.
sourcepub fn area_of_use(&self) -> Result<(Option<Area>, Option<String>), ProjError>
pub fn area_of_use(&self) -> Result<(Option<Area>, Option<String>), ProjError>
Returns the area of use of a projection
When multiple usages are available, the first one will be returned. The bounding box coordinates are in degrees.
According to upstream, both the area of use and the projection name might have not been defined, so they are optional.
sourcepub fn project<C, F>(&self, point: C, inverse: bool) -> Result<C, ProjError> where
C: Coord<F>,
F: CoordinateType,
pub fn project<C, F>(&self, point: C, inverse: bool) -> Result<C, ProjError> where
C: Coord<F>,
F: CoordinateType,
Project geodetic coordinates (in radians) into the projection specified by definition
Note: specifying inverse
as true
carries out an inverse projection to geodetic coordinates
(in radians) from the projection specified by definition
.
Safety
This method contains unsafe code.
sourcepub fn convert<C, F>(&self, point: C) -> Result<C, ProjError> where
C: Coord<F>,
F: CoordinateType,
pub fn convert<C, F>(&self, point: C) -> Result<C, ProjError> where
C: Coord<F>,
F: CoordinateType,
Convert projected coordinates between coordinate reference systems.
Input and output CRS may be specified in two ways:
- Using the PROJ
pipeline
operator. This method makes use of thepipeline
functionality available sincePROJ
5. This has the advantage of being able to chain an arbitrary combination of projection, conversion, and transformation steps, allowing for extremely complex operations (new
) - Using EPSG codes or
PROJ
strings to define input and output CRS (new_known_crs
)
A Note on Coordinate Order
Depending on the method used to instantiate the Proj
object, coordinate input and output order may vary:
- If you have used
new
, it is assumed that you’ve specified the order using the input string, or that you are aware of the required input order and expected output order. - If you have used
new_known_crs
, input and output order are normalised to Longitude, Latitude / Easting, Northing.
The following example converts from NAD83 US Survey Feet (EPSG 2230) to NAD83 Metres (EPSG 26946)
extern crate proj;
use proj::{Proj, Coord};
let from = "EPSG:2230";
let to = "EPSG:26946";
let ft_to_m = Proj::new_known_crs(&from, &to, None).unwrap();
let result = ft_to_m
.convert((4760096.421921, 3744293.729449))
.unwrap();
assert_relative_eq!(result.x() as f64, 1450880.29, epsilon=1e-2);
assert_relative_eq!(result.y() as f64, 1141263.01, epsilon=1e-2);
Safety
This method contains unsafe code.
sourcepub fn convert_array<'a, C, F>(
&self,
points: &'a mut [C]
) -> Result<&'a mut [C], ProjError> where
C: Coord<F>,
F: CoordinateType,
pub fn convert_array<'a, C, F>(
&self,
points: &'a mut [C]
) -> Result<&'a mut [C], ProjError> where
C: Coord<F>,
F: CoordinateType,
Convert a mutable slice (or anything that can deref into a mutable slice) of Coord
s
The following example converts from NAD83 US Survey Feet (EPSG 2230) to NAD83 Metres (EPSG 26946)
A Note on Coordinate Order
Depending on the method used to instantiate the Proj
object, coordinate input and output order may vary:
- If you have used
new
, it is assumed that you’ve specified the order using the input string, or that you are aware of the required input order and expected output order. - If you have used
new_known_crs
, input and output order are normalised to Longitude, Latitude / Easting, Northing.
use proj::{Proj, Coord};
// Convert from NAD83(NSRS2007) to NAD83(2011)
let from = "EPSG:4759";
let to = "EPSG:4317";
let NAD83_old_to_new = Proj::new_known_crs(&from, &to, None).unwrap();
let mut v = vec![
(-98.5421515000, 39.2240867222),
(-98.3166503906, 38.7112325390),
];
NAD83_old_to_new.convert_array(&mut v);
assert_relative_eq!(v[0].x(), -98.54, epsilon=1e-2);
assert_relative_eq!(v[1].y(), 38.71, epsilon=1e-2);
Safety
This method contains unsafe code.
sourcepub fn project_array<'a, C, F>(
&self,
points: &'a mut [C],
inverse: bool
) -> Result<&'a mut [C], ProjError> where
C: Coord<F>,
F: CoordinateType,
pub fn project_array<'a, C, F>(
&self,
points: &'a mut [C],
inverse: bool
) -> Result<&'a mut [C], ProjError> where
C: Coord<F>,
F: CoordinateType,
Project an array of geodetic coordinates (in radians) into the projection specified by definition
Note: specifying inverse
as true
carries out an inverse projection to geodetic coordinates
(in radians) from the projection specified by definition
.
use proj::{Proj, Coord};
let from = "EPSG:2230";
let to = "EPSG:26946";
let ft_to_m = Proj::new_known_crs(&from, &to, None).unwrap();
let mut v = vec![
(4760096.421921, 3744293.729449),
(4760197.421921, 3744394.729449),
];
ft_to_m.convert_array(&mut v).unwrap();
assert_relative_eq!(v[0].x(), 1450880.29, epsilon=1e-2);
assert_relative_eq!(v[1].y(), 1141293.79, epsilon=1e-2);
Safety
This method contains unsafe code.
Trait Implementations
sourceimpl Info for Proj
impl Info for Proj
sourcefn info(&self) -> Result<Projinfo, ProjError>
fn info(&self) -> Result<Projinfo, ProjError>
Return Information about the current PROJ context Read more
sourcefn network_enabled(&self) -> bool
fn network_enabled(&self) -> bool
Check whether network access for resource file download is currently enabled or disabled. Read more
sourceimpl TryFrom<&'_ str> for Proj
impl TryFrom<&'_ str> for Proj
sourcefn try_from(definition: &str) -> Result<Proj, Self::Error>
fn try_from(definition: &str) -> Result<Proj, Self::Error>
Create a Proj
from a PROJ string definition.
Examples
use std::convert::TryFrom;
let transformer = proj::Proj::try_from(
"+proj=merc +lat_ts=56.5 +ellps=GRS80"
).unwrap();
type Error = ProjCreateError
type Error = ProjCreateError
The type returned in the event of a conversion error.
sourceimpl TryFrom<(&'_ str, &'_ str)> for Proj
impl TryFrom<(&'_ str, &'_ str)> for Proj
sourcefn try_from((source_crs, target_crs): (&str, &str)) -> Result<Proj, Self::Error>
fn try_from((source_crs, target_crs): (&str, &str)) -> Result<Proj, Self::Error>
Create a Proj
from a source CRS and target CRS.
Examples
use std::convert::TryFrom;
let transformer = proj::Proj::try_from((
"EPSG:2230",
"EPSG:26946"
)).unwrap();
type Error = ProjCreateError
type Error = ProjCreateError
The type returned in the event of a conversion error.
Auto Trait Implementations
impl RefUnwindSafe for Proj
impl !Send for Proj
impl !Sync for Proj
impl Unpin for Proj
impl UnwindSafe for Proj
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more