transform-translate does not preserve geometric angles and distances

[hadbn]

When using this function, the translation is performed on each point independently, without considering the geometry of the feature as a whole.
As a result, the translation of a circle, for example, will no longer be a circle, which can be prejudicial.

Reproduced with Turf version 7.1 running at https://turf-sandbox.netlify.app/ with the following code :

const p = turf.point(  [-30., 40]);

//blue : original circle around p
const c0 = turf.circle(p, 1000);
const c0_col = turf.polygon(c0.geometry.coordinates, {fill: '#0FF'});

//red : transformTranslate of the blue circle
const c1 = turf.transformTranslate(c0, 1000, 30); //red
const c1_col = turf.polygon(c1.geometry.coordinates, {fill: '#ff0000'});

//green : circle around the transformTranslate of the center of the blue one
const p1 = turf.transformTranslate(p, 1000, 30);
const c11 = turf.circle(p1, 1000);
const c11_col = turf.polygon(c11.geometry.coordinates, {fill: '#00ff00'});

return turf.featureCollection([c0_col, c11_col, c1_col]);

It would be useful to add a parameter to the function, allowing the user to decide whether or not to keep the geometric properties of the feature given as input.

[smallsaucepan]

Thanks @hadbn

This seems like a limitation of tranformTranslate. rhumb-translating individual points is bound to distort especially away from the equator. Best illustration I can think of is the red and blue lines are both 8000km long:

Another probable example of this is at #2419

So, your PR seems like a good approach. However I don't think the user should have to opt in. The corrected behaviour should be the default.

Will get a second opinion though. What do you think @mfedderly @JamesLMilner @rowanwins. Can we just fix the bug and not treat this as something the user needs to opt in to? Perhaps we would need to clarify in the docs that translation uses the centroid as the reference point.

Or is this somehow the expected behaviour?

[hadbn]

Did you have a chance to discuss that, @smallsaucepan @mfedderly @JamesLMilner and @rowanwins ?
If you have any suggestion or if you are willing to change the default behaviour, I can update the pull request I made.

[smallsaucepan]

Haven't heard further from anyone else. My inclination is for us to do two things:

1. fix this so the default behaviour works and displays properly on a mercator projection, no additional option required
2. use this function as a model for how we document whether an implementation supports mercator projection, spherical earth, or both

Would you be happy with the approach described in point 1?

For point 2 I'd like to see something like the below on the website eventually - map and / or globe indicating support for planar or spherical calculations. Maybe as text as well below the description.

Note that we generate both the README.md files and the website content, so we can add some special handling to the parsing of the JSDoc description contents.

https://github.com/Turfjs/turf/blob/master/packages/turf-transform-translate/README.md
https://turfjs.org/docs/api/transformTranslate

Perhaps something like this could work?

/**
 * Moves any geojson Feature or Geometry of a specified distance along a Rhumb Line
 * on the provided direction angle.
 *
 * [method:planar]
 * [method:spherical]
 *
 * @function
 * ...

transformTranslate would currently only be [method:planar].

This is something we ultimately hope to apply to all Turf functions.