New parameter for Grid Generators + Modify behavior with masking

[Pitouli]

Hello,

When you generate a grid, you provide a bounding box, a dimension for the cells, and an optional mask.

Today, the grid is always CONTAINED inside the bounding box.

I would like to add an optional "size" option that could be either "contain" (default) or "cover", so in the second case the grid COVERS the bounding box.

Additionally, when you provide a mask, the cells that intersect with it are kept, which means that the grids COVERS the mask.
This create a weird behavior when you define your bbox from your mask: your mask becomes partially covered with cells (near the bounding box, cells are missing, elsewhere they are present)

I would like to align the behavior such as if the user as provide the "size=cover" option we keep the cells that intersect with the mask (like today) but if he provide the "size=contain" option then we keep only the cells contained within the mask.

Of course, if we want to avoid breaking change (at least while we are in v7) in order to release these features in the next minor update without breaking anything, I can define the size options with "cover", "contain", and "legacy" (or "mixed" ?) and use the third one as default.

I made a gist to show the three behaviors and the update I propose:
https://gist.github.com/Pitouli/c6cfffde0a2d8c0f8d220420f93104be

You can execute the code here to see it in your browser: https://turf-sandbox.netlify.app/

By having a purely "contain grid" and a purely "cover grid", it allows this interesting scenario: imagine you have 100k points and you need to know if the belongs to an area with a detailed boundary, you can create those two grids to eliminate very quickly the points that are clearly inside the area and those that are clearly outside, and you finally only have to apply the precise algorithm for the few remaining points.

What do you think? Should I proceed with PRs? Do you have better ideas for naming of the options and its values? Should I keep a "legacy" option?

[smallsaucepan]

Thanks for doing this work @Pitouli. Appreciate the level of detail.

I think I understand where you're going with cover vs contain. Seems like a worthwhile addition.

This create a weird behavior when you define your bbox from your mask

Would you mind putting together a quick example that shows this? A sandbox example, or even just a screenshot? I'm having some trouble visualising it.

Of course, if we want to avoid breaking change (at least while we are in v7) ...

The grid* packages are probably due for a breaking shakeup soon anyway. More info here, though it's likely the options and behaviour are going to change.

What do you think? Should I proceed with PRs?

Let's discuss it a bit more to come up with a plan. Taking the above into account, would you be interested in fixing the basic behaviour of grid* functions first, and then looking in to your suggestion? It might be the best way to make sure you don't have to do the cover/contain work twice. If you don't that's fine though.

Do you have better ideas for naming of the options and its values?

I would avoid using size - maybe maskBehavior or maskInteraction. Should the grid allow itself to be contained by the mask, or cover it completely?

Should I keep a "legacy" option?

I'm not the biggest fan of adding temporary legacy options to maintain backward behaviour. It complicates the interface, and ultimately you need to make a breaking change anyway to retire the legacy flag.

Would much rather Turf decide where it wants to end up, and then waiting to make a breaking change at the appropriate time without holding up other development.

Regardless of which approach we take, the project needs to find a way to track and manage breaking changes. Your idea might be an opportunity to try some different techniques.

[Pitouli]

Would you mind putting together a quick example that shows this? A sandbox example, or even just a screenshot? I'm having some trouble visualising it.

I shared a gist will all the code needed to reproduce the problem (and you can execute it online without having to install anything).

But I will try to make a better explanation with illustrations below :)

Let 's consider this area.

As a user, I need to create a grid over this area, for whatever reason. To create this grid, I need a bounding box, so I compute the bounding box of my area.

But, with the default algorithm, the grid will be CONTAINED in my bbox. So it does not completely cover my area. You can see it on the left and right side of the area (and if you zoom, on the top and bottom)

What is even stranger is that, with the current algorithm, if I use my area as a mask, it will consider that the cell is to be kept if it at least partially intersect with the area. So it means that random points in the resulting "grid" neither guarantee to be INSIDE the area (because the mask keep cells that go outside) neither guarantee that not being in the grid guarantee to be OUTSIDE of the ara (because the bbox does not keep cells that go outside).

That's why I propose to add a parameter to explicitly say if you need the grid to COVER your area or be CONTAINED in your area (area could be the bbox alone or the mask inside the bbox)

[Pitouli]

I would avoid using size - maybe maskBehavior or maskInteraction. Should the grid allow itself to be contained by the mask, or cover it completely?

About maskBehavior or maskInteraction naming, one thing to take into account is that there is a mask parameter, and this contain vs cover should not only apply to this mask but also to the bbox.

Unless of course we do two parameters bboxBehavior and maskBehavior to allow the user to have event more control (and we could even have a behavior parameter and have the two others that default to this main one...)

The grid* packages are probably due for a breaking shakeup soon anyway

Thanks for the link

Taking the above into account, would you be interested in fixing the basic behaviour of grid* functions first, and then looking in to your suggestion?

Not an expert, but I would be pleased to help on that matter considering how many turf packages I am using freely! ^^

I do not have any urgency anymore, because I have rewritten completely the method for my own usage so it can return three set of merged rectangles: those INSIDE, those OUTSIDE, and those PARTIAL (the last one is not visible on the picture)

So we can take the time to find the best solution to decide what should be the behavior of this function :)

PS: I can share my algorithm if you think it can be of interest (it is a sort of "area simplifier") but it is probably too specific for turf.

[smallsaucepan]

Thanks @Pitouli. I understand what you're referring to now.

If we consider this diagram:

This is the effect of an odd feature in the grid functions. If the size of each grid cell doesn't divide exactly into the size of the bbox, buffer rounds down to the nearest whole number and then centres the grid in the bbox. That's why in the image above there are the two uncovered sections.

As an example, if you have a bbox 10 wide, and ask for cells 1.05 wide, the max cells turf can fit without exceeding the bbox is 9. So you end up with 9 x 1.05 wide grid (width of 9.45) which turf then centers within the original bbox by moving the whole grid (10 - (9 * 1.05)) / 2 to the right. That's what's leaving parts of your mask uncovered. It's complicated by longitude varying with latitude, though that's the general idea.

This is the subject of #2640 - what do we need to do to remove the conditions that lead us to need to center the grid.

Not an expert, but I would be pleased to help on that matter considering how many turf packages I am using freely! ^^

Awesome. Thank you. If we were to remove the centering behaviour then buffer would behave more like newGridCover from your gist. Would you mind taking a deep dive into #2640 and letting us know your thoughts there?

PS: I can share my algorithm if you think it can be of interest (it is a sort of "area simplifier") but it is probably too specific for turf.

Please do. Once we've made buffer more predictable it might lead to extended cover / contain functionality, or even a new turf module. Would really appreciate that.