qm_tiler Usage
The main functionality of the project is provided by the qm_tiler
app. This tool allows to create tiles in the form of Triangulated Irregular Networks (TIN), in Cesium's quantized-mesh format. It implements several simplification algorithm, each of them having different parameters and properties.
Running the tool using the default parameters is as simple as:
qm_tiler -i <input_raster> -o <output_tiles_dir>
However, qm_tiler
allows to tune the creation of the multiresolution pyramid of tiles in many ways, and it implements several TIN creation algorithms, each with its own set of specific parameters to set. Consequently, if you run the help of the qm_tiler
tool, you will see that there are a lot of parameters that the user may tune:
$ qm_tiler -h
Creates the tiles of a GDAL raster terrain in Cesium's Quantized Mesh format
(*) The parameters marked with this sign can be specified multiple times to reflect the desired value per zoom level.
When the required zoom is larger than the number of specified parameters, the last one is used.
On the other hand, when a single parameter is specified, it is assumed to represent the value for the root level of the pyramid (i.e., zoom=0),
and the values for the deeper levels will be computed as value/2^zoom, for those parameters whose scale needs to be lowered at deeper levels,
or value*2^zoom, for those whose scale needs to grow with depth.
qm_tiler options::
-h [ --help ] Produce help message
-i [ --input ] arg Input terrain file to parse (can be
specified like this or as a positional
parameter)
-o [ --output-dir ] arg (=terrain_tiles_qm)
The output directory for the tiles
-s [ --start-zoom ] arg (=-1) The zoom level to start at. This should
be greater than the end zoom level
(i.e., the TMS pyramid is constructed
from bottom to top). If smaller than
zero, defaults to the maximum zoom
possible according to DEM resolution.
-e [ --end-zoom ] arg (=0) The zoom level to end at. This should
be less than the start zoom level
(i.e., the TMS pyramid is constructed
from bottom to top).
-b [ --bathymetry ] arg (=0) Switch to consider the input DEM as
containing depths instead of elevations
--samples-per-tile arg (=256) Samples to take in each dimension per
tile. While TMS tiles are supposed to
comprise 256x256 pixels/samples, using
this option we can sub-sample it to
lower resolutions. Note that a smaller
sampling provides a coarser base mesh
that will be easier to simplify.
--clip-high arg (=inf) Clip values in the DEM above this
threshold.
--clip-low arg (=-inf) Clip values in the DEM below this
threshold.
--above-sea-level-scale-factor arg (=-1)
Scale factor to apply to the readings
above sea level (ignored if < 0)
--below-sea-level-scale-factor arg (=-1)
Scale factor to apply to the readings
below sea level (ignored if < 0)
--num-threads arg (=1) Number of threads used (0=max_threads)
--scheduler arg (=rowwise) Scheduler type. Defines the preferred
tile processing order within a zoom.
Note that on multithreaded executions
this order may not be preserved.
OPTIONS: rowwise, columnwise,
chessboard, 4connected (see
documentation for the meaning of each)
--tc-strategy arg (=greedy) TIN creation strategy. OPTIONS: greedy,
lt, delaunay, ps-hierarchy, ps-wlop,
ps-grid, ps-random (see documentation
for further information)
--tc-greedy-error-tol arg (=150000 ) Error tolerance for a tile to fulfill
in the greedy insertion approach (*).
--tc-greedy-init-grid-size arg (=-1) An initial grid of this size will be
used as base mesh to start the
insertion process. Defaults to the 4
corners of the tile if < 0
--tc-greedy-error-type arg (=height) The error computation type. Available:
height, 3d.
--tc-lt-stop-edges-count arg (=500 ) Simplification stops when the number of
edges is below this value (*).
--tc-lt-weight-volume arg (=0.5) Simplification volume weight
(Lindstrom-Turk cost function, see
original reference).
--tc-lt-weight-boundary arg (=0.5) Simplification boundary weight
(Lindstrom-Turk cost function, see
original reference).
--tc-lt-weight-shape arg (=1e-10) Simplification shape weight
(Lindstrom-Turk cost function, see
original reference).
--tc-ps-border-max-error arg (=10000 )
Polyline simplification error at
borders (*).
--tc-ps-border-max-length-xy-percent arg (=20 )
Polyline simplification, maximum length
of border edges when projected to the
XY plane. Expressed as a percentage
[0..100] (*).
--tc-ps-features-min-size arg (=5) Minimum number of points in a feature
polyline to be considered.
--tc-ps-hierarchy-cluster-size arg (=1000 )
Hierarchy point set simplification
maximum cluster size (*).
--tc-ps-hierarchy-max-surface-variance arg (=1000 )
Hierarchy point set simplification
maximum surface variation (*).
--tc-ps-wlop-retain-percent arg (=1 ) Percentage of points to retain,
[0..100] (*).
--tc-ps-wlop-radius arg (=10000 ) PS WLOP simplification: radius.
--tc-ps-wlop-iter-number arg (=35) PS WLOP simplification: number of
iterations.
--tc-ps-grid-cell-size arg (=10000 ) PS Grid simplification: Cell size (*).
--tc-ps-random-percent arg (=90 ) PS Random simplification: percentage to
remove.
--debug-dir arg Debug directory where simplified meshes
will be stored in OFF format for easing
visualization.
-c [ --config ] arg Configuration file with a set of the
options above specified in the form
<option>=<value>. Note that the options
in the config file have preference over
the ones specified on the command line.
Since this list is quite large and complex, we divided the explanation of the parameters into the following sections:
- General Parameters: global parameters not related to the simplification method used.
- Since we need to set various parameters for the different levels of the pyramid, we explain in this page the way we designed to set parameters for different zoom levels.
- Then, we comment on the different TIN creation methods implemented, and their related parameters:
- Greedy Insertion: Parameters related to the greedy insertion simplification method.
- Edge Collapse Simplification: Parameters related to the edge collapse simplification method.
- Point Set Simplification: Parameters related to the point set simplification methods. In this case, more than a single algorithm for point set simplification can be selected.