Struct proj::Proj

pub struct Proj { /* fields omitted */ }

A PROJ instance

Implementations

impl Proj

pub fn new(definition: &str) -> Option<Proj>

Try to instantiate a new PROJ instance

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.

Safety

This method contains unsafe code.

pub fn new_known_crs(from: &str, to: &str, area: Option<Area>) -> Option<Proj>

Create a 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.

 extern crate proj;
 use proj::Proj;

 extern crate geo_types;
 use geo_types::Point;

 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(Point::new(4760096.421921f64, 3744293.729449f64))
     .unwrap();
 assert_approx_eq!(result.x(), 1450880.29f64, 1.0e-2);
 assert_approx_eq!(result.y(), 1141263.01f64, 1.0e-2);

Safety

This method contains unsafe code.

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.

pub fn def(&self) -> String

Get the current definition from PROJ

Safety

This method contains unsafe code.

pub fn project<T, U>(
    &self,
    point: T,
    inverse: bool
) -> Result<Point<U>, ProjError> where
    T: Into<Point<U>>,
    U: Float, 

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.

pub fn convert<T, U>(&self, point: T) -> Result<Point<U>, ProjError> where
    T: Into<Point<U>>,
    U: Float, 

Convert projected coordinates between coordinate reference systems.

Input and output CRS may be specified in two ways:

1. Using the PROJ pipeline operator. This method makes use of the pipeline functionality available since PROJ 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)
2. 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) Note the steps:

• define the operation as a pipeline operation
• define step 1 as an inverse transform, yielding geodetic coordinates
• define step 2 as a forward transform to projected coordinates, yielding metres.

extern crate proj;
use proj::Proj;

extern crate geo_types;
use geo_types::Point;

let nad_ft_to_m = Proj::new(
    "
    +proj=pipeline
    +step +inv +proj=lcc +lat_1=33.88333333333333
    +lat_2=32.78333333333333 +lat_0=32.16666666666666
    +lon_0=-116.25 +x_0=2000000.0001016 +y_0=500000.0001016001 +ellps=GRS80
    +towgs84=0,0,0,0,0,0,0 +units=us-ft +no_defs
    +step +proj=lcc +lat_1=33.88333333333333 +lat_2=32.78333333333333 +lat_0=32.16666666666666
    +lon_0=-116.25 +x_0=2000000 +y_0=500000
    +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs
",
)
.unwrap();
let result = nad_ft_to_m
    .convert(Point::new(4760096.421921f64, 3744293.729449f64))
    .unwrap();
assert_approx_eq!(result.x(), 1450880.29f64, 1.0e-2);
assert_approx_eq!(result.y(), 1141263.01f64, 1.0e-2);

Safety

This method contains unsafe code.

pub fn convert_array<'a, T>(
    &self,
    points: &'a mut [Point<T>]
) -> Result<&'a mut [Point<T>], ProjError> where
    T: Float, 

Convert a mutable slice (or anything that can deref into a mutable slice) of Points

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;
extern crate geo_types;
use geo_types::Point;
let from = "EPSG:2230";
let to = "EPSG:26946";
let ft_to_m = Proj::new_known_crs(&from, &to, None).unwrap();
let mut v = vec![
    Point::new(4760096.421921, 3744293.729449),
    Point::new(4760197.421921, 3744394.729449),
];
ft_to_m.convert_array(&mut v);
assert_approx_eq!(v[0].x(), 1450880.2910605003f64);
assert_approx_eq!(v[1].y(), 1141293.7960220212f64);

Safety

This method contains unsafe code.

pub fn project_array<'a, T>(
    &self,
    points: &'a mut [Point<T>],
    inverse: bool
) -> Result<&'a mut [Point<T>], ProjError> where
    T: Float, 

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;
extern crate geo_types;
use geo_types::Point;
let stereo70 = Proj::new(
    "+proj=sterea +lat_0=46 +lon_0=25 +k=0.99975 +x_0=500000 +y_0=500000
    +ellps=krass +towgs84=33.4,-146.6,-76.3,-0.359,-0.053,0.844,-0.84 +units=m +no_defs",
)
.unwrap();
// Geodetic -> Pulkovo 1942(58) / Stereo70 (EPSG 3844)
let mut v = vec![Point::new(0.436332, 0.802851)];
let t = stereo70.project_array(&mut v, false).unwrap();
assert_approx_eq!(v[0].x(), 500119.7035366755f64);
assert_approx_eq!(v[0].y(), 500027.77901023754f64);

Safety

This method contains unsafe code.

Trait Implementations

impl Drop for Proj

fn drop(&mut self)

Executes the destructor for this type.