A new fill paint property to mask areas outside region of interest or polygon
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 12.4k
- Forks
- 2.4k
- PR merge metrics
- No merged PRs in 30d
Description
This is a feature request. The implementation details are unknown.
## Motivation
As a map designer, a common cartographic technique for me to focus the user attention to an area of interest is to mask/hide details of the areas outside the region of interest.
To accomplish such an effect with the existing GL style-spec, one needs to create a polygon covering the whole world with a hole of the desired region. This is a cumbersome and tedious data creation process for a map designer.
## Design Alternatives
- A new `fill-region: 'inside' | 'outside'` property for the existing fill layer. The 'outside' value would apply all the paint properties to all areas outside of the polygons in the layer if set https://github.com/mapbox/mapbox-gl-js/issues/6267#issuecomment-369928098
- ~~A new `inverted-fill` layer type which will apply a fill style to all areas outside of a polygon~~
- ~~New `inverted-fill-x` properties for all existing fill properties~~
## Design
Adding a new `fill-region` paint property is simple and communicates clearly to the user where the paint is applied in relation with the polygon.
~~Feel that maybe a new `inverted-fill` layer type might be the simplest with respect to keeping the style-spec clean~~
### Mock-Up
What will this design look like to developers?
```
map.addLayer({
'id': 'area of interest',
'source': 'aoi',
'type': 'fill',
'layout': {},
'paint': {
'fill-region': 'outside',
...any supported fill properties
}
});
```
What will this design look like to end users?

_[Image source: inverted fill in qgis](https://gis.stackexchange.com/questions/153754/inverted-shading-with-polygons-in-qgis-2-8)_
### Concepts
`fill-region` is the new concept that would be introduced. This feature is called "inverted polygon" in [qgis](http://oslandia.com/en/2014/06/14/masking-features-in-qgis-2-4/).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing GL style-spec for the fill layer and the map.addLayer example, then trace how fill paint properties are applied to polygons. Resolve the fill-region behavior, including its default and outside cases, and define the rendering and validation work needed for the feature to be complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- computer-graphics, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100