Survey

Survey definition

The survey XML file contains references to the components needed to build a simulation: The scene, the platform and the scanner. It also contains waypoint information needed to define the scan positions or trajectory. For an overview of all possible tags and parameters in the survey XML, go to XML Tag and Parameter Summary at the bottom of the page.

Linking to the different components is done by specifying the absolute or relative path of the respective XML file in the <survey> tag, followed by a hash (#) and the ID of the entry:

<survey name="toyblocks_als" 
        platform="data/platforms.xml#sr22"
        scanner="data/scanners_als.xml#riegl_vq-880g"
        scene="data/scenes/toyblocks/toyblocks_scene.xml#toyblocks_scene">

Optionally, a seed can be specified in the <survey>-tag to control random numbers. This is explained in detail on the page Error sources and randomness control.

Scanner settings

Scanner settings are defined at the document level before the <survey>-tag and/or within the <leg>-tags. Setting one or more templates with defined scanner settings at the beginning of the file enables the reuse of these settings for the different legs. Within the <scannerSettings> in each <leg>, the globally defined scanner settings can be referenced by an ID using the template parameter. Alternatively, all scanner settings can be given explicitly in the <scannerSettings> of the <leg>. Templates can also be combined with single values. In this case, the explicitly defined values will override the ones specified in the template.

<?xml version="1.0"?>
<document>
        <scannerSettings id="profile1" active="true" pulseFreq_hz="100000" scanAngle_deg="90" scanFreq_hz="50"/>
	<survey name="toyblocks_uls_stopturn" platform="data/platforms.xml#quadcopter" scanner="data/scanners_als.xml#riegl_vux-1uav" scene="data/scenes/toyblocks/toyblocks_scene.xml#toyblocks_scene">
	<!-- platform: quadcopter, deflector: rotating, stop and turn-mode -->
		<leg>
			<platformSettings  x="-80.0" y="-50.0" z="35.000" onGround="false" movePerSec_m="5" stopAndTurn="true"/>
			<scannerSettings template="profile1" trajectoryTimeInterval_s="0.05"/>
		</leg>
		<leg>
			<platformSettings  x="80.0" y="-50.0" z="35.000" onGround="false" movePerSec_m="5" stopAndTurn="true"/>
			<scannerSettings template="profile1" trajectoryTimeInterval_s="0.05"/>
		</leg>
		<leg>
			<platformSettings  x="-80.0" y="50.0" z="35.000" onGround="false" movePerSec_m="5" stopAndTurn="true"/>
			<scannerSettings template="profile1" pulseFreq_hz="300000" trajectoryTimeInterval_s="0.05"/>
		</leg>
		<leg>
			<platformSettings  x="80.0" y="50.0" z="35.000" onGround="false" movePerSec_m="5"/>
			<scannerSettings  active="false"/>
		</leg>
	</survey>
</document>

In this example, "profile1" is used for all flight lines (legs), but for the last flight line, the pulse frequency is increased to 300 kHz (all other settings as defined in the <scannerSettings> template "profile1").

Fullwave settings

The FWFSettings-tag is used to configure the discretization of the full waveform in space and time and the window size for the peak detection. The parameters are explained in detail on the pages Scanners and Fullwave processing.

Leg definition

For each scan position or waypoint, a <leg> is defined. Within this tag, platform position is provided in the tag <platformSettings>. For dynamic platforms, at least two legs have to be defined corresponding to the start and stop way point and the speed between two waypoints is set with the parameter movePerSec_m. The direction of movement is determined by the position of the next waypoint. The onGround parameter is useful for terrestrial surveys. It is "false" by default, but when set to "true", the platform is automatically placed onto the ground regardless of the specified z-coordinate. The ground is determined as the lowest z-coordinate in the data at the xy-position of the leg. Specifically for the copter-platform, a turn mode can be specific (smoothTurn or stopAndTurn), which is explained and visualized in Platforms.

Scanner settings for each leg are defined in the <scannerSettings>-tag. This includes the scanner activity, pulse frequency, scan angle, scan frequency, head rotation and trajectory output. They can also be loaded from a template, which is defined in the beginning of the <document> before the <survey>-tag. The settings are explained on the page Scanner settings.

The full survey file may look like this (data/surveys/demo/als_hd_demo_tiff.xml):

XML Tag and Parameter Summary

<scannerSettings [...]> tag

Attribute	Default value	Comment
id	-	ID by which the settings can be loaded for the individual legs, REQUIRED
active	true	Boolean
pulseFreq_hz	0
scanFreq_hz	0
scanAngle_deg	0	(Vertical) half scan angle, recommended for ALS surveys
headRotatePerSec_deg	0	Recommended for TLS surveys
headRotateStart_deg	0	Recommended for TLS surveys
headRotateStop_deg	0	Recommended for TLS surveys

<survey [...]> tag

Attribute	Default value	Comment
name	-	Path to XML, followed by a hash (#) and the entry-ID, REQUIRED
platform	-	Path to XML, followed by a hash (#) and the entry-ID, REQUIRED
scanner	-	Path to XML, followed by a hash (#) and the entry-ID, REQUIRED
scene	-	Path to XML, followed by a hash (#) and the entry-ID, REQUIRED
seed	randomly computed	see Error sources and randomness control

<FWFSettings [...]> tag within the <survey> tag

Attribute	Default value	Comment
beamSampleQuality	3	discretization in space, see Fullwave
binSize_ns	0.25	discretization in time
maxFullwaveRange_ns	0	maximum time to record for a single pulse. 0 means no limit (wait for last pulse).
winSize_ns	pulseLength_ns/4	pulseLength as defined for the scanner (in the scanner XML)

<leg> tag(s) within the <survey> tag

<platformSettings [...]> within <leg> tag

Attribute	Default value	Comment
x	0
y	0
z	0
onGround	false	Boolean
movePerSec_m	70.0	Ignored for static platforms
stopAndTurn	true	Boolean, specific to multicopter
smoothTurn	false	Boolean, specific to multicopter
slowdownEnabled	true	Boolean, specific to multicopter
yawAtDeparture_deg	Align to 2nd waypoint	Specific to multicopter

scannerSettings [...]> within <leg> tag

Attribute	Default value	Comment
template	-	ID of the scanner settings which were globally defined in the beginning of the <document>
active	true	Boolean
pulseFreq_hz	0
scanFreq_hz	0
scanAngle_deg	0	(Vertical) half scan angle, recommended for ALS surveys
verticalAngleMin_deg	0	Recommended for TLS surveys, see also Scanner settings
verticalAngleMax_deg	0	Recommended for TLS surveys
headRotatePerSec_deg	0	Recommended for TLS surveys
headRotateStart_deg	0	Recommended for TLS surveys
headRotateStop_deg	0	Recommended for TLS surveys
trajectoryTimeInterval_s	0.0	0 means no trajectory output