Module GridFeature
See also

Aim of module

Derives feature models (slope, curvature, roughness, etc.) from grid models based on the local grid neighbourhood defined by a kernel.

General description

Apart from the terrain height, Digital Terrain Models allow the derivation of additional features based on the local grid neighbourhood. Important features are, for instance, the terrain slope and curvature. Although the most accurate results are obtained by deriving these features as a by-product of the surface interpolation using the original point cloud in Module Grid, there are a couple of advantages for deriving these features on raster basis:

  • the neighbourhood queries are much faster on grid basis compared to the point cloud
  • the data distribution in the grid is regular (optimal for feature derivation)
  • sometimes, only the interpolated grid is available but not the original point cloud
  • etc.

The grid features are derived by taking all grid pixels into account within a certain kernel environment defined by its size (kernelSize, i.e. the kernel radius) and its shape (kernelShape, i.e.: square, circle, diamond). The following figure illustrates some standard cases:

Figure 1: Standard kernel layouts; left: Chebyshev metrics, middle: Euclidian metrics; right: Manhattan Metrics

In general, the features are derived based on an appropriate underlying functional model. All slope related features, for instance, are calculated based on the best fitting plane defined by all valid grid points within the kernel. Curvature related features, in turn, are derived from a best fitting paraboloid. Multiple features can be calculated simultaneously simply be specifying a list of grid features (feature).

The following features are supported:

Feature Derived from description
sigmaz Plane sigma z of grid post adjustment (i.e. of the interpolated height)
sigma0 Plane sigma 0 of grid post adjustment (i.e. of the unit weight observation)
slpPerc Plane steepest slope [%]
slpDeg Plane steepest slope [deg]
slpRad Plane steepest slope [rad]
exposRad Plane slope aspect [rad] (azimuth of steepest slope line, N=0, clockwise)
exposDeg Plane slope aspect [deg] (azimuth of steepest slope line, N=0, clockwise)
normalx Plane x-component of surface normal unit vector
normaly Plane y-component of surface normal unit vector
kmin Paraboloid minimum curvature [1/unit]
kmax Paraboloid maximum curvature
kmean Paraboloid mean curvature: kmean=(kmin+kmax)/2
kgauss Paraboloid gaussian curvature: kgauss = kmin*kmax
kminDir Paraboloid direction (azimuth) of minimum curvature [rad]
kmaxDir Paraboloid direction (azimuth) of maximum curvature [rad]
absKmaxDir Paraboloid direction (azimuth) of maximum absolute curvature [rad]

For each specified feature a separate grid file is calculated. The output grid file names (outFile) can either be specified explicitly, in which case a user-defined file name has to be specified for each feature. In case no or only file name is specified, unique file names are automatically created by adding the eature name as a postfix. The output grid files containing the feature rasters are created in GDAL supported format (oFormat). Please note that the feature grids are created in the same structure (resolution/extent) as the input DTM (inFile). Optional user defined limits can be specified to restrict the area of interest (limit). Please note that, irregular limits are automatically aligned to the grid structure of the input raster as re-sampling is strictly avoided.

Parameter description

-inFileinput raster file
Type: opals::RasterBand
Remarks: mandatory
The raster band to extract features for.
RasterBand: File path of a raster dataset with optional specification of a zero-based band index or band name (default: 0).
See Supported grid/raster formats
Syntax: filePath [':' (bandName | bandIndex)]
-outFileoutput raster file
Type: opals::Vector<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 and the extension are constructed according to the specified grid feature and oFormat (e.g. '_slope.tif').
-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...).
-featuregrid feature models to be calculated
Type: opals::Vector<opals::GridFeature::Enum>
Remarks: mandatory
Possible values:  
  sigma0 ....... sigma 0 of grid post adjustment (i.e. of the unit weight observation)
  slope ........ steepest slope [%] (deprecated: use slpPerc instead)
  slpPerc ...... steepest slope [%]
  slpDeg ....... steepest slope [deg]
  slpRad ....... steepest slope [rad]
  exposition ... slope aspect [rad] (deprecated: use expoRad instead) 
  exposRad ..... slope aspect [rad] (azimuth of steepest slope)
  exposDeg ..... slope aspect [deg] (azimuth of steepest slope)
  normalx ...... x-component of surface normal unit vector
  normaly ...... y-component of surface normal unit vector
  kmin ......... minimum curvature
  kmax ......... maximum curvature
  kmean ........ mean curvature: kmean=(kmin+kmax)/2
  kgauss ....... gaussian curvature: kgauss = kmin*kmax
  kminDir ...... Azimuth [rad] of minimum curvature
  kmaxDir ...... Azimuth [rad] of maximum curvature
  absKmaxDir ... Azimuth [rad] of maximum absolute curvature
  precision .... grid post precision (derived from sigmaz, pdens and slope)
The grid feature models are created in the same format and structure as the basic (input) surface model are derived. Please note that if more than one output file is specified, the number of output file names must match the number of specified features
-kernelShapekernel shape
Type: opals::KernelShape
Remarks: default=square
Possible values:  
  square .... square kernel (Chebyshev metrics))
  circle .... circular kernel (Euclidean metrics)
  diamond ... diamond kernel (Manhattan metrics)
To select a predefined shape of the (binary) kernel matrix.
-kernelSizekernel size (radius of kernel in pixels)
Type: int32
Remarks: default=1
To specify the kernel radius. A value of 1 corresponds to a 3x3, a value of 2 to a 5x5, [...] kernel.
-limit2D clipping window
Type: opals::GridLimit
Remarks: optional
If no user defined limits are specified or -limit is even skipped, the entire xy-extents of the input raster model are used.
GridLimit: Defines xy-limits for output grid/raster datasets. The limit coordinates specified by left/lower/right/upper either refer to pixel centers (default) or corners, and may optionally get rounded to multiples of the grid size.
Syntax: ['center'|'corner']['round']['(' left lower right upper ')']
-noDatanodata value
Type: float
Remarks: default=9999
Value representing an undefined value in the output raster model


The following examples rely on the grid model albis.tif located in the $OPALS_ROOT/demo/ directory.

Example 1: Slope rasters

This first example demonstrates how to derive different slope feature grids (slope/steepness, exposition/aspect, x/y components of surface normal vector).

Since only the input file (albis.tif) and the feature list (slpPerc, exposRad, exposDeg, normalx, normal) where specified, the default kernel settings (kernel radius: 1, kernel shape: square) were used. Consequently, for each grid point a best fitting plane was estimated using the grid point and its eight neighbours. The requested features are all calculated from this (tilted) plane. The names of the output grid files composed automatically based on the input file name and using the standard feature postfixes. (albis_exposRad.tif, etc).

The visualizations shown in Figure 2 are obtained with the following commands:

opalsZColor -inFile albis_exposDeg.tif -palFile aspectPal.xml
opalsZColor -inFile albis_slpPerc.tif -palFile slopePal.xml -scalePal 0.1
opalsZColor -inFile albis_nx.tif -interval 0.2 -palFile greyPal.xml -zRange -1 1
opalsZColor -inFile albis_ny.tif -interval 0.2 -palFile greyPal.xml -zRange -1 1
Figure 2: Slope feature visualizations

Example 2: Curvature rasters

In the second example different curvature rasters (minimum/maximum/mean/gaussian curvature) are derived. Hereby, a circular kernel shape and a kernel size (radius) of 2 pixels is used.

opalsGridFeature -inFile albis.tif -kernelSize 2 -kernelShape circle -feature kmin kmax kmean kgauss

Figure 3 shows colour coded visualizations of the resulting curvature rasters which were derived using the following commands.

opalsZColor -inFile albis_kmin.tif -palFile colorBrewer_SpectralPal.xml -scalePal -0.01,0.01 -interval 0.001
opalsZColor -inFile albis_kmax.tif -palFile colorBrewer_SpectralPal.xml -scalePal -0.01,0.01 -interval 0.001
opalsZColor -inFile albis_kmean.tif -palFile colorBrewer_SpectralPal.xml -scalePal -0.01,0.01 -interval 0.001
opalsZColor -inFile albis_kgauss.tif -palFile colorBrewer_SpectralPal.xml -scalePal -0.0002,0.0002 -interval 0.00002
Figure 3: Curvature feature visualizations
opalsZColor is the executable file of Module ZColor
Definition: ModuleExecutables.hpp:253
@ kgauss
gaussian curvature: kgauss = kmin*kmax
Definition: GridFeature.hpp:29
@ normalx
x-component of surface normal unit vector
Definition: GridFeature.hpp:23
@ exposDeg
slope aspect [deg] (azimuth of steepest slope)
Definition: GridFeature.hpp:22
@ normaly
y-component of surface normal unit vector
Definition: GridFeature.hpp:24
@ kmax
maximum curvature
Definition: GridFeature.hpp:27
@ kmin
minimum curvature
Definition: GridFeature.hpp:26
@ scalePal
scale factor to be applied to the given palette (opalsZcolor)
@ zRange
range of z-values to be used for z-coloring (e.g. opalsZcolor)
@ slpPerc
steepest slope [%]
Definition: GridFeature.hpp:17
@ exposRad
slope aspect [rad] (azimuth of steepest slope)
Definition: GridFeature.hpp:21
@ kernelSize
output grid size equals entire kernel size
@ kmean
mean curvature: kmean=(kmin+kmax)/2
Definition: GridFeature.hpp:28
@ feature
Use a statistic feature of the boundary gap points for filling.
@ circle
circular kernel (Euclidean metrics)
@ palFile
palette file (opalsZcolor)
opalsGridFeature is the executable file of Module GridFeature
Definition: ModuleExecutables.hpp:98