Add ability to convert 3d coordinates

[PaulWagener]

Fixes #150

This PR adds the ability to convert 3d coordinates.

The Coord trait is changed to add a Z coordinate so at least a minor version bump is warranted with this change.

[urschrei]

Hi @PaulWagener, thanks for the PR!

As ever with 2D -> 3D, there's likely to be some discussion…

At minimum, I don't think we can remove the xy functions in one fell swoop as that would break a great deal of downstream code. I think marking them as deprecated in favour of the new ones is better, here.

As for Coord, we're looking at the same problem. In a sense, this is our fault for using an overly general name, but changing the signature will break a lot of code. How do people feel about a new Coord3 (or maybe Coord4 to include M values) struct and deprecating Coord.

Even more radically: we could adopt Rust-Geodesy's coordinate struct…

[PaulWagener]

As long as 3D coordinates will be supported I will be happy :)

[Oreilles]

What more is needed for this feature to be added ? I'd be happy to help.

[lx-88]

I just wanted to bring up that this issue hurt me on a recent project. It would be great to see a solution to 3d transformations, or at least allowing transformation into ECEF, into the project and released.

[michaelkirk]

@lx-88 - does using this branch work for you?

[michaelkirk]

How do people feel about a new Coord3 (or maybe Coord4 to include M values) struct and deprecating Coord.

A new struct or a new trait?

I thought the whole "bring your own struct" thing was kind of nice, so users don't have to first convert their data to an intermediate proj-crate format.

Just brainstorming... if avoiding api-breakage is a concern, could we introduce the new 3d method with a default impl?

 trait Coord {
   ...
+  #[deprecated(note = "implement from_xyz instead, this method will be removed in a future release")]
   fn from_xy(x: f64, y: f64, z:f64) -> Self;

   // at some point we'd remove the default impl, which would be a breaking release - presumably in the same release as we remove `from_xy`
+  fn from_xyz(x: f64, y: f64, z:f64) -> Self {
+     Self::from_xy(x, y)
+  }
 }

[nokonoko1203]

Hello!
I would be very happy if this crate could be made to correspond to three-dimensional coordinates!

I know that it is very difficult to do this, but what is the reason that this PR has not been merged?
Is there anything I can do to help?

[balazsdukai]

In the meantime, while this PR is being worked on, here is a fork that reprojects 3d coordinates . Here is an example how I use it.
I did the minimum necessary for my use case, but it might be useful for others.

[nokonoko1203]

This is great! I'll use it as a reference!
I was just thinking of using it for a similar project.
(PointCloud to 3D Tiles v1.1: https://github.com/MIERUNE/point-tiler)

[nokonoko1203]

incorporated the contents of this PR into my fork.
I used it to convert from the projection coordinate system used in Japan, and it works very smoothly!

https://github.com/nokonoko1203/proj/blob/f643a9a197921fc7f31571972f522bbd5149a20e/src/proj.rs#L1330

#[test]
fn test_3d_crs() {
	let from = "EPSG:6677";
	let to = "EPSG:6697";
	let proj = Proj::new_known_crs(from, to, None).unwrap();
	let (x, y, z) = (-5998.998, -35838.918, 3.901);
	let (lng, lat, height) = proj.convert((x, y, z)).unwrap();
	assert_relative_eq!(lng, 139.76706139226548, epsilon = 1e-3);
	assert_relative_eq!(lat, 35.67694831658619, epsilon = 1e-3);
	assert_relative_eq!(height, 3.901, epsilon = 1e-3);
	
	let from = "EPSG:6697";
	let to = "EPSG:4979";
	let proj = Proj::new_known_crs(from, to, None).unwrap();
	let (lng, lat, height) = proj.convert((lng, lat, height)).unwrap();
	assert_relative_eq!(lng, 139.76706139226548, epsilon = 1e-3);
	assert_relative_eq!(lat, 35.67694831658619, epsilon = 1e-3);
	assert_relative_eq!(height, 40.53393140934767, epsilon = 1e-3);
	
	let from = "EPSG:4979";
	let to = "EPSG:4978";
	let proj = Proj::new_known_crs(from, to, None).unwrap();
	let (x, y, z) = proj.convert((lng, lat, height)).unwrap();
	assert_relative_eq!(x, -3959898.9249523925, epsilon = 1e-3);
	assert_relative_eq!(y, 3350278.1607454875, epsilon = 1e-3);
	assert_relative_eq!(z, 3699157.243055472, epsilon = 1e-3);
}