First steps
HELIOS++ is delivered to you as a zipped folder, including all the required libraries. Unzip the folder to a path where you have write permission. In the run subfolder, you will find helios.exe, which is the main executable.
You will also find a data subfolder with a number of example surveys, scanners, platforms and scenes. They provide a good starting point for experimentation and are required to pass some of the test cases.
To compile HELIOS++ from source, please follow the instructions given in the BUILDME file of the repository. Setting up the complete build chain from scratch should be possible in a few hours (including download times).
To avoid unexpected behavior, we suggest to run the test cases after installation. To do this, open a Command Prompt or PowerShell Window (or another terminal application), navigate to the path where you have extracted helios++, and run
run\helios --test
The output should show that all tests are [PASSED]:
> run\helios.exe --test
TEST Randomness generation test [PASSED]
TEST Noise sources test [PASSED]
TEST Voxel parsing test [PASSED]
TEST Ray intersection test [PASSED]
TEST Serialization test [PASSED]
TEST Survey copy test [PASSED]
TEST Plane fitter test [PASSED]
TEST LadLut test [PASSED]
TEST Platform physics test [PASSED]
TEST Scene part split test [PASSED]
Be sure to also check if the return code is zero (environment variable ERRORLEVEL), e.g. on Windows:
> echo %ERRORLEVEL%
0
If you have extracted the data folder to a different path, make sure that HELIOS++ can find the folder, e.g. by running it from the parent directory of the data folder (and running helios with an absolute path).
Starting HELIOS++ is done in a command line by telling it where to find the survey file.
Open a command prompt and navigate to the folder where you extracted helios to.
Type
run\helios [survey-file]
and hit the Enter button to start the simulation.
The software has a modular architecture, where the simulation assets (i.e. platform, scene and scanner) are read from XML files and linked scenepart files. [survey-file] is the absolute or relative path to a survey XML file. In this XML file, paths pointing to the scene XML, the platform XML and the scanner XML are provided. Sample scenes, platforms and scanners are provided in the data directory. For example, run
run\helios data\surveys\demo\tls_arbaro_demo.xml
which will run a simulation of a TLS scan of two trees from two scan positions. The output will be created in the output/Survey Playback/Arbaro Demo - folder under the timestamp of the simulation start. This point cloud can be visualized e.g. using Cloud Compare, and may look like this:
To print the HELIOS++ help message, type:
run\helios -h
This gives you an overview of additional, optional arguments. Currently, the following arguments are supported:
-h or --help : Show this help
--test : Run tests to check helios++ behaves as expected
--unzip <input_path> <output_path>
Decompress the file at input path and write it decompressed at output path.
File at input path must be the compressed output of helios++
--assets <dir_path> : Specify the path to assets directory
By default: ./assets/
--output <dir_path> : Specify the path to output directory
By default: ./output/
--writeWaveform : Use this flag to enable full waveform writing
By default waveform is NOT written to output file
--calcEchowidth : Use this flag to enable full waveform fitting
By default the full waveform is NOT fitted
--fullwaveNoise : Use this flag to add noise when computing full waveform
By default: full waveform noise is disabled
--fixedIncidenceAngle : Use this flag to use fixed incidence angle
Fixed incidence angle of exactly 0.0 will be considered for all intersections
--seed <seed>: Specify the seed for randomness generation
It can be an intenger, a decimal or a timestamp with format
YYYY-mm-DD HH::MM::SS
By default: a random seed is generated
--lasOutput : Use this flag to generate the output point cloud in LAS format (v 1.4)
--las10: Use this flag to write in LAS format (v 1.0)
--zipOutput : Use this flag to generate compressed output
--lasScale : Specify the decimal scale factor for LAS output
--parallelization <integer> : Specify the parallelization strategy
0 for a static/dynamic chunk based parallelization and 1 for a
warehouse based one.
By default: Static/dynamic chunk based strategy is used
-j or --njobs or --nthreads <integer> : Specify the number of
jobs to be used to compute the simulation
By default: all available threads are used
--chunkSize <integer> : Specify the chunk size to be used for
parallel computing. If a negative number is given, then its
absolute value is used as starting size of the dynamic chunk-size strategy.
Positive numbers specify the size for a static chunk-size strategy
By default: -32
--warehouseFactor <integer> : Specify the warehouse factor.
The number of tasks in the warehouse would be k times the
number of workers. The greater the factor, the less the
probability of idle cores but the greater the memory consumption.
By default: 4
--rebuildScene : Force scene rebuild even when a previously
built scene is available
By default: previous scene is used if found
--kdt <integer> : Specify the type of KDTree to be built for for the scene
Default 1 is for the simple KDTree based on median balancing, 2 for
the SAH based KDTree, 3 for the SAH with best axis
based KDTree and 4 for a fast SAH approximation
--kdtJobs <integer> : Specify the number of threads to be used for building the KDTree.
If 1, then the KDTree will be built in a sequential fashion
If >1, then the KDTree will be built in a parallel fashion
If 0, then the KDTree will be built using as many threads as available
This is not recommended because using more threads than required
by scene complexity might easily lead to poor performance
Default is 1
--sahNodes <integer> : Specify how many nodes must be used by the
Surface Area Heuristic when building a SAH based KDTree
By default it is 21. More nodes lead to a best search process
to find split position, at the expenses of a
greater computational cost. When using a fast SAH
approximation it is recommended to set this to 32.
--disablePlatformNoise : Disable platform noise, no matter
what is specified on XML files
By default: XML specifications are considered
--disableLegNoise : Disable leg noise, no matter what is
specified on XML files
By default: XML specifications are considered
--logFile : Logging will be outputted to a file, not only
to standard output.
By default: logging will be written to standard output
--logFileOnly : Logging will be outputted ONLY to a file
By default: logging will be outputted to standard output
--silent : Disable logging output
By default: only information and errors are reported
-q or --quiet : Specify the verbosity level to errors only
By default: only information and errors are reported
-vt : Specify the verbosity level to time and errors only
By default: only information and errors are reported
-v : Specify the verbosity level to errors, information and warnings
By default: only information and errors are reported
-v2 or -vv : Specify the verbosity level to report all messages
By default: only information and errors are reported
The following figure provides a general overview of the main HELIOS++ XML files, their content, and their connection:
In the survey XML, scan positions or way points are configured and full waveform settings, platform settings, and scanner settings can be controlled.
The scene XML links to the different geometry parts, which can be of different types such as polygon meshes, georeferenced rasters (GeoTiff), point clouds or voxels. Different parameters and filters can be passed to define how to load and pre-process the linked files, including transformations such as translation, rotation and scaling of individual scene parts. More details are listed in on the Scene subpage.
The platform XML contains the definition of different platforms, such as a stationary tripod for terrestrial laser scanning simulations, vehicles for mobile laser scanning simulations and aircrafts for airborne laser scanning simulations. A number of platforms are predefined (tripod, quadcopter, Cirrus SR-22, ...) and can be extended. See the platforms.xml file in the data folder.
The scanner XML contains scanner specifications like beam divergence, accuracy, deflector type, pulse frequency or pulse length. Similar to the platforms, a number of scanners are predefined in scanners_als.xml and scanners_tls.xml in the data-folder.
HELIOS++ comes with a folder structure which helps in storing and finding these compartments. It is therefore recommended to work in the provided folder structure:
The paths pointing from the survey XML file to the other XML files can be set relative or absolute. Note that relative paths always relate to the current working directory, i.e. the directory where helios was called from. They hence usually start with data/, when following the suggested folder structure.
The software loads the geometries and performs a simulation according to the specified input configurations. The output is written to output/Survey Playback. Separate folders are created for each survey and for each time the survey is executed. Points are written to XYZ ASCII files (default) or LAS files (using the --lasOutput argument), with one file per leg (i.e. per scan position, flight line or path), respectively. Optionally, the full waveform can be exported, by adding --writeWaveform as command line argument.
Accordingly, a more elaborate example to start a simulation would be:
run\helios data\surveys\demo\tls_arbaro_demo.xml --lasOutput --writeWaveform --seed 42 -j 1
which creates a reproducible simulation (because of fixed seed, cf. Controlling Randomness) , writes LAS output files and additionally writes the fullwave signal into ASCII files. The result folder will look like this:
If you want to export the trajectory, you can provide the trajectoryTimeInterval_s="0.01" attribute in the <scannerSettings [...]> tag in the survey XML. The position and attitude of the platform will then be written to an ASCII output file for each leg every 0.01 seconds (depending on the value of the attribute). For static platforms (TLS), this attribute is ignored. See the separate page Output for details on the file formats.
To become familiar with the inputs and outputs of HELIOS++, check out the variety of example surveys, execute them and have a look at the output. The following table provides an overview of the available demo surveys and scenes:
| survey.xml | Scene | Input Geometry | Platform | Scanner | Comments |
|---|---|---|---|---|---|
| demo/als_hd_demo_tiff.xml | Heidelberg area | GeoTIFF (25 m resolution) | SR-22 Airplane | LEICA ALS50-II | Just a terrain model, demonstration how to define and use default scanner settings |
| demo/tls_arbaro_demo.xml | Tree models on terrain (plane) | OBJ-models, geometric primitives | Tripod | RIEGL VZ-400 | demonstration how to define and use default scanner settings, scene: demonstration of the up parameter of for the objloader |
| demo/mls_wheat_demo.xml | Wheat models on terrain (plane) | OBJ-models, geometric primitives | Tractor | RIEGL VZ-400 | |
| toyblocks/als_toyblocks.xml | Toyblocks on terrain (plane) | Geometric primitives | SR-22 Airplane | RIEGL VQ-880-G | |
| toyblocks/uls_toyblocks_stop_and_turn.xml | Toyblocks on terrain (plane) | Geometric primitives | Quadcopter | RIEGL VUX 1-UAV |
stopAndTurn-mode |
| toyblocks/uls_toyblocks_survey_scene_combo.xml | Toyblocks on terrain (plane) | Geometric primitives | Quadcopter | RIEGL VUX 1-UAV | Combined survey and scene, efilepath parameter |
| toyblocks/mls_toyblocks.xml | Toyblocks on terrain (plane) | Geometric primitives | Car | RIEGL VUX 1-UAV | |
| toyblocks/tls_toyblocks.xml | Toyblocks on terrain (plane) | Geometric primitives | Tripod | RIEGL VZ-400 | |
| voxels/tls_sphere_xyzloader.xml | Sphere and terrain (plane) | ASCII Point cloud (x y z) | Tripod | RIEGL VZ-400 | |
| voxels/tls_sphere_xyzloader_normals.xml | Sphere and terrain (plane) | ASCII Point cloud (x y z nx ny nz) | Tripod | RIEGL VZ-400 | |
| voxels/als_detailedVoxels_mode_comparison.xml | Tree models on terrain (plane) | detailedVoxels | SR-22 Airplane | RIEGL LMS-Q780 | FWFSettings demonstrated |
| voxels/uls_detailedVoxels_mode_comparison.xml | Tree models on terrain (plane) | detailedVoxels | Quadcopter | RIEGL VUX 1-UAV | FWFSettings demonstrated |