Home

Welcome to the mask plugin homepage!

Mask plugin was developped by Xavier Culos (AEAG) and contributed by Hugo Mercier (Oslandia) on funding by Agence de l'eau Adour Garonne.

That tool is designed to help users to quickly generate cartographic masking layer to enlight an area of interest. French readers can find a brief story of its genesis here.

Current features are:

• creates or modify a mask relying on current polygon selection (on active layer)
• creates or modify a mask via a call of do_mask function so that mask can be called programmatically from other plugins
• opens a dialog to choose mask layer properties:
  • style options (default is inverted polygon renderer + border shading)
  • buffer around mask
  • filter labels of features falling outside area of interest (achieved by a $in_mask boolean filter on labeling placement options)
  • choose mask layer format (Memory or any OGR datasource)

See tutorial video here https://www.youtube.com/watch?v=u29yGSQhX2g

#How to use it ? ##Quick mask

1. Select some polygon feature(s) on a vector layer
2. Hit Mask Button
3. Choose mask properties (default should be just fine)

##Advanced properties

Style

This is QGis style chooser widget. You can save you style as a default for the plugin, and use Qgis style library to store different preformated styles. Current style relies on the inverted polygon renderer. Be aware that switching to another renderer will cover your zone of interest, not the area outside.

Buffer

It is possible to enlarge mask geometry by applying a buffer on it. Units parameters is the size of the buffer, in map units (meters for most projections) [https://github.com/aeag/mask/blob/master/doc/buffered_mask.png](buffered mask)

On the fly simplification

This option allows to speed up map drawing, but can lead to artefacts in geometry that could change spatial intersection with labels. The algorithm deletes geometry vertices that are not useful at a given scale to draw correctly the object. In clear, a tolerance of 1 pixel will keep only 1 node per pixel, raising it above one pixel will start to be visible on screen.

Labeling filters

Checking lines in that listbox will filter label drawing based on label position. If label anchor point is spatially falling inside mask feature, it will be displayed, otherwise it won't. This is achieved thanks to python variables and functions that are added to qgis instance:

• $mask_geometry : this is the geometry stored in one variable. You can use it to generate your own expressions (area, bounding box, spatial relations)
• $in_mask() : this is a function that returns 0 or 1 if label is outside or inside mask feature. A layer label being spatially filtered will have that function filled and activated in label placement properties. it takes srid epsg code as an argument : in_mask(4326)

Filtering is operated using different spatial operators depending on geometry types (line, points or polygons) of labeled layers. An option allows to switch between different algorithm, faster ones are using centroid and approximated computations, slower ones are using exact computations (PointOnSurface).

Output format

Default output is memory layer. A memory layer is not saved, except if you have Memory Layer plugin loaded. We highly recommend it. For some use case such as embedded layers or qgis server, memory layers can't be accessed when opening a project file. It is then useful to save mask as ogr datasources (shp, sqlite, tab, gpkg, etc). We recommend then to keep the habit of storing that datasource along the project file, with the same base name, because masking maps belongs strongly to project use. Be aware too that it is not designed to support multi-user use cases. usingO OGR datasources could corrupt data. Memory layer saver datastream (a .qgs.mldata file) could also be corrupted with two users saving projects concurrently.

##In Atlas map generation workflow: autogenerate mask features QGIS can automate map generation based on a "coverage layer". It is a polygon layer that will be iterated to zoom on, pick some attributes to customize titles, pages names, styles and so on. Having the ability to mask the coverage area can be done with symbology rules, but it's for advanced users. And that won't filter labels on the fly. If mask plugin is loaded, and a mask has been set (please do not rename it), it will then automatically be applied to each Atlas iteration. Some issues existed in version <=1.4, please upgrade to solve them.

##Call it from a plugin or python script of your own (API) Mask plugin is exposed to python. It is then possible to code some process and call mask generation at some point. It is especially useful with place finder tools.
example snippet using some existing WKT string to make a geometry

from mask import aeag_mask
mymapcrs = 4326
masklayerName = 'mask_layer'
mygeometry = QgsGeometry.fromWkt(aWKTstring)
aeag_mask.do(mymapcrs, mygeometry, masklayerName)