Module Isolines
See also

Aim of module

Derives contour lines (isolines) from grid models and stores them as a vector dataset.

General description

Contour lines are a convenient method to get a cartographic 2D representation of the 3D structure of a DTM. Typically an interval will be specified to get contour lines with equally spaced height intervals. The zRange may be specified optionally to reduce this height range. Individual levels may be specified alone or together with interval.

The contour lines can be additionally controlled by the following parameters: Small closed contours can be suppressed with parameter closeMin. Closed contours smaller than the given minimum area will not be written to the output file.

To derive the contour lines densification points will be calculated to get more pleasant results at the expense of calculation time. The calculation of these intermediate points may be suppressed by setting the option densification to false.

There is another option thinOut to reduce the number of points in the output file. The number of points is reduced by using the Douglas-Peucker algorithm. This is done by default using a very low perpendicular tolerance of 0.01 (1 cm) not to change the contour lines in an unexpected manner. Be careful using this parameter with higher values, because the local shape of contours may change unexpectedly.

Parameter description

-inFileinput grid model file
Type: opals::Path
Remarks: mandatory
The input grid model file is expected in a GDAL supported data format.
-outFileoutput file (contour lines)
Type: opals::Path
Remarks: estimable
The contour lines are stored as vector dataset. Estimation rule: input file name + '_iso' + <.ext>.
-oFormatoutput vector file format
Type: opals::String
Remarks: estimable
Supported vector formats: SHP
Estimation rule: The output format is estimated based on the extension of the output file (*.shp->SHP, ...).
-bandinput band number
Type: opals::String
Remarks: default=0
To select the desired band of a multi-layer input raster file. Bands are numbered from 1.
-intervalequidistance interval
Type: double
Remarks: optional
Equidistance interval for contour lines. If neither option -interval nor option -levels is specified, a reasonable interval will be estimated.
-levelsindividual levels
Type: opals::Vector<double>
Remarks: optional
Individual levels for contour lines ma be specified. If neither option -interval nor option -levels is specified, a reasonable interval will be estimated.
-zRangerange (zmin, zmax) for contour lines
Type: opals::Array<double, 2>
Remarks: optional
Range (zmin zmax) of z-values considered for output. Only contour lines within the given 'zRange' will be calculated. If not specified, the entire z-range of the input grid model is used.
-thinOutallowed lateral deviation for thinout.
Type: double
Remarks: default=0.01
Thin out contour lines with Douglas-Peucker algorithm. The maximum allowed deviation from the original contour line can be specified. Be careful if using this parameter because thinning out may have a bad effect on the form of contour lines.
-closeMinsuppress closed contours with area < closeMin
Type: double
Remarks: optional
If this parameter is specified closed contour lines with an area smaller than the specified value will not be written to the output file.
-minLengthsuppress short contours
Type: double
Remarks: optional
If this parameter is specified contour lines with a length smalles than the specified value will not be written to the output file.
-densificationintermediate densification of grid
Type: bool
Remarks: default=1
Iterpolate intermediate densification points to get more pleasant contours.Setting this option to 0 will switch off densification.


The data used in the subsequent examples are located in the $OPALS_ROOT/demo/ directory and the following preprocessing steps (data import and surface grid calculation) are required:

opalsImport -inFile fullwave2.fwf -iFormat FWF
opalsRobFilter -inFile fullwave2.odm -filter echo[last]
opalsGrid -inFile fullwave2.odm -outFile fullwave2_dtm.tif -interpolation movingPlanes -filter class[ground] -selMode quadrant -searchRadius 10
opalsShade -inFile fullwave2_dtm.tif
opalsImport -inFile flyover.laz -tileSize 100 -coord_ref_sys EPSG:5650
opalsGrid -inFile flyover.odm -outFile flyover_dtm.tif -interpolation movingPlanes -neighbours 8 -searchRadius 2 -selMode quadrant -gridSize 0.5
opalsShade -inFile flyover_dtm.tif

Example 1

The first example shows a typical run of opalsIsolines specifying the mandatory parameter inFile together with parameter interval.

opalsIsolines -inFile fullwave2_dtm.tif -interval 5

It produces contour lines from the DTM fullwave2_dtm.tif with a contour interval of 5 meters.

Output of Example 1

Example 2

In the second example only the mandatory parameter inFile is specified. Thus, the command is very short and simple:

opalsIsolines -inFile flyover_dtm.tif

It produces contour lines from the DTM flyover_dtm.tif with an equidistant interval estimated from the z-range of the DTM. The interval is estimated and rounded to a commonly used interval out of 10, 20, 25, 50 times a power of 10. In this case opalsIsolines estimates an interval of 1 m, which is fairly suitable. But typically one will specify an interval customized to the project (like in the first example).

Output of Example 2

Example 3

In example 2 we can see that in rough terrain we will get a lot of small closed contours. This type of fragmented contours are often not wanted in contour maps. We can suppress the output of such small closed contour lines specifying the additional option closeMin with a reasonable value for the minimum area of a closed contour line to be selected for output.

opalsIsolines -inFile flyover_dtm.tif -interval 1 -closeMin 10

In this case all closed contours with an area smalles than 10 square meters will be suppressed.

Output of Example 3

Example 4

Another option (zRange) allows us to limit the height range to a lower and upper limit. Only contour lines beetween these limis will be produced.

opalsIsolines -inFile flyover_dtm.tif -interval 0.5 -closeMin 10 -zRange 18.5 22.5
Output of Example 4

Example 5

It is also possible to generate contour lines of individual levels by using the option levels and explicitly specifying the wanted levels.

opalsIsolines -inFile flyover_dtm.tif -closeMin 10 -levels 21 22 22.25 22.5 22.75 23
Output of Example 5
@ quadrant
quadrant-wise nn selection, ie. nn per quadrant, then 2nd nn per quadrant, ...
@ closeMin
suppress closed contours with area < closeMin (opalsIsolines)
@ movingPlanes
moving (tilted) plane interpolation
@ coord_ref_sys
default coordinate reference system (EPSG Code, WKT string or PRJ-File)
@ last
last stage to be processed (opalsStripAdjust)
opalsImport is the executable file of Module Import
Definition: ModuleExecutables.hpp:113
opalsRobFilter is the executable file of Module RobFilter
Definition: ModuleExecutables.hpp:183
@ zRange
range of z-values to be used for z-coloring (e.g. opalsZcolor)
opalsIsolines is the executable file of Module Isolines
Definition: ModuleExecutables.hpp:123
opalsGrid is the executable file of Module Grid
Definition: ModuleExecutables.hpp:93
@ levels
individual height levels (e.g. opalsIsolines)
@ filter
string to be parsed in construction of DM::IFilter (various modules)
opalsShade is the executable file of Module Shade
Definition: ModuleExecutables.hpp:198