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)
slope Plane steepest slope [%]
slpDeg Plane steepest slope [deg]
slpRad Plane steepest slope [rad]
exposition Plane slope aspect [rad] (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::Path
Remarks: mandatory
Import raster image in GDAL supported format,
-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>
Remarks: mandatory

Possible values:  
  sigma0 ....... sigma 0 of grid post adjustment (i.e. of the unit weight observation)
  slope ........ steepest slope [%]
  slpDeg ....... steepest slope [deg]
  slpRad ....... steepest slope [rad]
  exposition ... slope aspect [rad] (azimuth of steepest slope line, N=0, clockwise)
  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: int
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.
-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).

opalsGridFeature -inFile albis.tif -feature slope expos normalx normaly

Since only the input file (albis.tif) and the feature list (slope, expos, 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_expos.tif, etc).

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

opalsAlgebra -inFile albis_expos.tif -outFile albis_expos_deg.tif -formula r[0]*180./pi
opalsZColor -inFile albis_expos_deg.tif -palFile aspectPal.xml
opalsZColor -inFile albis_slope.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