Module TerrainMask
See also

Aim of module

Identifies open terrain parts of a DSM input raster using the volume based approach by Piltz et al. (2016).

General description

The basic input for Module TerrainMask is a DSM raster (inFile) in GDAL (GeoData Abstraction Library) readable format. The resulting mask (outFile) is stored as a binary raster file again in a GDAL supported format. A pixel value of 0 hereby denotes (open) terrain areas and 1 off-terrain objects (vegetation, buildings, power lines, etc.). The volume based filtering apporoach is controlled by two parameters: (i) the minimum height (minHeight) necessary to classify elevated objects as off-terrain and (ii) the maximum width (maxWidth) denoting the admissable size of such an elevated object (i.e. maximum building length/width). The algorithm processes the input DSM in axis parallel and diagonal profiles (N-S, E-W, NW-SE, SW-NE) and runs the classification separately for all four directions. A simple voting scheme combining the results of all four directional masks is applied to obtain the final terrain mask. The parameter (minConsensus) hereby denotes the minimum number of (directional) masks classifying a certain pixel as elevated. If debugOutFile is activated the four directional masks are additionally saved to disk allowing arbitrary post-processing.

The basic off-terrain classification strategy is demonstrated for a single profile in Figure 1.

Fig. 1: Basic principle of volume based terrain masking by calculatig the so-called <em>normalized volume above ground</em> (cf. Piltz et al., 2016).

For a certain location x within the scanline and a certain width w the normalized volume above ground is calculated as the sum of "pixel elevation minus reference elevation minus minimum object height (nvag)". The reference height is defined as the higher elevation of the pixels neighboring the start and the end location (x-1 and x+w, respectively). If nvag is greater than zero the respective profile range (w) is a potential off-terrain candidate. The optimum (non overlapping) set of x/w combinations is found by solving a longest path problem in a graph where each x is a vertex and each x,w pair an edge between x and x+w with a weight of nvag(x,w). For more details please refer to the cited literature.

Parameter description

-inFileinput raster file
Type: opals::Path
Remarks: mandatory
Import raster image in GDAL supported format,
-outFileoutput raster file
Type: opals::Path
Remarks: estimable
Path of filtered raster image file in GDAL supported format.
Estimation rule: The current directory and the name (body) of the input file are used as file name basis. Additionally, the postfix '_dtm' plus the output format specific extension is added.
-oFormatraster file format [GTiff,AAIGrid,SCOP,...]
Type: opals::String
Remarks: estimable
Use GDAL driver names like GTiff, AAIGrid, USGSDEM, SCOP... .
Estimation rule: The output format is estimated based on the extension of the output file (*.tif->GTiff, *.dem->USGSDEM, *.dtm->SCOP...).
-minHeightminimum height
Type: opals::Vector<double>
Remarks: default=0 0 0.1 0.1 1 0.5 5 1 10 2 50 3 100 5
The minimum height above ground of an extended object (building, vegetation, power line), to be considered as a potential off-terrain object. The minimum height can either be specified as a contant value or as a width dependent function (lookup table. In the latter case a series of width/height value pairs is expected with monotoneously ascending values of, both, width and height (e.g. 0.0 0.0 1.0 0.1 5.0 2.0 50.0 3.0)
-maxWidthmaximum width
Type: double
Remarks: default=100
The maximum width of an off-terrain object. The size should correspond to the largest object (e.g. warehouse) in the scene. Please note, that larger values increase the processing time.
-minConsensusminimum consensus
Type: int32
Remarks: default=3
The filter algorithm processes four directional masks separately. The final decision if a pixel is classified as elevated is made based on a consensus voting. The -minConsensus parameter denotes the minimum number of masks classifying a certain pixel as elevated.
-noDatanodata value
Type: float
Remarks: default=9999
Value representing an undefined value in the output raster model
-debugOutFileindicator for preserving temporary products
Type: bool
Remarks: default=0
If activated, all intermediate products (i.e. directional masks) are written to disk.


The data used in the following examples can be found in the $OPALS_ROOT/demo/ directory. Please use the following commands to generate a DSM.

opalsImport -inFile G*.las -outFile G.odm -filter echo[first] -tileSize 50
opalsCell -inFIle G.odm -outFile dsm0.tif -feature max -cell 1
opalsStatFilter -inFile dsm0.tif -outFile dsm1.tif -kernelSi 5 -kernelShape square -fea mean
opalsAlgebra -inFile dsm0.tif dsm1.tif -outFile dsm.tif -formula r[0]?r[0]:r[1]
opalsShade -inFile dsm.tif

The following command extracts the DTM mask considering a minimum object height of 3m and maximum object width of 60m.

The resulting DTM mask is shown in Figure 1.

Fig 1: Terrain grid mask

Running the command

prints the usage screen.


Piltz, B., Bayer, S., and Poznanska, A. M.: Volume based DTM generation from very high resolution photogrammetric DSMs, Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci., XLI-B3, 83-90, doi:10.5194/isprs-archives-XLI-B3-83-2016, 2016.

lw, gm
@ maxWidth
maximum (object) width
@ minConsensus
minimum level of consensus
@ first
apply transformation to the first grid before subtracting
@ minHeight
minimum (object) height
opalsAlgebra is the executable file of Module Algebra
Definition: ModuleExecutables.hpp:13
opalsImport is the executable file of Module Import
Definition: ModuleExecutables.hpp:113
opalsTerrainMask is the executable file of Module TerrainMask
Definition: ModuleExecutables.hpp:233
@ mean
opalsStatFilter is the executable file of Module StatFilter
Definition: ModuleExecutables.hpp:213
@ square
square kernel (Chebyshev metrics))
opalsCell is the executable file of Module Cell
Definition: ModuleExecutables.hpp:23
@ filter
string to be parsed in construction of DM::IFilter (various modules)
@ feature
Use a statistic feature of the boundary gap points for filling.
@ formula
formula string for albegraic grid computations (opalsAlgebra)
opalsShade is the executable file of Module Shade
Definition: ModuleExecutables.hpp:198