Discussion on improving grid functions

[twelch]

Capturing some grid function related things I've been researching in one place for discussion and just awareness.

I noticed there's been some changes in behavior for at least the squareGrid/rectangleGrid functions in 2021 where something seems off/incorrect, or just don't do quite what the docs imply (for example that specifying units for cellSide will return cells that are equidistant in those units).
#2638
#2136
#2203

In addition, across all issues open/closed I see a call for the grid functions (hexGrid, squareGrid, rectangleGrid, triangleGrid, pointGrid?), to construct grids that meet different constraints. For example:

1. Grids that fit perfectly within bounding box provided (exactFit), rather than just the maximum cells that still fit within the bounding box without going over, and then centering the grid (current)
2. Grids whose cells are exactly the same height/width in the units specified (currently optimized for degrees but many/most? users want fixed unit lengths like kilometers, miles) squareGrid result is only square in the unit of degree #2638
3. Grids that are rotated to a given bearing (edge case)
4. Aligning different grids and/or producing sub-grids (edge case) Aligning grids with different cellSides #2013

Possible solutions include:

• Start with improving the grid function docs to more specifically describe their behavior, so people know what they can expect.
• Fix the functions to do what they were intended to do (be able to provide units and the resulting grid cells will be equidistant in those units)
• If needed, support multiple methods within each function rather than a one-size-fits-all approach that doesn't meet most needs. Or if the different options needed are too varied, create multiple functions.

[smallsaucepan]

Two areas to maybe address before deciding on an approach:

First is to decide what exactly are we giving someone when they ask for a rectangle? Is it the corners of a spherical rectangle like you'd see on the surface of the Earth? Or a planar rectangle on a 2D projection? Those points will differ more and more as you get further toward the poles. The former is more accurate and consistent, whereas the latter will "look nicer" on a map. I'm firmly team "spherical earth" - I'd want this to work as well in Sweden as it does in Kenya.

Second is that the way we define the API seems odd. We have a bounding box, and then a cell width - which isn't guaranteed to be an exact multiple of the bbox edge, so we fudge that by re-centering which then leads to issues like #2013 . Would seem neater to choose between:

• starting point, number of cells, and cell width - leaving the overall bounding box undefined
• bbox, number of cell divisions - width is calculated making sure to fit an exact number of cells

I can imagine use cases for both, so perhaps warrants splitting into two functions.

[smallsaucepan]

Here's my proposal. What do you think @twelch?

As soon as possible roll back #2106. This would close #2638 but reopen #2079. Update the docs for the grid functions to warn the bounding box must span less than 180 degrees latitude.

There might still be a simple enough fix for 2079? Suspect we'd need to somehow infer the winding of the bbox to figure out the user wants us to take the "long way round". Maybe the original reporter @stollc could weigh in?

Then for v8 as it would be a breaking change, we simplify the behaviour of the grid functions so that the user provides either:

• starting point, number of cells, and cell width - leaving the overall bounding box undefined
• bbox, number of cell divisions - width is calculated making sure to fit an exact number of cells

Overall we aim to have Turf do a couple of basic functions predictably and correctly, and push any remaining calculations and complexity back onto the user. Trying to cater to all potential use cases (rotations, centering, subgrids) is only going to lead to us doing none of them well.