Background
The documentation of LAStools has grown steadily in recent years. At the moment there are 3 sources available:
- reference info in the *_readme.txt files
- the blogs on www.rapidlasso.com and www.rapidlasso.de
- our LAStools google group https://groups.google.com/g/lastools
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
- tool specific arguments
- 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
| Color | Points RGB/CIR/NIR channels |
| Coordinates | Point coordinates (scaled) |
| Simple thinning | Filter points with simple thinning |
| Return number | Point return number or return count |
| Scanner channel | Point scanner channel |
| Scanline | Scanline / Flightline |
| Source ID | Point source ID |
| User data | Point user data |
| VLR | Variable length record |
| Tiles | Tile bounding box buffers |
| Classification | Point classifications |
| Extra byte | Point extra byte attributes |
| Flags | Point flags |
| GPS time | Points GPS time |
| Intensity | Point intensity |
| Raw point values | Operations on raw xyz integers |
| Registers | Optional Registers(0..15) |
| Scan angle | Points scan angle |
| Waveform packet | Waveform packet EVLR |
| CRS | Coordinate Reference Systems |
| Logical | General filter and transformation logic |
| Input | Input data |
| Output | Output data |
| Basics | Basic 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,…