Background

The documentation of LAStools has grown steadily in recent years. At the moment there are 3 sources available:

The reference information in the readme files has not always been updated for changes and
enhancements, so:

  • some arguments/parameters were missing
  • some arguments didn’t work
  • some arguments were mentioned but not explained

Even professional users who don‘t need a tutorial need a good reference. Also creating a LAStools GUI/Wrapper requires precise knowledge of which argument works with the tools. That’s why we analyzed the entire code and adjusted all readmes at the same time.
The result was the creation of a database that allows easy filtering and searching for tools, modules, and arguments. So the new LAStools GUI will be able to quickly search for arguments and functions and give a very clear overview of the tool functions.
As side effects, we can now also:

  • enforce automated use of the tools – e.g. for automated testing
  • generate reference information (like the readme files) at the push of a button
  • may reverse generate the -h output of tool

The new README files

All readmes are structured according to the following scheme:

  • title
  • description
  • see also (references, optional)
  • examples (optional)
  • argument reference
    • tool specific arguments
      • ungrouped
      • (grouped, optional)
      • common (like -h,-v,…)
    • module specific arguments
      • grouped
      • module argument details
  • license info
  • outro

The description will be updated as before. Significant changes will be updated in prose language. The
reference will show the most important changes – automatically generated and clear.

Our new readmes are available as ZIP file and in the current release of LAStools.

Data quality

The syntactical quality of the reference information within the readme should be fairly high. It doesn’t say much about semantics. The semantics should come into play with the use cases. Also LAStools itself has many good internal checks about the semantics of argument combinations. The new status of the readmes represents a solid basis for the further development of LAStools.

Tools and modules

The arguments are split into the arguments of the tool and the arguments of the modules used by the tool. Arguments of a module are grouped into groups. Most of a tool’s arguments are grouped internally, but are not grouped for the output (because the groups there tend to be quite small and a tool’s arguments might be seen as a single list).

Grouping

In the past, you only got each argument once in a readme’s argument list. There were groups like “Filter” and “Modification” or “Transform coordinates” and “Modify user data”.

One problem is that many arguments belong to more than one group. While this is taken into account in the internal database, it leads to either an information gap or redundancy in the readmes.
We have opted for redundancy. If you search for an argument in a specific group, you will find all arguments that belong to that group, even if that argument is already listed in another group.
Example: The argument -copy_user_data_into_attribute will be in the group of “User data” as well as in “Attributes / Extra Data”. This makes the readmes larger, but ensures that all information is found when looking at a specific group.
Each argument is described on a single line. In case an argument requires further explanation, it is described in the introduction (if it is an argument specific to that tool), or below the argument groups
(if it is a general argument used by more than one tool).
In total there are more than 1300 different arguments in more than 50 tools and 9 global modules.
This shows the power of LAStools. With the new documentation, forces are unleashed to make all features available to all users. In the long term, grouping will become less important as more full-text based search options for named and tagged arguments will be added.

Groups

ColorPoints RGB/CIR/NIR channels
CoordinatesPoint coordinates (scaled)
Simple thinningFilter points with simple thinning
Return numberPoint return number or return count
Scanner channelPoint scanner channel
ScanlineScanline / Flightline
Source IDPoint source ID
User dataPoint user data
VLRVariable length record
TilesTile bounding box buffers
ClassificationPoint classifications
Extra bytePoint extra byte attributes
FlagsPoint flags
GPS timePoints GPS time
IntensityPoint intensity
Raw point valuesOperations on raw xyz integers
RegistersOptional Registers(0..15)
Scan anglePoints scan angle
Waveform packetWaveform packet EVLR
CRSCoordinate Reference Systems
LogicalGeneral filter and transformation logic
InputInput data
OutputOutput data
BasicsBasic tool arguments

Format changes

  • from text to markdown
  • all TABs are unified to spaces
  • all files are now UTF-8 with BOM and CRLF line endings

Any good Linux and Windows editor knows how to display this nicely. If you are having trouble viewing it, consider using a more powerful text editor such as cudatext, notepad++, ultraedit,…