Terrain Task

A terrain dataset is a digital terrain model optimized for visualization in a browser and is generated by this terrain job. Terrain datasets can be created from raster-based digital terrain models (GeoTIFF, TIFF, ASCII) or an OBJ-TIN. The output format of the conversion job is Cesium Quantized Mesh. The data is tiled according to the Tile Map Service (TMS).

Basic Information

Click to show more information

Runtime and Tiling

The following table shows the default calculated maximum level, which is determined based on the input resolution of the data:

Resolution Maximum Level

< 0.3 m

20

< 0.6 m

19

< 1.2 m

18

< 2.4 m

17

< 4.8 m

16

< 9.6 m

15

< 19.2 m

14

< 38.4 m

13

< 76.8 m

12

< 153.6 m

11

< 307.2 m

10

< 614.4 m

9

< 1228.8 m

8

< 2457.6 m

7

< 4915.2 m

6

< 9830.4 m

5

An area of ~500 km² at a resolution of 5 m can be processed in about 1 minute (using 8 threads) — the data volume may be about 50 MB. The same area at 2 m resolution takes about 25 minutes (using 8 threads) and the data volume may be about 500 MB. According to the table above, the first example is processed from level 15 and the second up to level 17, which shows a ~20× increase in processing time and data volume.

If breaklines are included, the processing time increases significantly, depending on the number and complexity of the breaklines. In the above examples (19 m and 2 m) with ~25,000 breakline segments, the processing time changes from 20 seconds and 25 minutes to 20 minutes and 60 minutes, respectively. For higher resolutions and/or larger areas with breaklines, jobs can take several days.

Processing time scales with:

  • the resolution of the input data

  • the size of the area to be processed

  • the complexity of the included breakline lines

Preprocessing Checklist

Before starting a terrain job, the following should be checked:

  • The raster and GeoJSON files (breaklines) use the same coordinate system.

  • The raster resolution is really necessary; consider downscaling if needed (especially for breaklines).

  • Breaklines are not overly complex (generalization algorithms can be considered here).

  • There are no duplicate breaklines, and the breakline file contains only line features (no points or polygons).

  • There are no overlapping hard/soft polygons.

  • Polygon files should be topologically correct.

Step 1

Option Description

Task Name

Name of the task.

Create or overwrite Datasource

Select whether to create a new datasource or overwrite an existing one

Datasource Name

If an existing data source is to be overwritten, select the source here.

Step 2 (Task Settings)

Required Settings

Option Description

Input Type

Select the input type: Raster (TIFF, GEOTIFF, ESRI ASCII Grid) or TIN (.obj).

Path to input data (e.g. path\\*.asc or path\\data.asc)

For raster inputs, either a directory wildcard (e.g. path\*.asc) must be specified to include multiple files, or a specific file (path\\data.asc). The path can be local on the server or a network path. For TIN inputs, either a single .obj file must be specified or a wildcard (path\\*.obj) for multiple files. To use different .obj files for different levels, a comma-separated list should be specified. See the following example.

EPSG Code

For raster or TIN inputs, the EPSG code (code for the coordinate reference system / CRS [see also: https://epsg.io/]) of the input dataset must be specified.
Example for different .obj files for different levels:

15,C:\\path\\to\\highres1.obj,C:\\path\\to\\highres2.obj,12,C:\\path\\to\\lowres.obj

In this example, highres1.obj and highres2.obj are used for level 15 (and generalized for subsequent levels down to level 12), while lowres.obj is used for level 12.

Additional Terrain Information

Option Description

Path to fold-lines (.json, optional)

Here you can specify the path to a fold-line (breaklines) file. The file must be in GeoJSON format. The file must use the same CRS as the input data and may only contain line features. All fold-lines must be within a feature collection. Here are some notes on fold-lines Checklist.

Disable lighting effects on terrain (Default: false, optional)

If true, lighting effects on the terrain are disabled. Edges in the terrain will be rendered less realistically.

Cut fold-lines into mesh (Default: false, optional; TIN inputs only)

If true, the fold-lines are cut into the provided .obj TIN. Set false if the fold-lines were already used when creating the .obj TIN; in this case, the fold-lines only affect lighting.

Path to soft-polygons file(.json, optional)

Here you can specify the path to a GeoJSON polygon file used to create soft breaks/edges (raster or TIN only). Each polygon must contain a property with the polygon height. Sloped polygons are not supported.

Path to hard-polygons file (.json, optional)

Here you can specify the path to a GeoJSON polygon file used to create flat planar surfaces with sharp boundaries at fixed heights (raster or TIN only). Each polygon must contain a height property. Sloped polygons are not supported.

Buffer within hard-polygons (Default: 0.2)

Specifies the XY distance between lower and upper edge used to create hard edges. This helps to mitigate artifacts caused by vertical walls/cliffs (raster or TIN only).

Name of the property that indicates the height in the JSON file (Default: height, optional)

Specify the property name of the attribute for polygon heights if it differs from height (raster or TIN only).

Advanced Settings

Option Description

Number of threads (Default: 4, optional)

Number of threads used for tiling and processing (Default: 4).

Log level (optional)

Optional log level of the LOG file: debug, info, warning, error.

OGC WKT String (Default: empty, optional)

Allows specifying an unknown or other coordinate system. For example, here is the OGC WKT string for EPSG:25832

Additional optional parameters (space separated, optional)

Specify expert parameters (see list below).

Additional Optional Parameters (Expert)

Use these optional parameters to fine-tune processing:

--offset <arg>         (Default: 0)      # Specify offset in meters; positive raises terrain, negative lowers it
--from <arg>           (Default: 8)      # Level from which breaklines are considered (min. 8; Quad Tree only)
--to <arg>             (Default: 9999)   # Level up to which breaklines are considered (Quad Tree only)
--from-level <arg>     (Default: 0)      # Level from which terrain files are created (TIN and raster only)
--to-level <arg>       (Default: 20)     # Level up to which terrain files are created (Default for raster is calculated from resolution)
--decimate-ratio <arg> (Default: 30)     # Reduction rate in percent (higher = more vertices removed) for generalization
--complete <arg>       (Default: 0)      # Set true to generate only tiles that are completely filled with data
--block-overlap <arg>  (Default: 250)    # Overlap of 5000 x 5000 raster blocks to avoid direct disk reading
-h                     # Show help (aborts job and lists available parameters in job log)
Example for an OGC WKT String:

EPSG:25832: PROJCS["ETRS89 / UTM zone 32N",GEOGCS["ETRS89",DATUM["European_Terrestrial_Reference_System_1989",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG","6258"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4258"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",9],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","25832"]]

Step 3

Option Description

Start Job as soon as possible

Start the job immediately.

Start Job once at given time

Schedule job for a future time.

Repeat Job

Automatic periodic execution of the job.

Publish Job after Completion

Once conversion is successful, the datasource is published automatically.

Resume or Restart Aborted/Failed Jobs

If a terrain job is aborted or unexpectedly fails, you can resume or restart it by clicking "Restart" in the job bar. The job will then be started again with the same settings. Already processed tiles will be skipped, so only the failed or unprocessed tiles will be recalculated.

Further Notes

Preprocessing Checklist

Before starting a terrain job, the following should be checked:

  • The raster and GeoJSON files (fold-lines/breaklines) use the same coordinate system.

  • The raster resolution is really necessary; consider downscaling if needed (especially for fold-lines/breaklines).

  • Fold-lines/breaklines are not overly complex (generalization algorithms can be considered here).

  • There are no duplicate fold-lines/breaklines, and the fold-line/breakline file contains only line features (no points or polygons).

  • There are no overlapping hard/soft polygons.

  • Polygon files should be topologically correct.

Additionally:

  • Avoid vertical breakline structures (segments with identical XY but different Z values). These can cause rendering artifacts.

  • If artifacts occur along hard polygon edges, increase the value for Buffer within hard-polygons.

  • For TIN inputs (*.obj), specify the breaklines used to create the TIN to improve lighting.

  • For large areas, it is recommended to create a low-resolution "base terrain" and use multiple terrain mesh-in-mesh jobs for smaller, high-resolution areas within the base terrain.