Struct Proj

pub struct Proj { /* private fields */ }

A coordinate transformation object.

A Proj can be constructed a few different ways:

• ProjBuilder
• Proj::new
• Proj::new_known_crs

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

impl Proj

pub fn coordinate_metadata_create( &self, epoch: f64, ) -> Result<Proj, ProjCreateError>

Create a coordinate metadata object to be used in coordinate operations.

This creates a coordinate metadata object that can be used in coordinate operations, such as transformations. The coordinate metadata object contains information about the coordinates, such as the epoch they are referenced to.

Note

Only transformation objects (e.g. those created by calling new()) can be converted to metadata objects. They cannot be created from pipelines.

Arguments

• epoch - The epoch that the coordinates are referenced to.

Returns

A new coordinate metadata object or an error if creation failed.

Safety

This method contains unsafe code.

pub fn coordinate_metadata_get_epoch(&self) -> f64

Get the epoch from a coordinate metadata object.

This retrieves the epoch associated with a coordinate metadata object.

Returns

The epoch value as a float, or f64::NAN if the object doesn’t have an associated epoch.

Safety

This method contains unsafe code.

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

Constructing 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.

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.

pub fn create_crs_to_crs_from_pj( &self, target_crs: &Proj, area: Option<Area>, options: Option<Vec<&str>>, ) -> Result<Proj, ProjCreateError>

Create a transformation object that is a pipeline between two known coordinate reference systems.

This is similar to using Proj::new_known_crs() except that it accepts existing Proj objects instead of string identifiers.

Note on Coordinate Metadata

Starting with PROJ 9.4, both source and target can be CoordinateMetadata objects, allowing for changes of coordinate epochs (though in practice this is limited to use of velocity grids inside the same dynamic CRS). In the proj crate, CoordinateMetadata is a Proj struct created with Proj::coordinate_metadata_create().

Arguments

• target_crs - The target CRS or coordinate metadata object
• area - Optional area of use to help select the appropriate transformation
• options - Optional list of strings with “KEY=VALUE” format. Supported options include:
  • AUTHORITY=name: to restrict the authority of coordinate operations looked up in the database.
  • ACCURACY=value: to set the minimum desired accuracy (in metres) of the candidate coordinate operations.
  • ALLOW_BALLPARK=YES/NO: can be set to NO to disallow the use of Ballpark transformation.
  • ONLY_BEST=YES/NO: Can be set to YES to cause PROJ to error out if the best transformation cannot be used.
  • FORCE_OVER=YES/NO: can be set to YES to force the +over flag on the transformation.

Returns

A new transformation object or an error if creation failed

Examples

Constructing a Proj from a source CRS and target CRS:

// UTM Zone 6 US Survey Feet to Metres
let from = proj::Proj::new("EPSG:2230").unwrap();
let to = proj::Proj::new("EPSG:26946").unwrap();
let transformer = from.create_crs_to_crs_from_pj(&to, None, None).unwrap();
let result = transformer
    .convert((4760096.421921, 3744293.729449))
    .unwrap();
assert_relative_eq!(result.0, 1450880.2910605022, epsilon = 1.0e-8);
assert_relative_eq!(result.1, 1141263.0111604782, epsilon = 1.0e-8);

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 lib_info(&self) -> Result<Info, ProjError>

Return information about the current instance of the PROJ libary.

See: https://proj.org/development/reference/datatypes.html#c.PJ_INFO

If instead you are looking for information about the current projection / conversion, see Proj::proj_info.

Safety

This method contains unsafe code.

pub fn network_enabled(&self) -> bool

Check whether network access for resource file download is currently enabled or disabled.

Safety

This method contains unsafe code.

pub fn get_url_endpoint(&self) -> Result<String, ProjError>

Get the URL endpoint to query for remote grids

Safety

This method contains unsafe code.

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.

pub fn proj_info(&self) -> ProjInfo

Get information about a specific transformation object.

See https://proj.org/development/reference/functions.html#c.proj_pj_info

If instead you are looking for information about the PROJ installation, see Proj::lib_info.

Safety

This method contains unsafe code.

pub fn def(&self) -> Result<String, ProjError>

Get the current definition from PROJ

Safety

This method contains unsafe code.

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.

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:

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)

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.

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 Coords

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.

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.

pub fn transform_bounds<F>( &self, left: F, bottom: F, right: F, top: F, densify_pts: i32, ) -> Result<[F; 4], ProjError>

where F: CoordinateType,

Transform boundary densifying the edges to account for nonlinear transformations along these edges and extracting the outermost bounds.

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)

The densify_pts parameter describes the number of points to add to each edge to account for nonlinear edges produced by the transform process. Large numbers will produce worse performance.

The following example converts from NAD83 US Survey Feet (EPSG 2230) to NAD83 Metres (EPSG 26946)

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
    .transform_bounds(4760096.421921, 3744293.729449, 4760196.421921, 3744393.729449, 21)
    .unwrap();
assert_relative_eq!(result[0] as f64, 1450880.29, epsilon=1e-2);
assert_relative_eq!(result[1] as f64, 1141263.01, epsilon=1e-2);
assert_relative_eq!(result[2] as f64, 1450910.77, epsilon=1e-2);
assert_relative_eq!(result[3] as f64, 1141293.49, epsilon=1e-2);

Safety

This method contains unsafe code.

pub fn to_projjson( &self, multiline: Option<bool>, indentation_width: Option<usize>, schema: Option<&str>, ) -> Result<String, ProjError>

Return the projjson representation of a transformation

Safety

This method contains unsafe code.

Trait Implementations

impl Debug for Proj

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Proj

fn drop(&mut self)

Executes the destructor for this type.

impl TryFrom<&str> for Proj

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

The type returned in the event of a conversion error.

impl TryFrom<(&str, &str)> for Proj

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

The type returned in the event of a conversion error.