Clarify in convertLength documentation usage of degree and radian units

[stebogit]

Working on a line grid module, copying from the @turf/rectangle-grid package, I stumbled upon this inconsistency. Is it possible convertLength is off or am I missing something obvious here?

const nw = turf.point([-120.20778894424438, 47.40590873190948]);
const ne = turf.destination(nw, 1, 90, { units: 'kilometers' });
const sw = turf.destination(nw, 1, 180, { units: 'kilometers' });
const se = turf.point([ne.geometry.coordinates[0], sw.geometry.coordinates[1]]);

const box = turf.bboxPolygon(turf.bbox(turf.featureCollection([nw, ne, sw, se])))

const dKm = turf.distance(nw, ne, {units: 'kilometers'});
const width = Math.abs(nw.geometry.coordinates[0] - ne.geometry.coordinates[0]);
const widthKm = turf.convertLength(width, 'degrees', 'kilometers');

console.log(dKm); // 1.0000000000004476
console.log(widthKm); // 1.4792675889975462

The earth's curvature can't justify such big difference in a 1km distance.

The way the bbox's width is calculated above is the same logic used now (recently updated) in defining the rectangle/square grid features, but that should produce an incorrect grid result. Though I'm not sure those changes have been already published since the output of the square grid seems fine.
@rowanwins any thoughts?

[tunnelpuzzle]

I think the issue is subtracting the latitude won't give you the correct degree distance.

const width = Math.abs(nw.geometry.coordinates[0] - ne.geometry.coordinates[0]); // 0.013287829229710724
const widthDistance= turf.distance(nw, ne, {units: 'degrees'}); // 0.008982708286552414

If your starting point was at [0, 0] for example instead of [-120.0, 47.0] it would work.

[smallsaucepan]

This sounds like it wasn't an issue in the end? Closing but please reopen if it was a problem with convertLength.

[twelch]

@smallsaucepan looks related to the recent #2638 and possibly the changes made in #2106? And a difference in how turf.distance and turf.convertLength work. If the difference is expected, the goal of this issue might just be to clarify the behavior (and maybe underlying earth model) of each, which could make it's way into the API docs.

[twelch]

I wouldn't mind updating the docs if someone could explain the difference.

[smallsaucepan]

This is working ok. The distance between two longitudes (nw.geometry.coordinates[0] - ne.geometry.coordinates[0]) varies with latitude though. So we can't just subtract them and use that as an "angle" to feed into convertLength().

I've had in mind to add a "Units" page to the website for a while. Let's leave this open to be resolved by the addition of that page - including gotchas when using degrees and radians as units.

[smallsaucepan]

@twelch can we consider this covered by PR #2748, which adds a cautionary note to the Units documentation about using degrees and radians? That page would eventually be linked to from many pages, including convertLength.

[twelch]

Yes, @smallsaucepan the addition of Units docs is sufficient for me to close this.