Release note for version 240510: The redesign of the error handling may require customization of scripts using LAStools.
Background:
The reasons for error messages can be minor (e.g. a tool argument is not in the correct range). However, especially when working in batch mode, it is crucial that errors in the process are reliably detected so that no data is used or published that contains errors or is incomplete. In the past, the only way to reliably determine whether an error situation existed was to analyze the output of the program console for the “ERROR” token. In addition, warnings were issued that must be viewed as errors and lead to the program being terminated immediately. This resulted in console outputs as follows:
llx/lly unspecified. set to lower left bounding box 535180/4.12958e+006.
ERROR (TINclean): failed malloc for 40610234 TINtriangles.
ERROR: cannot alloc enough TIN triangles to triangulate 20305117 points.
ERROR: cannot alloc enough TIN triangles to triangulate 26879983 points.Already the first error led the program to stop because there was no chance of obtaining a valid result. Some months ago, LAStools was extended to define message classes, which made it easier for library functions to detect an error by message type (and not just text output). A common method in console applications is to use an exit code. This exit code was not always set correctly in LAStools. Therefore, it often remained at “0” for “success”, even if there were errors or warnings.
Redesign
The error handling was completely redesigned, which also includes some significant changes to the program workflow. The new error handling principles are as follows:
- All messages are classified into the categories „very verbose, verbose, information, warning, serious warning, error, fatal error“.
- Warnings never stop the program, the exit code at the end of the program is set to „2“.
- Serious warnings stop the program, unless the „-force“ argument is used.
- In the event of an error, the program is immediately terminated with the exit code “3”.
- The exit code „0“ means that no errors or warnings occurred during the execution of the program.
This fundamental change within the workflow will potentially change the behavior of existing batch programs and require action from users. However, it should be worthwhile for you to adapt your scripts to ensure continuous improvement in workflow results.
Exit codes
Every LAStools program now ends with a defined exit code. The exit code is defined by the highest message type that occurred during program run. Certain message types force the program to stop immediatly.
| Message type | Exit code | Immediate STOP |
|---|---|---|
| WARNING | 1 | no |
| SERIOUS_WARNING | 2 | yes (default), no (-force argument) |
| ERROR | 3 | yes |
| FATAL_ERROR | 4 | yes |
ERRORs that did not stop the program in the past become a WARNING in the future, (e.g. in coordinate system interpretation). There were also a lot of ERRORs when something did not match with CRS, but the program continued to run. These will also become WARNINGs. The exit code of a program can be easily retrieved. The variable %errorlevel% can be used within the Windows console.
> las2las64 -abc
ERROR: cannot understand argument '-abc'. use -h or see las2dem_README.md to get help.
> echo %errorlevel%
3Within a windows batch file, the variable can be used to control the program flow. Sample file „test.cmd“:
@echo off
las2dem64 -i test.laz
echo program exits with errorlevel=%errorlevel%
if "%errorlevel%"=="0" (
echo "succeed"
rem ... do this
) else (
echo "failed"
rem ... do that
)Within linux bash
echo $?can be used to get the program exit code.
Common extensions
Part of the redesign was also a common argument parser for all LAStools. This means that all common arguments such as „-v“, „-h“,… will behave identically in future. The „-fail“ argument is now part of all licensed tools. The tool exits with an „unlicensed“ error message instead of running in demo mode.
| Argument | Description | Note |
|---|---|---|
| -h, -help | Prints information about the tool | |
| -hh | Prints information about the tool and the used modules | |
| -v, -verbose | Prints verbose log output | |
| -vv | Prints very verbose log output | |
| -silent | Prints only output on errors or warnings | |
| -quiet | Prints no output at all | |
| -force | Continue, even if serious warnings occur | |
| -errors_ignore | Continue, even if errors occur (if possible). Use with caution! | |
| -print_log_stats | Print additional log statistics: Log stats: FE=0,E=1,SW=0,W=0,I=1 Where FE…I identifies the message type „fatal error“ … „information“ | |
| -gui | Run with old graphical interface (if possible) | |
| -version | Print version and license summary and exit | |
| -cpu64 | Run multi core processes in 64 bit | Only certain tools |
| -cores [n] | Use [n] cores for multi processing | Only certain tools |
| -license | Print license information and exit | Only licensed tools |
| -fail | Fail if license is invalid (avoid running in demo mode) | Only licensed tools |
Help system
Our reference help system is the [toolname]_README.md files (like las2dem_README.md) and laslook with the full argument database. Additionally, all tools have a „-h“ or „-help“ argument to display online help. This also resulted in all module arguments being printed and the actual arguments of the tool itself were not so easy to see. Now the „-h“ argument only prints the tool help. To also print the module arguments, the argument „-hh“ can be used.