Add mask

[cotegeo]

Good morning,

I'd like to put a mask layer on my app. I saw on a forum it exists a property 'fill-region' with values 'inside' and "outside". But this doesn't work. The console returns "unknown property". Is there a property that enable to make mask ?

Thanks

Sylvain BECQUAERT

[HarelM]

The slack channel is better for these kind of questions, but I'm not sure I fully understand the requirements.
Maybe a mock up of what you want to do can help here.
Also I would advise to consult the spec docs here:
https://maplibre.org/maplibre-style-spec/

[bameyrick]

This is a feature I would also be very much interested in, and would like to help to implement - but would likely need support in understanding how MapLibre works.

Use case

I'm not sure if my use case is the same as what @cotegeo has in mind but we've been rendering Cloud Optimised GeoTiffs to a raster layer using @geomatico/maplibre-cog-protocol. We have functionality where we only want to render data within user selected country boundaries, but because the COG has data for the whole world we want a mask layer above the COG layer to hide everything but the selected countries.

Unmasked	Masked

---

Masking via a custom layer

I recently managed to create a proof of concept masking layer that implements CustomLayerInterface. It's quite a rudimentary solution that only works with mercator projection, but it would be great to have this natively supported as I think it could run much more efficiently and maybe also support globe projection.

The custom layer:

1. Accepts an array of Feature<Polygon>.
2. Converts each polygon to vertices (using earcut).
3. Uses stencil buffering to draw the polygon vertices and then extract them from a quad that covers the entire screen.

There is example code in this discussion where I was struggling with the stencil buffer but then found a fudge to fix the rendering issues that I won't bother duplicating here, but when I was bumbling around maplibre-gl-js's source code could sort of understand that there are classes and methods of things like stencil mode, subdivision, etc that seem like the sort of things needed to create a mask layer (just in a much more optimised way).

---

Proposal

As @cotegeo mentioned, I think it would be good to add a fill-region paint option to the existing fill layer where you can specify outside or inside where inside is the default and existing functionality of a fill layer, and outside creates a mask by painting the inverse.

This would be good as theoretically the masking could work with a VectorTileSource or GeoJSON source and even use filter expressions to pick what is not masked out.

Potential issues

The issue with this approach is that the mask is just a painted colour so if you had raster tiles below as your base map they would be hidden too.

Alternative approach

Maybe a better solution would be to add masking to raster layers to only paint the pixels of the raster within the provided polygons, but I have no idea if that is even possible, and if being able to provide raster layer with a vector source to mask with alongside the raster source would be messy.

---

Although I am keen to help add functionality like this I wouldn't even know where to start or what the best approach to take would be, but I am happy to try figure it out with some guidance 😊

[HarelM]

Is this a dynamic change you need to do? Otherwise you could:

1. Change the data
2. Change the plugin to support clipping

[bameyrick]

Yes it would need to be dynamic as users can select any combination of admin boundaries which we then subtract from the mask.

By

Change the plugin to support clipping

do you mean the cog protocol plugin used for loading the tiles?

[HarelM]

Yes.
I'm not sure how such masking can be dynamic without affecting all layers etc.
In any case, feel free to open an issue with a spec change proposal in the maplibre-style-spec repo.
Please provide as many information as possible and also sdd it to the monthly meeting agenda.

[bameyrick]

Cool, thank you @HarelM. I have been experimenting with achieving masking in the protocol too, so I will continue with that and I can use what I find to feed into the spec change proposal 👍