Home | Docs | Issue Tracker | FAQ | Download | |
Date: | 2011/11/30 |
---|---|
Author: | Thomas Bonfort |
Author: | Alan Boudreault |
Contact: | tbonfort at terriscope.fr |
Contact: | aboudreault at mapgears.com |
Last Edited: | 2012/05/11 |
Status: | Implemented |
Version: | MapServer 6.2 |
For some applications, it is desirable to mask out one or more layers so that only the features that intersect another set of features are rendered in the returned image. While it is relatively trivial to achieve this goal with sql joins if all the data is stored in postgis, the task becomes much more evolved or even impossible if the layer to be masked, or the layer to use as a mask, comes from a shapefile or a raster datasource.
A example use-case for this could be rendering meteo data for a given client, but only on the areas where the client has purchased the service. In this case, the meteo data should only be rendered on the areas covered by a set of polygons that represent the purchased areas.
Another example use-case given an input DEM raster, could be to only render data where the elevation is comprised in a given range.
To achieve these goals, the present RFC proposes the introduction of “MASK” layers, where only the features that intersect the given mask are rendered onto the final image.
In order to work with all layer types, this RFC proposes to implement layer masking at the pixel level, with the addition of a single “MASK” mapfile keyword. The MASK keywords is placed at the layer level, and takes a single argument which is the name of another mapfile layer that should be used as a mask.
The mechanism to achieve masking at rendering time is:
Example of MASK usage:
LAYER
NAME "parcels"
TYPE POLYGON
STATUS OFF
DATA "the_geom from parcels where clientid='%token%'"
CLASS
STYLE
COLOR 0 0 0
END
END
END
LAYER
NAME "meteo"
STATUS ON
TYPE RASTER
DATA "raster.tif"
MASK "parcels"
END
Note
The layer used as a mask will be rendered in the final map image if its status is set to DEFAULT, or if its status is set to ON and the layer name is included in the requested layers. Most users of this feature will probably want to set the mask layer to STATUS OFF.
The following files will be modified/created by this RFC:
mapserver.h/mapfile.c/mapfile.h/maplexer.l/mapcopy.c: parser and new layerObj members
mapdraw.c: implementation in msDrawLayer()
maplabel.c: implementation for dropping labels from the labelcache if they don't
intersect the mask layer in msAddLabel()
Getters and Setters will have to be added to programmatically add a MASK to a layerObj. No other issues are to be expected.
This change provides a new functionality with no backwards compatibility issues being considered.
There are no special cases to treat here aside from the classic ones (parsing errors, invalid layer referenced by MASK, invalid renderer selected)
Passed with +1 from ThomasB, MichaelS, StephenW, AssefaY, FrankW, TamasS, DanielM, JeffMcK, TomK, OlivierC, SteveL