Turf design direction

[smallsaucepan]

Hi all.

Have been using Turf for a few years now. Recently though have needed to come to grips with a few bugs, and would like to submit a PR or two. Fixing some of the bugs could have (positive) flow on effects in other areas as well e.g. #1726 . Had some questions for the community / maintainers first though.

Saw a comment along the line of Turf uses different approaches in different areas and it's not really defined anywhere which it should be. Note I'm paraphrasing here! Is that still generally true? What's the best way to determine the correct approach?

For example #1726 above might be because Turf uses great circle calculations for distance, and the other systems mentioned use an ellipsoid. Should Turf do the same? Offer both? And would we make the default the current one (so as not to break anything) or the more appropriate / accurate / widely accepted one (to avoid building up technical debt)?

Appreciate any insights you can provide :)

Thanks
James

[twelch]

Hi @smallsaucepan. Great questions and a couple thoughts from me as a fairly new and somewhat inactive maintainer. My sense is that there is no one active maintainer that knows exactly what type of algorithm/approach is used for each function. The docs don't/never covered it, and in many/most cases the code comments don't specify either.

So what's the right approach here? I've pondered that the path out of this starts with:

• Add to documentation a comprehensive list of the approaches used in turf and their tradeoffs (e.g. cartesian/spherical, great circle/ellipsoid). Link to a research paper or other info. I personally don't feel like I have a full enough grasp to take this on, just enough to be dangerous.
• Document the approach each function uses (rediscover if necessary), linking to the approach list above.

In terms of offering a choice of the approach used for each function, I would look to how other projects tackle this in the geo space. I think this is a level up in complexity and is exactly what turf struggled to grow into.

• Maybe it's better to have one function for each approach with the approach part of the function name, instead of a swiss army function that handles all approaches. Consider that turf functions build on each other, so I can see that if the FunctionA depends on FunctionB, then FunctionA(approach='cartesian') should probably run FunctionB(approach='cartesian'). And by avoiding creating multi-approach functions, you don't have to decide whether to default to the fastest option or the most accurate option, you the user choose which option explicitly, the API is very flat.

[twelch]

You'll see that there's a similar past discussion around what type of indexing each function could/should offer, and whether the user should be able to specify the type of indexing used (e.g. protocol. #173. So the rabbit hole can go deeper.

From what I can tell, an indexing option has never been exposed to the user, rather indexing has slowly been added to functions to give them a performance boost using the best available algorithm that does not change the results accuracy/output (e.g. rbush, sweepline, etc.)

[smallsaucepan]

Thanks Tim. Agree that not overloading the function names is a good approach. Might use pygeo as a guide. Their distance module has great_circle() and geodesic() functions for example, and the user imports the one they want.

One approach might be to add an equivalent distance_geodesic() function to Turf, and then alter the export to something like:

export default distance_great_circle; // retains current behaviour
export { distance_geodesic, distance_great_circle }; // caller can import a specific one if they wish

Where that will get messy though is in dependant higher level functions like nearestPointOnLine, which calls distance. Would like to avoid the need for nearestPointOnLineGreatCircle AND nearestPointOnLineGeodesic, etc. A better way may be to provide a configuration object the user can customise once (a global) with their preferences (fast, accurate, cartesian, great circle, ellipsoid, rbush, sweepline, ...). Then the user just imports nearestPointOnLine and Turf respects their wishes. I'll look into that.

Happy to leave indexing until later. Better to get things working correctly, then worry about making them fast later.

If you want some help maintaining, happy to help there too. Spotted quite a few older bugs, PRs, etc that can probably be closed. I know the issue count is something I look at when deciding on a library.

[smallsaucepan]

Are we open to using a third party library to perform these calculations? Leveraging https://github.com/chrisveness/geodesy could save us implementing a lot of maths.