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.
The binaries have been built for Ubuntu 20.04, but may work on other/similar debian systems. Some (less common) libraries are bundled and provided in the .tar.gz file.
To extract the files, run
tar -xzvf helios_plusplus_lin.tar.gz
Then, add the run folder to the LD_LIBRARY_PATH environment variable. You need to do this every time you open a new shell or restart your computer!
cd helios_plusplus_lin/run
export LD_LIBRARY_PATH=$(pwd):$LD_LIBRARY_PATH
cd ..
You should then be able to run helios++:
run/helios <path to survey file>
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 Discrete time test [PASSED]
TEST Voxel parsing test [PASSED]
TEST Ray intersection test [PASSED]
TEST Grove test [PASSED]
TEST Serialization test [PASSED]
TEST Asset loading test [PASSED]
TEST Survey copy test [PASSED]
TEST Plane fitter test [PASSED]
TEST LadLut test [PASSED]
TEST Platform physics test [PASSED]
TEST Functional platform test [PASSED]
TEST Scene part split test [PASSED]
TEST Rigid motion test [PASSED]
TEST Fluxionum test [PASSED]
TEST Energy models test [PASSED]
TEST HPC 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.
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.
We have created a number of example jupyter notebooks that show you how to use HELIOS++ and especially its XML syntax and Python bindings:
 |
Two highly detailed tree models (loaded from .OBJ files) are scanned from two positions with a terrestrial laser scanner (TLS). |
 |
A wheat field (loaded from .OBJ files) is scanned from a tractor with mobile laser scanning (MLS). |
 |
A scene with different simple geometries (toyblocks, loaded from .OBJ files) is scanned by means of mobile laser scanning. |
 |
UAV-based laser scanning (ULS) is conducted over a toyblock scene. This example shows how to define the survey and the scene in a single XML file. |
 |
With airborne laser scanning (ALS), the terrain of Heidelberg (Germany) is scanned. For the virtual 3D scene, a digital terrain model (DTM) is loaded from a GeoTIFF. |
 |
Again, Heidelberg is scanned using a DTM of Heidelberg. This time, the airplaine holds a constant height above the ground by creating many support points with different heights. The many small segments are grouped to three strips using the stripId parameter. |
 |
A point cloud (XYZ ASCII file) is loaded to a voxel model with HELIOS++ and then scanned by TLS. Voxel normals are computed from the point cloud, which affect the beam incidence angles and hence the computed intensities. |
 |
Different modes for 3D (vegetation) modelling with detailedVoxels are demonstrated for a single tree. Both ULS and ALS simulations are conducted. |
 |
TLS is conducted using a Livox Mid-70 with a risley prism, resulting in a non-repeating, retina-like scanning pattern. |
 |
A toyblocks scene is scanned by ULS scanning using a Livox Mid-70 sensor. |
 |
A toyblocks scene is scanned by ALS using the Livox Mid-100, a device composed of three Mid-40 units. |
 |
The configuration of multi-channel scanners is demonstrated with the Velodyne Puck, which has 16 channels. A "box scene" is used for visualisation and debugging purposes. |
 |
ALS is simulated using a trajectory as input, from which platform position and platform attitude at a given time is read. HELIOS++ interpolated between the time values. The trajectory interpolation is demonstrated with simple examples using the box scene. |
 |
A Tutorial to get started with pyhelios. |
 |
This tutorial demonstrated pyhelios functions for obtaining scanner device characteristics, accessing and modifying scanner and platform settings, adding legs to a survey, and more |
 |
This example shows how to load and run a simulation with pyhelios and displays the resulting output. |
 |
This tutorial shows how to use a callback function to create a live plot of the simulatied trajectory. |
 |
An extensive example of using pyhelios to simulate ULS over a synthetic forest, which was modelled from TLS data. Includes various processing steps, like classification of TLS point cloud, creation of the 3D scene (DTM as GeoTIFF, voxelized forest as XYZ point cloud), configuration of the survey and comparison with a real ULS point cloud of the same scene. |