-
Notifications
You must be signed in to change notification settings - Fork 44
Survey
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.
Alternatively, the platform attribute of the <survey> tag can be setted to "interpolated". In this case, the platform behavior will be defined by a function obtained through interpolation of given trajectory data. The specification of trajectory data is detailed in the Interpolated trajectories section.
Scanner settings and platform 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> or <platformSettings> in each <leg>, the globally defined settings can be referenced by an ID using the template parameter.
Additionally, all settings can be given explicitly in the <scannerSettings> and platformSettings of the <leg>. If the same setting is defined in a template and in a leg which uses the template, the value that is given in the leg is taken.
So the priority is always: Leg -> Template -> Default
<?xml version="1.0"?>
<document>
<platformSettings id="platform1" z="35.000" onGround="false" movePerSec_m="5" stopAndTurn="true"/>
<scannerSettings id="scanner1" active="true" pulseFreq_hz="100000" scanAngle_deg="90" scanFreq_hz="50" trajectoryTimeInterval_s="0.05"/>
<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
OPTIONAL: detectorSettings and FWFSettings, examples below
<detectorSettings accuracy_m="0.001" rangeMin_m="1.5" rangeMax_m="200"/>
<FWFSettings winSize_ns="1.5" beamSampleQuality="3"/> -->
<!-- leg000 -->
<leg>
<platformSettings template="platform1" x="-80.0" y="-50.0"/>
<scannerSettings template="scanner1"/>
</leg>
<!-- leg001 -->
<leg>
<platformSettings template="platform1" x="80.0" y="-50.0"/>
<scannerSettings template="scanner1"/>
</leg>
<!-- leg002 -->
<leg>
<platformSettings template="platform1" x="-80.0" y="50.0"/>
<scannerSettings template="scanner1" pulseFreq_hz="300000"/>
</leg>
<!-- leg003 -->
<leg>
<platformSettings template="platform1" x="80.0" y="50.0"/>
<scannerSettings template="scanner1" active="false"/>
</leg>
</survey>
</document>In this example, the platformSettings template "platform1" is used for all flight lines (legs), so only the x and y position have to be specified for each leg. Furthermore, all legs use the template "scanner1" for the scannerSettings. For leg002, the pulse frequency is increased to 300 kHz. Hence, the pulse prequency defined in the template is overridden, all other settings (scan frequency, scan angle, etc.) remain as defined in the template.
To replicate existing surveys, a trajectory file can be supplied as input to a leg instead of setting waypoints manually. This has the added advantage that the platform's attitude can be considered, which may, e.g., come from flight planning tools. To enable the interpolation, set the platform in the <survey > tag to "interpolated".
When the platform is defined from trajectory data, a basePlatform can be defined in the <survey> tag from which the scanner mount and other important platform attributes are retrieved. It is also possible to configure the scanner mount directly on the survey XML. For this, define a <scannerMount> element as a direct child of the <survey> element. The child <scannerMount> syntax is the same as usual. In the example below, the scanner is mounted with an offset of 0.2 m in the vertical coordinate. Besides, its attitude is defined by a 180-degree rotation on the x-axis and another 175-degree rotation on the z-axis.
<survey ...>
<scannerMount x="0" y="0" z="0.2">
<rot axis="x" angle_deg="180" />
<rot axis="z" angle_deg="175" />
</scannerMount>
</survey>The <platformSettings> tag inside a <leg> tag in the survey file can be used to configure the interpolation. The first attribute is the trajectory, which is the only mandatory one for interpolated platforms. It can be used to define the path to the trajectory file. A trajectory file can be a simple CSV with neither comments nor header. By default it is expected to have columns with (time, roll, pitch, yaw, x, y, z) format. It is also possible to specify an arbitrary data format using the comment #HEADER: "t", "roll", "pitch", "yaw", "x", "y", "z" in the trajectory file. The aforementioned header definition matches the default column order, but it can be arbitrarily changed to specify any column order as long as the names are correctly spelled. Anything that is specified in the survey XML file will overwrite any specification in the trajectory file: Here, the column order can be specified simply by adding index attributes to the <platformSettings> tag. The tIndex attribute can be used to specify the index of the time column, the xIndex, yIndex, and zIndex attributes can be used to specify the index of the columns representing the coordinates of the platform, and the rollIndex, pitchIndex and yawIndex attributes can be used to specify the index of the columns representing the angles of the platform. If angles should not be considered, the interpolationDomain should be set to "position" (default is "position_and_attitude"). By default, it is assumed that angles are given in degrees. Nonetheless, it is possible to give them already in radians. In this last case, the attribute toRadians must be explicitly set to "false" to prevent an unexpected conversion. Furthermore, the attribute trajectory_separator can be used to specify the column separator for input trajectory files.
It is also possible to define tStart and tEnd attributes for the <platformSettings> tag. The first one specifies the time of the starting point for the leg, while the second one specifies the time of the ending point. If tStart is not specified, the leg will start at the first point in time. If tEnd is not specified, the leg will end at the last point in time. When the attribute teleportToStart is configured as true, the platform is forced to teleport to the position of the starting point (either the first point in time of tStart).
The same trajectory file can be repeated among different legs. However, it is only possible to define its column order once. It is very important to prevent multiple column definitions for the same trajectory file in the same XML survey file. When using the same trajectory file for different legs and explicitly setting the tStart to skip parts of the trajectory or to repeat parts of the trajectory, make sure to also set teleportToStart to true. Furthermore, if you have multiple legs using different trajectory files (the later ones having higher time values), keep in mind that using teleportToStart without setting a tStart will use the start time of the first trajectory, because internally, all trajectories are merged to a single trajectory. So either specify neither tStart nor teleportToStart or specify both.
It is also possible to synchronize the starting GPS time of the simulation with the minimum time value from the input trajectory data. For this, set the attribute syncGPSTime to true.
Since trajectory files are translated to a matrix where each row represents the behavior of the platform at a certain time, it can be interesting to reduce the size of this matrix while minimizing the information loss. This can help to digest big trajectory files, besides facilitating interpolation. That is what slopeFilterThreshold attribute can be useful for. When it is configured to a value greater than zero, forward finite differences are used to approximate the derivative for each column, which is then understood as the slope of a linear interpolation by pieces. Whenever the accumulated deviation with respect to the first slope does not exceed the slopeFilterThreshold, it is assumed that all intermediary data points can be approximate well enough by a linear interpolation. Therefore, all points but the first and the last one are discarded.
The following XML snippet defines a platfrom from trajectory data. The first leg follows the entire trajectory. The second leg teleports to the position at t=4.78 and moves until the position at t=6.94 is reached. Note that it requires the teleportToStart flag to be true, because it needs to start at a previously passed position. The third leg goes from the position at t=8.02 until the end. In this case, it is not necessary to enable the teleportToStart flag because the start time comes after the previous end time. The fourth leg starts again from the very beginning. Since all legs are defined from the same trajectory data, the column specification of the first leg is assumed for all legs.
<?xml version="1.0" encoding="UTF-8"?>
<document>
<!-- Default scanner settings: -->
<scannerSettings id="scaset" active="true" pulseFreq_hz="70000" scanAngle_deg="60" scanFreq_hz="50" />
<survey name="interpolated_trajectory_als" scene="data/scenes/demo/interpolated_trajectory.xml#interpolated_trajectory_demo" platform="interpolated" basePlatform="data/platforms.xml#sr22" scanner="data/scanners_als.xml#leica_als50-ii">
<FWFSettings beamSampleQuality="3" binSize_ns="0.25" winSize_ns="1"/>
<!-- Leg which interpolates the full trajectory -->
<leg>
<platformSettings
trajectory="data/trajectories/cycloid.trj"
tIndex="0" xIndex="4" yIndex="5" zIndex="6" rollIndex="1" pitchIndex="2" yawIndex="3"
slopeFilterThreshold="0.0" toRadians="true" syncGPSTime="false"
/>
<scannerSettings template="scaset" trajectoryTimeInterval_s="0.054"/>
</leg>
<!-- Leg which interpolates the trajectory for all t in [4.78, 6.94] -->
<leg>
<platformSettings trajectory="data/trajectories/cycloid.trj" tStart="4.78" tEnd="6.94" teleportToStart="true"/>
<scannerSettings template="scaset" trajectoryTimeInterval_s="0.054"/>
</leg>
<!-- Leg which interpolates the trajectory for all t in [8.02, tb] where tb is the final time -->
<leg>
<platformSettings trajectory="data/trajectories/cycloid.trj" tStart="8.02"/>
<scannerSettings template="scaset" trajectoryTimeInterval_s="0.054"/>
</leg>
<!-- Leg which interpolates the full trajectory again from the start (3.7 is the time of the first point) -->
<leg>
<platformSettings trajectory="data/trajectories/cycloid.trj" tStart="3.7" teleportToStart="true"/>
<scannerSettings template="scaset" trajectoryTimeInterval_s="0.054"/>
</leg>
</survey>
</document>In the detectorSettings-tag, the accuracy, minimum range and maximum range of the detector can be specified. The detectorSettings are defined within the survey tag.
<detectorSettings accuracy_m="0.001" rangeMin_m="5" rangeMax_m="600"/>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. The FWFSettings are defined within the survey tag.
For each scan position or waypoint, a <leg> is defined. Optionally, a stripId can be assigned to a leg. Legs with the same stripId will be grouped and their simulated point cloud is written to a single output file, named by the stripId. Legs with no stripId are considered as separate strips and their outputs are numbered consecutively (leg000, leg001, etc.).
Within the <leg> tag, the 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 waypoints 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 specified (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.
IMPORTANT NOTE: There are several bugs with the multicopter platform, like legs not ending when using slowdownEnabled (#22, #37) or the user-defined speed (movePerSec_m) not being used. We advise to use the linearpath platform instead. In the platforms.xml, this could look like that:
<platform id="copter_linearpath" name="Quadrocopter UAV" type="linearpath">
<scannerMount x="0" y="0" z="0.2">
<rot axis="x" angle_deg="180" />
<rot axis="z" angle_deg="175" />
</scannerMount>
</platform>This platform would be compatible with e.g., the riegl_vux-1uav. Using the rotations in the scannerMount, the copter pitch during forward movement is simulated.
| Attribute | Default value | Comment |
|---|---|---|
id |
- | ID by which the settings can be loaded for the individual legs, REQUIRED |
active |
true | Boolean |
pulseFreq_hz |
First value of the list of pulseFreq_hz as defined in the scanner XML file (see scanner XML file). |
|
scanFreq_hz |
0 | |
verticalResolution_deg |
0 | Alternative to scanFreq_hz
|
beamDivergence_rad |
0.0003 | |
scanAngle_deg |
0 | (Vertical) half scan angle, recommended for ALS surveys; has no effect for scanners with optics = "conic"
|
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 |
horizontalResolution_deg |
0 | Recommended for TLS surveys, alternative to headRotatePerSec_deg
|
headRotateStart_deg |
0 | Recommended for TLS surveys |
headRotateStop_deg |
0 | Recommended for TLS surveys |
trajectoryTimeInterval_s |
0.0 | 0 means no trajectory output |
| 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. Alternatively, "interpolated" can be used to specify that the platform behavior will be defined by given trajectory data, REQUIRED |
basePlatform |
- | Interpolation mode only, Platform defining, e.g., the scanner mount, Path to XML, followed by a hash (#) and the entry-ID. |
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 |
| Attribute | Default value | Comment |
|---|---|---|
accuracy_m |
0.0 | |
rangeMin_m |
0.0 | |
rangeMax_m |
inf |
| 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). |
pulseLength_ns |
4 | |
winSize_ns |
pulseLength_ns/4 |
pulseLength as defined in the FWFSettings of the survey (see above) or of the scanner (scanner XML files) |
| Attribute | Default value | Comment |
|---|---|---|
stripId |
- | Legs with the same stripId will be grouped and written to a single output file, named by the stripId. Legs with no stripId are considered as separate strips and numbered consecutively (leg000, leg001, etc.). |
| 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 |
trajectory |
None | Interpolation mode only String like path |
trajectory_separator |
"," |
Interpolation mode only String like separator. " " and "\t" are not supported. |
interpolationDomain |
"position_and_attitude" | Interpolation mode only Either "position" or "position_and_attitude". If "position" is specified, angles (roll, pitch, yaw) in the trajectory file are not considered. |
tIndex |
0 | Interpolation mode only Integer column index |
rollIndex |
1 | Interpolation mode only Integer column index |
pitchIndex |
2 | Interpolation mode only Integer column index |
yawIndex |
3 | Interpolation mode only Integer column index |
xIndex |
4 | Interpolation mode only Integer column index |
yIndex |
5 | Interpolation mode only Integer column index |
zIndex |
6 | Interpolation mode only Integer column index |
tStart |
0 | Interpolation mode only Decimal time value |
tEnd |
None | Interpolation mode only Decimal time value |
slopeFilterThreshold |
0.0 | Interpolation mode only Decimal threshold |
teleportToStart |
false | Interpolation mode only Boolean flag |
toRadians |
true | Interpolation mode only Boolean flag |
syncGPSTime |
false | Interpolation mode only Boolean flag |
| Attribute | Default value | Comment |
|---|---|---|
template |
- | ID of the scanner settings which were globally defined in the beginning of the <document>. If an ID is specified, the settings of the template are used, unless they are overwritten by specifying further settings (see below) within the legs scannerSettings. |
active |
true | Boolean |
pulseFreq_hz |
First value of the list of pulseFreq_hz as defined in the scanner XML file (see scanner XML file). |
|
scanFreq_hz |
0 | |
beamDivergence_rad |
0.0003 | |
scanAngle_deg |
0 | (Vertical) half scan angle, recommended for ALS surveys; has no effect for scanners with optics = "conic"
|
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 |