!!!!Note, as of April 1 2012, the Wiki manual is under revision, however, the information below is up to date!!!!

The most recent (now out of date) version of the LiDAR Viewer Manual can be found here in pdf format:
Click here to download LiDAR Viewer Manual

This document describes how to install the Virtual Reality User Interface (Vrui) and the LidarViewer. It also provides a tutorial on navigating a dataset within Vrui. Through the use of pre-packaged datasets, this document also provides information about preparing data for the LidarViewer and then performing certain tasks within the program.

While this user’s manual focuses on using LiDAR Viewer in desktop environments, the software also works in semi-immersive or fully immersive virtual reality (VR) environments, such as Geowalls or CAVEs. The software offers similar functionality in all supported environments, but its user interface is environment-dependent.

Author: Peter Gold and Christopher Bowles. Programmer: Oliver Kreylos.

All questions about installation and use of this program should be directed to keckcaves_help@ucdavis.edu

Vrui and LidarViewer are free software. They can be redistributed and/or modified under the terms of the GNU General Public License as published by the Free Software Foundation.

Vrui is a C++ software development toolkit for highly interactive virtual reality applications, with a focus on portability between vastly different virtual reality environments, from laptop or desktop computers to CAVEs and other fully immersive systems. More information about Vrui can be found at http://idav.ucdavis.edu/~okreylos/ResDev/Vrui or http://www.keckcaves.org.

Vrui's development was supported by the University of California, Davis, by the UC Davis W.M. Keck Center for Active Visualization in the Earth Sciences (KeckCAVES, http://www.keckcaves.org), and the W.M Keck Foundation.

Light Detection and Ranging (LiDAR) data provides very high resolution imagery to the remote sensing community. In its simplest form, LiDAR creates a point cloud which is a series of returns (points) that each contain an x, y, z, (location) and usually i (intensity). Generally, the remote sensing community sub-samples and reduces these data to create digital elevation models (DEMs). The LidarViewer provides an opportunity for the user to view point cloud datasets without sub-sampling or reducing the data. The program will load in a point cloud and display each individual point from the survey. The LidarViewer allows the user to select points and extract them to a separate file, extract primitives (plane, sphere, cylinder) from selected points, determine distance from a plane, and navigate in real-time through large datasets (>1.2 billion points). It is a powerful tool that can provide unique perspectives to LiDAR datasets that are difficult to attain through DEMs.

The following section will detail how to install VRUI and LidarViewer. The commands used during installation will vary greatly with the directory structure that is utilized. A certain structure is recommended (especially if using Mac OS), but if a different organization scheme is preferred, the following font format will be of use to determine what needs to be altered: (It is strongly recommended that you use the recommended structure, especially if you have little experience with Linux or the terminal window in Mac OS).

Commands will be in these boxes 

This is the box that will come after a command to describe what that command does 

1. Operating System: UNIX, Linux, or Macintosh OS X (Not available for Windows OS)
2. Mac OSX systems also require Xcode
   1. The Xcode package is not a standard install for the Mac OS and therefore needs to be installed separately. It is available on the installation disks as an optional install. It can also be download from http://developer.apple.com/tools/download/. This code will only work with Snow Leopard (OS 10.6). For Mac OS Leopard (OS 10.5) go to the following link https://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/getSoftware?bundleID=20414.
   2. It may be necessary to install Command Line Tools, especially if using more recent iterations of Xcode. Open Xcode Preferences, click the Downloads button, and Install Command Line Tools.

LiDARViewer may often be referred to as LV

Throughout this manual, we use example data that has been downloaded from OpenTopography. Specifically, the lidar data used throughout this manual is from the 2007 EarthScope Northern California Lidar Project. The data we provide for this tutorial is freely available from OpenTopo. OpenTopo is pretty much the best. OpenTopography

Homebrew is a package manager for Mac OS and is the recommended tool for installing Vrui and LidarViewer on Mac OS platforms. You can also follow the Linux Install instructions below, however, the packaged install with Homebrew is faster and simpler.

To install Vrui via Homebrew:

1. Install Xcode
2. Install Homebrew
3. Download LidarViewerExamples.zip (Move this file to your Desktop and unpack)

In a Terminal window:

1. First type:

   $ brew tap KeckCAVES/keckcaves

2. Install Vrui:

   $ brew install vrui

3. Install Vrui Example Programs:

    brew install vrui-examples

4. Test the Vrui install:

   $ ShowEarthModel

   Vrui window should open displaying a rotating globe

5. Install LidarViewer:

   $ brew install lidarviewer

6. Test LidarViewer install:

   $ LidarViewer Desktop/LidarViewerExamples/PtArena.lidar

   LidarViewer window should open showing point cloud

Download and install:

1. X11
2. OpenGL
3. C/C++ compiler
4. png library
5. tiff library
6. jpeg library

Download latest versions of Vrui and LidarViewer from:

1. Vrui (Do not unpack yet!!)
2. LidarViewer (Do not unpack yet!!)
3. LidarViewerExamples.zip (Move this file to your Desktop and unpack)

Open a terminal or X11 window (Mac – Applications → Utilities → Terminal or X11)

NOTE: <version> will be used as a substitute for the actual version numbers (e.g., 2.2-001), which change periodically.

$ mkdir ~/src 

makes a directory called src in your home directory 

To see what your home directory is:

$ echo $HOME 

prints the home directory (usually /Users/YourUserName)

Move the 3 .tar.gz files downloaded to this directory. This is easily done by dragging the files to the src folder. However if you want to remain true to the terminal here are the commands needed to move the files:

$ mv ~/Desktop/Vrui<version>.tar.gz ~/src
$ mv ~/Desktop/LidarViewer<version>.tar.gz ~/src 

 move Vrui and LidarViewer to ~/src directory 

Unpack the Vrui and LidarViewer source tarballs

$ cd src

move to src directory that contains tarballs

Then unpack:

$ tar zxvf Vrui<version>.tar.gz
$ tar zxvf LidarViewer<version>.tar.gz

Unpack Vrui tarball
Unpack LidarViewer tarball

To make things easier when typing in a name, you can press tab and if the computer has enough information it will complete the phrase.
For example – open the terminal, type:

$ cd ~/De 

At this point press tab. Desktop should be filled in. This comes in handy when dealing with long and complicated filenames, like the three files you just downloaded.

VRUI must be installed before LV can be installed

The following instructions, along with instructions for additional install options can be found in /src/Vrui<version>/README

$ cd Vrui<version>
$ make && make install 

moves you to the Vrui directory
compiles the software 

The build will take several minutes. If there are error messages during the build, read the README file in the ~/src/Vrui<version> directory. The support for PNG and JPEG is an important section if errors concerning JPEG or PNG missing files occur.

To test that VRUI was installed correctly and your computer is capable of running the program:

$ cd ~/src/Vrui<version>/ExamplePrograms/

move to ExamplePrograms directory

Then:

$ make 

compile the programs 

After everything is compiled and there are no errors

$ cd bin

move to bin folder containing program executable

$ ./ShowEarthModel 

runs the Earth Model Program 

Vrui window should open and display a rotating globe.

The following instructions, along with instructions for additional install options can be found in /src/LidarViewer<version>/README

Open the LidarViewer makefile in /src/LidarViewer-<version> and make sure version of Vrui indicated in the first line of code (VRUI_MAKEDIR := $(HOME)/Vrui-<version>/share/make) matches the Vrui version you just installed

$ cd LidarViewer<version>
$ make 

moves you to the LV directory
compiles the software 

The build will take several minutes. If there are error messages during the build, read the README file in the ~/src/LidarViewer-2.5 directory. The support for PNG and JPEG is an important section if errors concerning JPEG or PNG missing files occur. If the organizational structure of your computer is different, you will also need to read this document.

Test LidarViewer install

$ cd ~/src/LidarViewer<version>/bin
$ ./LidarViewer ~/Desktop/LidarViewerExamples/PtArena.lidar/ 

moves to the directory with LidarViewer executable
calls the LV program and tells LV where the pre-processed data is that the program should load

LidarViewer should open and display a grey-scaled lidar point cloud.

LidarViewer is comprised of several programs for dealing with large lidar datasets. LidarViewer is used to visualize point clouds, the rest of the programs are for processing lidar data for visualization in LidarViewer, or for other processes useful in manipulation lidar data.

• 2.1 LidarViewer - Platform for interactive visualization, measurement, and analysis program for large >TB lidar datasets.
• 2.2 LidarPreprocessor - Converts lidar datasets in ascii, las, etc. format to LidarViewer .lidar format.
• 2.3 LidarIlluminator - Calculates normals to each lidar point, allowing enhanced point cloud visualization using a real-time hillshading effect.
• 2.4 LidarExporter - Exports user-defined sections of lidar datasets.
• 2.5 LidarSubtractor - Subtracts lidar data, such as points selected for removal, from .lidar files.
• 2.6 PointSetSimilarity - Compares two datasets and determines a percent similarity
• 2.7 LidarGridder
• 2.8 CalcLasRange - Calculate parameters of .las files
• 2.9 PaulBunyan
• 2.10 PrintPrimitiveFile - Prints parameters of geometric primitives

1. If you installed Vrui and LidarViewer on Mac OS X using Homebrew, you can call a LidarViewer program from whichever directory you happen to be in-in Terminal:

$ LidarViewer Desktop/LidarViewerExamples/PtArena.lidar

Call LidarViewer to open PtArena example dataset

2. If you followed the standard installation instructions for Mac OS X, you must move to the src/LidarViewer<version>/bin directory to launch LidarViewer and related programs:

$ cd src/LidarViewer<version>/bin

move to location of LidarViewer executable

bin <YourUserName>$ ./LidarViewer Desktop/LidarViewerExamples/PtArena.lidar

Call LidarViewer to open PtArena example dataset

LidarPreprocessor will process the following columns of a lidar dataset for visualization in LidarViewer:

1. x,y,z (points will be colored black if not colored by user);
2. x,y,z,i (points will by colored by intensity (i = intensity) of the laser return, which may need to be scaled (covered later);
3. x,y,z,r,g,b (points colored by rgb values, which can be true color collected during scanning, or artificial color assigned using LidarPreprocessor.)

LidarPreprocessor is flexible with column order, delimiter (e.g., comma, space, tab, etc.), and type of file, but you must know the order of the columns. For example, check the column order of the PtArena.txt lidar file by typing in Terminal:

$ head Desktop/LidarViewerExamples/PtArena.txt

prints out the first 10 lines of a text file, very helpful when dealing with large text files 

The result is:

x,y,z,classification,gpstime,scan_angle,intensity,number_of_returns,return_number,point_source_ID,edge_of_flight_line_flag,direction_of_scan_flag,user_data,red_channel,green_channel,blue_channel
442000.04,4314018.69,36.41,1,165688.344000000011874,0,5,0,0,2,0,0,0,0,0,0
442000.37,4314018.98,36.41,1,165688.344000000011874,0,6,0,0,2,0,0,0,0,0,0
442000.68,4314019.25,36.42,1,165688.344000000011874,0,6,0,0,2,0,0,0,0,0,0
442001.30,4314019.79,36.46,1,165688.344000000011874,0,5,0,0,2,0,0,0,0,0,0
442000.32,4314016.42,36.44,1,165688.369000000006054,0,4,0,0,2,0,0,0,0,0,0
442000.63,4314016.69,36.47,1,165688.369000000006054,0,5,0,0,2,0,0,0,0,0,0
442000.95,4314016.98,36.45,1,165688.369000000006054,0,5,0,0,2,0,0,0,0,0,0
442001.57,4314017.53,36.50,1,165688.369000000006054,0,6,0,0,2,0,0,0,0,0,0
442002.20,4314018.09,36.51,1,165688.369000000006054,0,5,0,0,2,0,0,0,0,0,0

NOTE: Column order starts at 0, so the column order for this file is: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16.

In this case, we are interested in x,y,z,i, or columns 0 1 2 6.

The full form command to run LidarPreprocessor is:

$ ./LidarPreprocessor –np <number of points> -ooc <memory cache size> -header <number of header lines> -lasOffset <Δx> <Δy> <Δz> -o <path/to/output file> <input file type> -c <r> <g> <b> <path/to/input files> 

Not all commands are necessary to run LidarPreprocessor, for example, if the dataset does not have a header, does not need to be colored and does not need to be offset, then command to run LidarPreprocessor is:

$ ./LidarPreprocessor –np <number of points> -ooc <memory cache size> -o <path/to/output file> <input file type> <path/to/input files> 

-np <number of points> – specifies the maximum number of LiDAR points to store in each octree node. Should be a power of two; 4096 is the recommended number to use.

-ooc <memory cache size> – specifies the amount of physical memory (im Mb) to use during the operations. This should be set to half the computer's physical memory (RAM). If you do not specify -ooc the default cache size is 512 Mb, on the assumption that you have 1 GB of RAM.

-header <number of header lines> – specify the number of header lines your text file has.

-o <path/to/output file> – specifies the name of the generated .lidar file. The preprocessor will create a directory of that name and create 'index' and 'points' files inside that directory. Specify and extension of '.lidar'.

-lasOffset <Δx> <Δy> <Δz> – adds/subtracts the specified quantity to the x, y, and/or z coordinates of each lidar point. LidarViewer uses floating point numbers, which allow a greater range at the expense of precision, thus -lasOffset is a critical step for datasets that are in UTM where the x and y coordinates have 6 or 7 digits before the decimal place. See example below.

<input file type>

-lasClasses <class 0> <class 1> … <class n> – specifies that all following input files are LAS interchange files. (question from Dawn: does this require a specific file extention? I had a .las file that -auto worked for, but I didn't see a -las file type in the wiki here. My points were unclassified.)

LAS 1.3 classes (ASPRS Standards for Lidar point classes):

-ascii <x column> <y column> <z column> <intensity column> – specifies that all following files are generic ASCII input files with space- or comma-separated columns. The four additional parameters specify the zero-based column indices of x, y, z, and intensity values, respectively. The input file extension for these files can be .txt

-lidar – specifies .lidar files previously processed with LidarPreprocessor

-csv <x column> <y column> <z column> <intensity column> – almost the same as -ascii, but using a strict CSV (comma-separated value) file format. (Question from Dawn: Does the input file extension have to be .csv? No - Burak)

-asciirgb <x column> <y column> <z column> <red column> <green column> <blue column> – specifies that all following files are generic ASCII input files with space- or comma-separated columns. The six additional parameters specify the zero-based column indices of x, y, z, red, green, and blue values, respectively.

-csvrgb <x column> <y column> <z column> <red column> <green column> <blue column> – almost the same as -asciirgb, but using a strict CSV (comma-separated value) file format.

-xyzi – specifies that all following input files are ASCII files with four space-separated columns: X Y Z intensity.

-xyzrgb – specifies that all following input files are ASCII files with six space-separated columns: X Y Z red green blue. This is a shorthand for -asciirgb 0 1 2 3 4 5. The input file extension must be .xyzrgb

-auto – tells LidarPreprocessor to attempt to auto-detect the formats of all following files by their extension, where possible. This works for -bin (.bin), -binrgb (.binrgb), -las (.las), -xyzi (.xyzi), -xyzrgb (.xyzrgb), and -oct (.oct). The input file extension must match one of these file types for -auto to interpret them correctly. Note that this does not include csv or ascii data types.

-bin – specifies that all following input files are binary files of 3D points with intensity values.

-binrgb – specifies that all following input files are binary files of 3D points with RGB color values.

-oct – specifies that all following files are LiDAR files in LiDAR Viewer version 1.x format.

-idl – you don't want to know what this is.

<r> <g> <b> Point coloring and intensity scaling

-c <red mask> <green mask> <blue mask> – specifies an RGB color mask to apply to all read LiDAR points. Any color read from an input file is component-wise multiplied with this color mask. -c is most commonly used to scale point colors from an input file's intensity range to LiDAR Viewer's range of 0-255. -c can be used to color a dataset by each point's intensity value, either with grey- or color-scaled rgb values. -c can also be used to color points solid colors (i.e., where differences in intensity are not longer apparent in the point cloud). See examples below.

The following section will detail how to process lidar data for visualization in LidarViewer.

Note: Mac OS X and most Linux distros support 'drag and drop' interaction with Terminal, that is, dragging PtArena.txt into Terminal will automatically enter the path to the file: ~/Desktop/LidarViewerExamples/PtArena.txt. Just try it.

To process the PtArena.txt lidar data, the command for LidarPreProcessor is:

$ ./LidarPreprocessor –np 4096 -ooc 2000 -header 1 –o ~/Desktop/LidarViewerExamples/PtArena_test1.lidar –ascii 0 1 2 6 ~/Desktop/LidarViewerExamples/PtArena.txt 

process the PtArena.txt lidar data file for visualization in LidarViewer

The Terminal output should read as follows:

geodynamo204:~ pogold120$ LidarPreprocessor -np 4096 -ooc 2000 -header 1 -o /Users/pogold120/Desktop/LidarViewerExamples/PtArena_test1.lidar -ascii 0 1 2 6 /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt 
Processing generic ASCII input file /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt... done.
Bounding box: [441451.610000, 442080.220000] x [4313835.440000, 4314391.700000] x [-8.570000, 87.630000]
RGB range: [0.000000, 108.000000] x [0.000000, 108.000000] x [0.000000, 108.000000]

Storing 2167222 points as temporary octree... done
Creating octree for 2167222 points
Creating octree... 100.000000% done
Octree contains 2961 nodes with up to 4096 points per node in 7 resolution levels
Processing octree level 0
Processing octree level 1
Processing octree level 2
Processing octree level 3
Processing octree level 4
Processing octree level 5
Processing octree level 6
Octree file sizes are 71092 bytes and 58917764 bytes
Writing final octree files... done
Time to load input data: 2.947980s, time to create octree: 6.832620s, time to write final octree files: 1.273235s

There should now be a folder in the LidarViewerExamples folder called PtArena_test1.lidar containing two folders: Index and Points

Then, to view the data in LidarViewer:

$ ./LidarViewer ~/Desktop/LidarViewerExamples/PtArena_test1.lidar 

visualize PtArena_test.lidar with LidarViewer

It should look like this:

Don't be alarmed-it probably worked, but the point colors need to be scaled. Place your cursor in the LidarViewer window, hold the left mouse button and move the mouse, you should see a vague, square, grey-colored shape moving around.

In this example, we are using airborne lidar, which has very low intensity values. Thus it is necessary to up-scale the intensity to LidarViewer's range of 0-255 in order to bring the data into visible range using the -c <r> <g> <b> command. This step is a bit trial-and-error, but first we'll try -c 20 20 20:

$ ./LidarPreprocessor –np 4096 -ooc 2000 -header 1 –o ~/Desktop/LidarViewerExamples/PtArena_test2.lidar –ascii 0 1 2 6 -c 20 20 20 ~/Desktop/LidarViewerExamples/PtArena.txt 

re-processes the PtArena.txt lidar data, but this time scales the intensity to visible range

The Terminal output should read as follows:

geodynamo204:~ pogold120$ LidarPreprocessor -np 4096 -ooc 2000 -header 1 -o /Users/pogold120/Desktop/LidarViewerExamples/PtArena_test2.lidar -ascii 0 1 2 6 -c 20 20 20 /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt 
Processing generic ASCII input file /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt... done.
Bounding box: [441451.610000, 442080.220000] x [4313835.440000, 4314391.700000] x [-8.570000, 87.630000]
RGB range: [0.000000, 2160.000000] x [0.000000, 2160.000000] x [0.000000, 2160.000000]

Storing 2167222 points as temporary octree... done
Creating octree for 2167222 points
Creating octree... 100.000000% done
Octree contains 2961 nodes with up to 4096 points per node in 7 resolution levels
Processing octree level 0
Processing octree level 1
Processing octree level 2
Processing octree level 3
Processing octree level 4
Processing octree level 5
Processing octree level 6
Octree file sizes are 71092 bytes and 58917764 bytes
Writing final octree files... done
Time to load input data: 4.038383s, time to create octree: 6.675681s, time to write final octree files: 1.279950s

$ ./LidarViewer ~/Desktop/LidarViewerExamples/PtArena_test2.lidar 

visualize PtArena_test2.lidar with LidarViewer

After moving the data about a bit, you should see gray-scaled intensity-colored point cloud:

Or if we use -c 50 50 50, we would see a brighter gray-scaled intensity-colored point cloud:

$ ./LidarPreprocessor –np 4096 -ooc 2000 -header 1 –o ~/Desktop/LidarViewerExamples/PtArena_test3.lidar –ascii 0 1 2 6 -c 50 50 50 ~/Desktop/LidarViewerExamples/PtArena.txt 

re-processes the PtArena.txt lidar data, but this time scales the intensity to a different visible range

$ ./LidarViewer ~/Desktop/LidarViewerExamples/PtArena_test3.lidar 

visualize PtArena_test3.lidar with LidarViewer

After moving the data about a bit, you should see brighter gray-scaled intensity-colored point cloud:

We already have covered how to process grey-scaled intensity colored lidar datasets, but if needed, point clouds can be colored by any RGB combination. For example:

red-scaled intensity (-c 50 0 0)	green-scaled intensity (-c 0 50 0)	Oh-Brother-Where-Art-Thou-scaled intensity (-c 45 78 35)

Ultimately, the user must decide on the optimum color scaling for their purposes through trial-and-error.

Points can also be colored with solid colors, that is, without intensity scaling. This can be useful for distinguishing between points that have been classified as ground vs vegetation by automated or manual devegetation techniques. When coloring points (as opposed to scaling intensity colors), LidarPreprocessor reads RGB fractions. For example, color 102 54 14 (brown-ish) should be entered as -c 0.4 .21 .054 (because 102/255 = .4, and so on).

For example, color (1) the PtArenaGround.txt lidar data brown, and (2) the PtArenaVeg.txt lidar data green, then (3) combine them:

$ ./LidarPreprocessor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaGround.lidar -ascii 0 1 2 -c 0.4 0.21 0.054 ~/Desktop/LidarViewerExamples/PtArenaGround.txt

color ground classified points brown

points classified as ground returns)

$ ./LidarPreprocessor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaVeg.lidar -ascii 0 1 2 -c 0 0.33 0 ~/Desktop/LidarViewerExamples/PtArenaGround.txt

color vegetation classified points green

points classified as vegetation returns

Then combine the Ground and Vegetation datasets to see what is considered 'ground' and what is considered 'vegetation'.

$ ./LidarPreprocessor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaVegGround.lidar -lidar ~/Desktop/LidarViewerExamples/PtArenaGround.lidar ~/Desktop/LidarViewerExamples/PtArenaVeg.lidar

combine green-colored vegetation points and brown-colored ground point

ground- and vegetation-classified points combined

Combining .lidar files and processing multiple point sets

In the last example, we used LidarPreprocessor to stitch together two .lidar files. LidarPreprocessor can combine as many .lidar files into a single .lidar file as you need, regardless of where the datasets are on the planet. Similarly, Preprocessor can process and then combine multiple point files (e.g., .txt, .asc, .xyzrgb, .las) at the same time. For example, to simplify the above classification-based point-coloring exercise into a single command line, do:

$./LidarPreprocessor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaVegGround.lidar -ascii 0 1 2 3 -c 0.4 .21 .054 ~/Desktop/LidarViewerExamples/PtArenaGround.xyzrgb -c 0 0.33 0 ~/Desktop/LidarViewerExamples/PtArenaVeg.xyzrgb

Now that we can see the data, zoom in on PtArena_test3.lidar. This data covers a section of the San Andreas fault that trends NW-SE. When you zoom in, you should see two grains in the data. The most apparent grain, which trends NE-SW at an angle to the screenshot, reflects the orientation of the airborne lidar swaths. The other grain trends east-west parallel to the top of the screenshot, and is an artifact resulting from LidarViewer's use of floating point numbers. (the latter can be more difficult to see at first).

LidarViewer represents data coordinates using floating point numbers, which lack the requisite precision for datasets in UTM coordinates. Here's what happens: the geographic center of this dataset is around (441779.794876, 4314113.71734, 41.1276550292), but LidarViewer will read this point as (441779.79, 4314113.7, 41.127655). The greater loss of precision of the y (northing) coordinate results in points being collapsed along east-west oriented lines. Thus you would want to apply an offset as follows: -lasOffset -441700 -4314100 0.

Try:

$ ./LidarPreprocessor –np 4096 -ooc 2000 -header 1 -lasOffset -441700 -4314100 0 –o ~/Desktop/LidarViewerExamples/PtArena_test4.lidar –ascii 0 1 2 6 -c 20 20 20 ~/Desktop/LidarViewerExamples/PtArena.txt 

re-processes the PtArena.txt lidar data, but this time scales the intensity to visible range and offset the points to increase precision

The Terminal output should read as follows:

geodynamo204:~ pogold120$ LidarPreprocessor -np 4096 -ooc 2000 -header 1 -lasOffset -441700 -431400 0 -o /Users/pogold120/Desktop/LidarViewerExamples/PtArena_test4.lidar -ascii 0 1 2 6 -c 20 20 20 /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt 
Processing generic ASCII input file /Users/pogold120/Desktop/LidarViewerExamples/PtArena.txt... done.
Bounding box: [-248.390000, 380.220000] x [3882435.440000, 3882991.700000] x [-8.570000, 87.630000]
RGB range: [0.000000, 2160.000000] x [0.000000, 2160.000000] x [0.000000, 2160.000000]

Storing 2167222 points as temporary octree... done
Creating octree for 2167222 points
Creating octree... 100.000000% done
Octree contains 2969 nodes with up to 4096 points per node in 7 resolution levels
Processing octree level 0
Processing octree level 1
Processing octree level 2
Processing octree level 3
Processing octree level 4
Processing octree level 5
Processing octree level 6
Octree file sizes are 71284 bytes and 58984036 bytes
Writing final octree files... done
Time to load input data: 3.222012s, time to create octree: 6.577037s, time to write final octree files: 1.085286s

There should now be and additional file in the PtArena_test4.lidar called Offset in addition to Points, and Index.

$ ./LidarViewer ~/Desktop/LidarViewerExamples/PtArena_test4.lidar 

visualize PtArena_test_v4.lidar with LidarViewer

PtArena_test3-Without offset (bad)	PtArena_test4-With offset (correct)

When you use the -lasOffset command, an 'offset' file is added to the .lidar project created by LidarPreprocessor. However, be sure to record the offset you use in case you need to remove it later.

LidarIlluminator is an important processing step that allows the point cloud data to be viewed in LidarViewer with a real-time hillshadeing effect, similar to how DEMs are commonly visualized. The hillshading effect can be toggled on/off, and the illumination (i.e., sunlight) direction can be changed in real-time.

Intensity colored point cloud	Illuminated point cloud

How does this work? LidarIlluminator illuminates the point cloud's 'surface' by calculating a normal vector for each point in the dataset. This normal is calculated as the normal to a least-squares approximate best-fit plane through a selection of data points surrounding the point in question. This selection is chosen either by gathering all the points within a specified radius of the point in question, or by choosing the closest n neighboring points to the point in question. Distances are Euclidean.

How wide of a radius to use or how many neighbors to specify depends on the resolution of the dataset, and the best result will come with a bit of trial and error. Too large of a radius or too many neighbors will consider too many points, which has the effect of visually smoothing the topography (though the topography is not actually smoothed).

The LidarIlluminator step will add a 'normals' file to the .lidar project created by LidarPreprocessor.

$ ./LidarIlluminator –cache <cache size> -radius <approximation radius> <input LiDAR file> 

OR

$ ./LidarIlluminator –cache <cache size> -neighbors <approximation radius> <input LiDAR file> 

-cache <cache size> – similar to –ooc from LidarPreprocessor. Set this value to half the computer’s physical RAM size in megabytes.

-radius <approximation radius> – for each point, LidarIlluminator finds all nearby points not farther away from the point in question than the <approximation radius>, measured in Euclidean distance. The approximation radius has to be selected appropriately for a given data set. A good starting guess is to set it to about twice the average point spacing in the data. The value uses the measurement units native to the .lidar file.

-neighbors <number or neighbors> – for each point, LidarIlluminator considers the number of neighbors, not their distance. -neighbors k collects a point's k nearest neighbors (in the Euclidean sense), including the point itself, and fits a plane through them to calculate the point's normal. A good stating guess for the number of neighbors is k=15.

-<input LiDAR file> – query the .LiDAR file directory created from the LidarPreprocessor

Lets try:

$ ./LidarIlluminator –cache 2000 -radius 1 ~/Desktop/LidarViewerExamples/PtArena_test4.lidar/ 

OR

$ ./LidarIlluminator –cache 2000 -neighbors 15 ~/Desktop/LidarViewerExamples/PtArena_test4.lidar/ 

The Terminal output should read as follows:

geodynamo204:~ pogold120$ LidarIlluminator -cache 2000 -radius 1 /Users/pogold120/Desktop/LidarViewerExamples/PtArena_test4.lidar 
Cache size: 31922 memory nodes
Calculating normal vectors... 100%

There should now be and additional file in the PtArena_test4.lidar called Normals in addition to Points, Index and Offset.

If you specify both -radius and -neighbors, LiDAR Viewer considers only the intersection of the two sets, meaning the up to k nearest neighbors less than radius away. This is a way of curtailing runaway searches, since otherwise in sparse areas of a data set -neighbors alone might have to go to a very large search radius, which might take a very long time.

$ ./LidarIlluminator –cache 2000 -radius 1 -neighbors 15 ~/Desktop/LidarViewerExamples/PtArena_test2.lidar/ 

See the following section Using LidarViewer on how to use Illuminator and make sure this worked.

LidarExporter is a useful tool for exporting subsets of large lidar datasets.

The command is:

$./LidarExporter -cache <cache size> -box <x-min> <y-min> <z-min> <x-max> <y-max> <z-max> <input .lidar file> <output .xyzrgb file>

-cache <cache size> – same as for LidarIlluminator. This value should be set to half of your computer's RAM in MB.

-box <x-min> <y-min> <z-min> <x-max> <y-max> <z-max> – defines a bounding box that will capture and export all points with x-coordinate between x-min and x-max, y-coordinates between y-min and y-max and z-coordinates between z-min and z-max.

<input .lidar file> – path to and name of the Preprocessed .lidar file from which you wish to extract points.

<output .xyzrgb file> – path to and name of the point file to be exported. You can put whatever extension you would like (e.g., .txt, .asc, .xyzrgb) and the points will be exported as x,y,z,r,g,b. For grey-scaled intensity colored point clouds, r, g, and b will have the same value.

Let's Export a section of data from the center of the PtArena_test2.lidar project processed earlier (dont worry about the offset for now). How to measure the coordinates in LidarViewer will be covered later in this manual, for now though, try exporting the data that lies within a box with coordinates x:[441609,441940], y:[4313934,4314244], and z:[0,1000]. (Make z-max high so as not to cut off the tops of any mountains).

The code is:

$./LidarExporter -cache 2000 -box 441609 4313934 0 441940 4314244 1000 ~/Desktop/LidarViewerExamples/PtArena_test2.lidar ~/Desktop/LidarViewerExamples/PtArena_export.xyzrgb

The Terminal output should read as follows:

geodynamo204:~ pogold120$ LidarExporter -cache 2000 -box 441609 4313934 0 441940 4314244 1000 /Users/pogold120/Desktop/LidarViewerExamples/PtArena_test2.lidar /Users/pogold120/Desktop/LidarViewerExamples/PtArena.xyzrgb
Cache size: 31922 memory nodes
759461 points saved

Then:

./LidarPreprocessor -np 4096 -o ~/Desktop/LidarViewerExamples/PtArena_export.lidar -ascii 0 1 2 3 ~/Desktop/LidarViewerExamples/PtArena_export.xyzrgb

And finally:

$./LidarViewer ~/Desktop/LidarViewerExamples/PtArena_export.lidar

Original .lidar dataset	Exported lidar dataset

LidarExporter can also be used to pull the relavent columns of data from multi-column datasets.

Remember that the raw data for the PtArena.lidar looked like this:

$ head ~/Desktop/LidarViewerExamples/PtArena.txt

x,y,z,classification,gpstime,scan_angle,intensity,number_of_returns,return_number,point_source_ID,edge_of_flight_line_flag,direction_of_scan_flag,user_data,red_channel,green_channel,blue_channel
442000.11,4314021.19,36.33,2,165688.318999999988591,0,5,0,0,2,0,0,0,0,0,0
442000.42,4314021.46,36.36,2,165688.318999999988591,0,5,0,0,2,0,0,0,0,0,0
442000.04,4314018.69,36.41,1,165688.344000000011874,0,5,0,0,2,0,0,0,0,0,0
442000.37,4314018.98,36.41,1,165688.344000000011874,0,6,0,0,2,0,0,0,0,0,0
442000.68,4314019.25,36.42,1,165688.344000000011874,0,6,0,0,2,0,0,0,0,0,0

But we only need columns 0, 1, 2, and 6 (x,y,z,intensity). After Exporting, the data looks like this:

$ head ~/Desktop/LidarViewerExamples/PtArena_export.xyzrgb

441609.125000 4313935.000000 2.310000 100 100 100
441609.375000 4313935.000000 2.350000 080 080 080
441609.062500 4313934.500000 2.380000 120 120 120
441609.718750 4313935.000000 2.380000 040 040 040
441609.375000 4313935.500000 2.290000 020 020 020

Note that LidarExporter does not include a header.

Important: LidarExporter reads Offset files (created when applying an offset with -lasoffset with LidarPreprocessor). This means that if you export points from an offset dataset, LidarExporter will remove the offset upon export, thus restoring coordinates to their original state. For example, examine the PtArena_test4.lidar project created above during the explanation of the -lasoffset command:

First:

$ ./LidarExporter ~/Desktop/LidarViewerExamples/PtArena_test4.lidar ~/Desktop/LidarViewerExamples/PtArena_test4.xyzrgb

Then:

$ head ~/Desktop/LidarViewerExamples/PtArena_test4.xyzrgb

441469.750000 4313835.549988 -6.380000 080 080 080
441470.119995 4313835.790009 -6.370000 080 080 080
441470.830002 4313835.589996 -6.380000 120 120 120
441470.500000 4313836.029999 -6.370000 080 080 080
441469.020004 4313836.010010 -6.310000 120 120 120

If LidarExporter had not removed the offset, the data would look like this:

-230.250000 -264.450012 -6.380000 080 080 080
-229.880005 -264.209991 -6.370000 080 080 080
-229.169998 -264.410004 -6.380000 120 120 120
-229.500000 -263.970001 -6.370000 080 080 080
-230.979996 -263.989990 -6.310000 120 120 120

This tool allows the user to subtract a selected dataset from the .lidar data file that the points were selected from. This is useful if one wants to clip data or manually remove vegetation or extraneous points from a LiDAR point cloud. The LidarSubtractor will create another .lidar file ready for the LidarViewer minus the selected points. Illumination must be recalculated for the new .lidar file.

$./LidarSubtractor –np <num points> -ooc <cache size> -o <output file> <base LiDAR file> <selected point set> -eps <epsilon> 

This is very similar to LidarPreprocessor because it is creating .lidar files.

-np <number of points> – specifies the maximum number of LiDAR points to store in each octree node. Show be a power of two; 4096 is the recommended number to use.

-ooc <memory size> – specifies the amount of memory to use for out-of-core processing, in megabytes (mb). Should be roughly half the computer’s physical memory.

-o <output file> – specifies the name of the generated LiDAR file. The preprocessor will create a directory of that name and create an index and points file inside that directory. An extension of .LiDAR for the folder is recommended to indicate that the folder is specific to the LidarViewer.

<base LiDAR file> – The original data file (.LiDAR file)

<selected point set> – The selected points in the .xyzrgb file

-eps <epsilon> – a fudge value to identify matching points. Due to floating-point issues, you need a non-zero epsilon to reliably match points between the base file and the selected set. For airborne LiDAR, a value of 0.01 (1 cm) seems to do the job. For tripod Lidar, you'll want to use a millimeter or even less. Again this value will change with units of original data.

In this example we'll subtract the PtArena_export.xyzrgb produced in the LidarExporter example above from the PtArena_test2.lidar. (Use test2 for this example because it has not been Offset-see footnote below about how LidarSubtractor handles Offset files).

Conceptually:

PtArenaDonut.lidar = PtArena_test2.lidar - PtArena_export.xyzrgb

The command:

$./LidarSubtractor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaDonut.lidar ~/Desktop/LidarViewerExamples/PtArena_test2.lidar ~/Desktop/LidarViewerExamples/PtArena_export.xyzrgb -eps .001

The Terminal output should read as follows:

	=		-
PtArenaDonut.lidar	=	PtArena_test2.lidar	-	PtArena_export.xyzrgb

LidarSubtractor has probably most commonly been used for subtracting vegetation points from a .lidar project to isolate ground points. Vegetation points can be selected manually in LidarViewer (this will be covered later). However, in this example, we'll subtract the vegetation from the PtArenaAll.lidar data to isolate the ground surface. The file PtArenaVeg.txt in the LidarViewerExamples folder contains points that have been automatically classified as vegetation (or buildings, telephone wires, birds, etc.) by OpenTopography.org (the source of the data).

Conceptually:

PtArenaGround_v2.lidar = PtArena_test2.lidar - PtArenaVeg.txt

The command:

$./LidarSubtractor -np 4096 -ooc 2000 -o ~/Desktop/LidarViewerExamples/PtArenaGround_v2.lidar ~/Desktop/LidarViewerExamples/PtArena_test2.lidar ~/Desktop/LidarViewerExamples/PtArenaVeg.txt -eps .001

	=		-
PtArenaGround_v2.lidar (~500,000 points)	=	PtArena_test2.lidar (~2,664,000 points)	-	PtArenaVeg.xyzrgb (~2,164,000)

(In this example, PtArena_test2 and PtArenaVeg look identical because most of PtArena_test2 has been classified as vegetation, note the difference in the point counts for all three datasets)

NOTE: Discrepancies in the point count for input and output files can arise when subtracting points. These are most commonly the result of there being duplicate points in the <input .lidar file>, which in the above example is PtArenaAll.lidar.

IMPORTANT: LidarSubtractor currently (as of v. 2.8) does not read Offset files. This will likely be fixed in later versions, but for now, what this means is that you will not be able to subtract a dataset that has been LidarExported from a .lidar project if that .lidar project has had an offset has been applied using -lasOffset (if an offset has been applied to a dataset, there should be an Offset file in in the .lidar folder). This is because LidarExporter reads Offset files, so exported datasets will have the offset removed. However, because LidarSubtractor does not read Offset files, it does not know to remove the offset from a .lidar file before subtracting a point set from it. Again, this is only an issue when subtracting datasets that have been produced using LidarExporter. Subtracting points that have been selected from within LidarViewer will work whether or not an offset has been applied to the .lidar dataset.

The PointSetSimilarity tools compares two selected point sets (i.e. .xyzrgb files) and provides a similarity value in percent. This is useful during a user-study where different users self-classify points (i.e. vegetation vs. ground) and you need a way to quantify the differences. For this tool to work you will need 2 selected point sets.

The command:

$ ./PointSetSimilarity <point set 1> <point set 2> <epsilon> 

<point set 1> – 1st .xyzrgb file

<point set 2> – 2nd xyzrgb file

<epsilon> – has the same purpose and value as in LidarSubtractor. The only result from running the program is a similarity value in percent. If you compare two identical point sets, you'll get 100%. If the two point sets have not a single point in common, you'll get 0%. The exact formula is: similarity = (2 * |A ^ B| / (|A| + |B|)) * 100%

Please add content!!

If you are using .las files, its not possible to use the head or wc commands to get info about the lidar dataset, as these command only work with text files. CalcLasRange is a LidarViewer tool that will read .las files and provide:

1. number of points
2. dataset bounding box [x min, x max] x [y min, y max] x [z min z max]
3. Intensity range [i min, i max]
4. RGB range [r min, r max], [g min, g max], [b min, b max]

The command:

$ ./CalcLasRange <input .las file>

The terminal output should read as follows:

geodynamo204:~ pogold120$ CalcLasRange /Desktop/points.las 
Checking file 1 of 1:/Desktop/points.las Reading input points... done.
Total number of points: 444414
Overall point bounding box: [441452, 442080] x [4.31384e+06, 4.31439e+06] x [-8.89, 66.21]
Overall intensity range: [0, 93]
Overall RGB range: [3.40282e+38, -3.40282e+38], [3.40282e+38, -3.40282e+38], [3.40282e+38, -3.40282e+38]

Please add content!!

LidarViewer allows you to make selection of points and fit geometric primitives (lines, planes, spheres, cylinders) to the selected points. The parameters of these primitives are printed in the Terminal window when the primitive is created. However if you save the primitive but forget to record its parameters, they can be reprinted using Print PrimitiveFile.

The command:

$ ./PrintPrimitiveFile <primitive.dat file>

The Terminal output (for a plane) should read:

geodynamo204:~ pogold120$ PrintPrimitiveFile /Desktop/SavedPrimitives0001.dat 
Primitive file /Desktop/SavedPrimitives0001.dat:
Plane primitive fitting 80595 points with RMS 2.69461:
  Plane equation: (0.0527855, -0.0249189, -0.998295) * X = 46614.4
  Corner points:
    (883402, -283.178, 23.587)
    (883344, -108.371, 16.1491)
    (883577, -224.639, 31.3784)
    (883519, -49.8327, 23.9404)
  Number of segments: 10 x 10

Note As of LidarViewer 2.8, what is printed in Terminal when a primitive is created is slightly different than what PrintPrimitiveFile produces. For the above example, the Terminal output when the Primitive was created was:

Plane fitting 80595 points
Centroid: (-883470, -191.002, -55.2547)
Normal vector: (0.0527855, -0.0249189, -0.998295)
RMS approximation residual: 2.69461

LidarViewer is designed to work in most visualization environments (e.g., desktop, tracked, immersive). Thus, some of the tools that you find on the menus only work in certain environments. Similarly, several programs including LidarViewer work on top of Vrui, thus, some of the tools on the menus are not actually specific to LidarViewer, but are rather to Vrui, and may have more obvious functions in other KeckCAVES programs. In the following sections, basic navigation and interaction within LidarViewer is described. The selection of topics reflects what in our experience have been the most commonly used tools/settings in LidarViewer.

In this section:

• 3.1 Menus in LidarViewer
• 3.2 Assigning and saving tool and navigation configurations
• 3.3 Navigation in LidarViewer
• 3.4 Adjusting Illumination
• 3.5 Selecting Points
• 3.6 Creating Geometric Primitives
• 3.7 Making Measurements
• 3.8 Extracting Profiles
• 3.9 Cutting Planes and Pointers
• 3.10 Saving View Points
• 3.11 Curve File Animations

There are two basic menus in LidarViewer: The Tool Selection Menu which contains interaction tools, many of which are common the Vrui-based KeckCAVES software; and the LidarViewer menu, which contains interaction tools most of which are specific to LidarViewer.

Tool Selection Menu	LidarViewer Menu

LidarViewer's interaction and navigation tools are assigned to buttons on your input device(s) via the above menus. In a standard non-tracked desktop or laptop environments the input devices are usually the mouse and keyboard (6-axis mice can be used too). In tracked desktop and immersive environments the input devices are position tracked 'wands', which will have different button configurations depending on brand.

In standard desktop/laptop systems, controls and tools must be projected to the data to enable interaction. This is because such systems do not have tracked controls, meaning that the LidarViewer tools are not independent of the data in 3D space. In such systems, the controls and tools are locked to the screen plane, thus to interact with the data, the data must either be brought to the screen plane or the controls and tools must be projected from the screen plane to the data. Its almost always preferable to do the latter.

Assigning tools is a multi-part process:

1. Press and hold an unassigned key (letters or numbers work-if its already assigned no menu will appear):
2. Assign a tool Transformer (almost always Point Cloud Projector in non-tracked systems)
3. Release key
4. Press and hold the same key
5. Assign an interaction or navigation Tool
6. Release key

Example:

1. Assign a tool Transformer	2. Assign a Tool
Point Cloud Projector	Measurement Tool

Assigning tools in tracked systems usually involves fewer steps. In tracked environments it is not necessary to project tools to the point cloud because both are independent entities in 3D space, that is, neither are locked in place as the tools are to the screen in non-tracked systems. Thus, assigning tools such as the Measurement Tool or a Locator Tool (see below) can be done without assigning the Point Cloud Projector (just follow the latter three steps described immediately above). However, assigning navigation tools may be dependent on the type and number of tracked wands in use, and thus this process is likely to be custom to individual visualization environments and will not be covered in this manual.

Setting up multiple tools can take several minutes, so to save time at the beginning of LidarViewer sessions, it is useful to save the interaction and navigation configuration that you use most often for certain tasks. To do this,

1. Assign all the tools you usually need
2. Right Click
3. Vrui System>Devices>Save Input Graph
4. Chose the location to save the Input Graph

Save Tool Configuration (Input Graph)	Save Input Graph

To load the tools at the beginning of a session, simply:

1. Right Click
2. Vrui System>Devices>Load Input Graph
3. Navigate to the location where the Input Graph is saved

Navigation in LidarViewer is done though a combination of preassigned and user-assigned controls.

1. Rotate data: Left-click and hold while moving the mouse. Rotation is always about the intersection of the white crosshairs.
2. Zoom: Rotate mouse wheel or press and hold the 'z' key and move the mouse without pressing mouse buttons. Zoom is always to the intersection of the white crosshairs.
3. Pan: Press and hold the 'z' key and left-click and hold while moving the mouse.

When navigating with the z-key/mouse combination, it can be awkward getting the center of the crosshairs in point cloud. If the center of the crosshairs does not intersect the point cloud, then zoom will be to some location that is (wherever the crosshairs center is) above, below, outside, or otherwise dissociated from the point cloud, and rotation will be about about that location too, leading to exaggerated rotations.

Panning while maintaining contact between the point cloud and the center of the cross hairs requires assigning a navigation tool, do:

1. Press and hold an open key
2. Transformer > Point Cloud Projector
3. Release key
4. Press and hold same key
5. Navigation > Warp To Position
6. Release key

1. Assign Transformer	2. Assign Navigation Tool
Point Cloud Projector	Warp To Position

To navigate, simply move the mouse cursor so it is over whichever part of the point cloud you wish to look at, then press the assigned button. The dataset will move so that whichever part was under the mouse cursor now intersects the center of the crosshairs. Again, just try it.

Please add content if its at all universal!

LidarViewer allows you to visualize point clouds with a dynamic hillshading effect, rendering the point cloud so it appears much like a hillshaded DEM (see Section 2.3 above). Feature recognition and dataset visualization is enhanced by the ability to interactively adjust the lighting (or 'sunlight') azimuth and elevation over this 'surface'. (You must preprocess the lidar data with LidarIlluminator to use the hillshading effect-see Section 2.3 above. If there is no normals file in the .lidar folder, then Illumination has not been calculated).

To Illuminate the point cloud, open the Render Dialog:

1. Right click and hold
2. Dialogs > Show Render Dialog
3. Release mouse button

1. Open Render Dialog	2. Adjust Illumination
	Render Dialog

To turn on the hillshading effect, select Lighting and deselect Use Point Colors

To adjust lighting, select Sunlight Source, and adjust sun azimuth and elevation using the adjacent sliders.

Intensity colored point cloud	Illuminated point cloud

Point rendering can be adjusted using the top three sliders.

The Show Plane Distance option allows you to visualize the point cloud where points are color coded relative to their distance from a user defined plane in the direction of the plane's normal vector. To do this:

1. Select data (Section 3.5) and fit a plane primitive (Section 3.6).
2. Deselect Lighting
3. Select Show Plane Distance

The color gradient can be adjusted interactively with the adjacent slider.

Show Plane Distance option

Lidar data can be interactively selected and saved from within LidarViewer.

1. Assign Point Cloud Projector to an open key as described in Sections 3.2 and 3.3 (non-tracked systems only)
2. Press and hold key
3. Locator > 6-DOF Locator
4. Release key

1. Assign Transformer	2. Assign Locator (selector)
Point Cloud Projector	6-DOF Locator

A yellow sphere (the Locator) will appear. This is what you use to select points.

Locator sphere (aka Selector brush)

To select points, move the data and place the yellow sphere so that it encompasses points you wish to select, then press the assigned key. Selected points will be colored green.

Locator (selector) tool	Selected points

Important!! You must have Lighting turned off or Use Point Colors turned on in the Render Dialog (see Section 3.4) in order to see selected points.

The Locator size and action (selection or deselection) can be adjusted from the Interaction Dialog. To open, do:

1. Right click and hold
2. Dialogs > Show Interaction Dialog

1. Open Interaction Dialog	2. Adjust Locator size and action
	Interaction Dialog

Adjust Locator sphere size by sliding the Brush Size slider.

Adjust Locator action (selection/add and deselection/subtract) by pressing the Add or Subtract buttons, or by doing Right click > Selector Modes:

It can be useful to have a select/add Locator tool assigned to one key, and a deselect/subtract Locator assigned to a different key, so that you dont have to switch between modes using the methods described above. To do this:

1. Open the Interaction Dialog
2. Deselect Override Tools
3. Adjust Locator size to desired diameter
4. Select Add
5. Assign Point Cloud Projector and 6-DOF Locator to an open key
6. Select Subtract on the Interaction Dialog
7. Assign Point Cloud Projector and 6-DOF Locator to an open key

This can make data selection faster, as when classifying large amounts of vegetation returns. Unfortunately, the locator size cannot be changed once the Locator keys have been assigned.

To Save or Clear the selected points, Right click > Selection:

As of LidarViewer 2.8, Classify Selection is not operational.

LidarViewer allows you to approximate the orientations of features by fitting geometric primitives (planes, lines, spheres, cylinders) to selections of points. To do this:

1. Make a selection of points as described in Section 3.5
2. Right click and hold
3. Primitives > Extract whichever primitive is most suitable.

Example: Fit a plane that approximates the orientation of a fault scarp:

1. Select Points	2. Extract Plane	3. Plane Fit to Points

Information about the plane is printed in the Terminal window:

Plane fitting 67176 points
Centroid: (75.6878, -98.7248, -55.471)
Normal vector: (0.707812, 0.706232, 0.0154557)
RMS approximation residual: 0.0180613

Note!! The normal vector can be used to calculate strike and dip, but you can also just do Right click > Primitives > Indicate Strike and Dip. Important!! This will display Dip and Dip Direction, not strike and dip.

The intersection point or line between pairs of primitives can also be determined from within LidarViewer. To do this:

1. Clear the previous point selection: Right click > Selection > Clear Selection
2. Select points and extract a primitive as described above.
3. Select primitives to intersect

Selecting primitives requires assigning a new tool.

1. Assign Transformer > Point Cloud Projector to an open key
2. Press and hold same key
3. Dragger > 6-DOF Dragger
4. Release key

Assign Transformer	Assign Dragger tool
Point Cloud Projector	6-DOF Dragger

Then, select primitives by holding the mouse cursor over each primitive and pressing the assigned Dragger key. Selected primitives will turn blue. Then do:

1. Right click > Primitives > Intersect Primitives

1. Fit second primitive	2. Select primitives with 6-DOF Dragger tool	3. Intersect Primitives

Information about the intersection is printed in the Terminal window:

Line intersecting two planes
Center point: (76.0394, -99.1038, -54.2534)
Axis direction: (-0.706067, 0.707981, -0.0152787)
Length: 17.3472

From the Primitives menu, you can also:

1. Save Primitves
2. Load previously saves primitives
3. Delete selected primitives
4. Clear all primitives

Measuring point positions, distances, and angles in LidarViewer is straightforward. Do:

1. Assign Transformer > Point Cloud Projector to an open key
2. Press and hold same key
3. Utility > Measurement Tool
4. Release key

1. Assign Transformer	2. Assign Measurement Tool	3. Measurement Dialog

Use the dialog box to change Measurement Mode. Leave Coordinate Mode as User, the other two will be removed in future versions of LidarViewer. To make measurements, hold the mouse cursor over whichever part of the point cloud you wish to measure, and press the key assigned to the Measurement Tool.

To expand the Measurement Dialog box (so full measurement precision is shown) simply click, hold, and drag the right side of the dialog box.

This tool is under construction.

Several pointer options are available in LidarViewer than can be useful for interactively indicating specific features, however most of these only work in tracked environments. Filed under the Pointer menu is the Clipping Plane tools, which allows you to make parts of a dataset disappear, as when you want to look at something cross section. This tool does work with non-tracked systems. To use it:

1. Assign Transformer > Point Cloud Projector to an open key
2. Press and hold same key
3. Pointer > Clipping Plane
4. Release key

1. Assign Transformer	2. Assign Pointer tool
Point Cloud Projector	Clipping Plane

To use, hold the cursor over the dataset and press the key assigned to the Clipping Plane tool. Important!! Lighting must be deselected in the Render Dialog.

Intensity colored point cloud of a fault scarp	Same view, with Clipping Plane applied

Saving a view point so that a particular look-direction can be exactly restored can be useful for recording the locations of key features, or for making paired figures where the topography in each image should be identically oriented. This is a simple step.

1. Right click > Vrui System > View > Save View
2. Choose the location to save.

1. Save Viewpoint	2. Choose location to save

Recording polished 'fly-throughs' and movies demonstrating interactive measurement methods is relatively simple in LidarViewer and all KeckCAVES programs. For instructions see Making Movies (need to insert internal link)

This method requires the use of ‘awk’ a program available with Linux and Mac OS in the terminal. The reason to do this is deal with a strange format and therefore need to specify which columns to process by using the –csv command which requires a comma delimited .asc file. In general this should not be needed due to the all the different input types that the pre-processor allows. Follow these steps:

1. Open the .txt document and count the variables (use head /Location/File.txt if the file is large)

For example:
 77317.276610 11498015.57 3852279.87 791.43 77 11498015.59 3852279.88 791.36 77
 There are 9 variables in this example 

2. Open terminal and type:

$ awk '{printf "%s, %s, %s, %s, %s. %s, %s, %s, %s\n", $1, $2, $3, $4, $5, $6, $7, $8, $9}' InputFile.txt > OutputFile.asc 

The only thing that needs to be edited are the number of %s and the number of , $#’s. In the above example, there are 9 variables. If I only had 3 variables, the command would look like this:

$ awk '{printf "%s, %s, %s\n", $1, $2, $3}' InputFile.txt > OutputFile.asc 

If you need to stitch numerous files together that are large you may need to specify a folder for the LidarPreprocessor to store temporary octrees. Generally this will not need to be done as a default folder will be assigned, but if that hard drive runs out of space during processing and you have another hard drive with more free space, this command will help (i.e. This command is not useful unless you have an external hard drive or multiple internal hard drives). If when processing data, a segmentation fault error message pops up, then you are possibly out of hard drive space, use the following commands. Again, this is likely very rare and does need to specified unless problems occur when pre-processing extremely large files.

To the command line in the LidarPreprocessor add:

to /location/tmp/TempOctreeNAMEXXXXXX –tp /location/tmp/TempPointsNAMEXXXXXX 

More information:

• Location specified needs to be a completely different hard drive or it will not work.
• The 6 Xs are important and must be added because they are used as placeholders to generate unique names.

Although this is more related to VRUI then the LidarViewer, I have included it in this section because it can be helpful when viewing point clouds. This is an advanced-user feature so use at your discretion.

$ cd ~/Vrui-X.X/etc/
$ open Vrui.cfg 

note this is not the ~/src/ directory, this opens a Vrui config textfile in a text editor 

In the textfile, find the section Desktop (should be near top) then locate the line:

backgroundColor (R, G, B, 1.0) 

Change the R,G,B values to taste and save the config file. The easiest way to remember the previous background color, and be able to quickly change back to it, is to comment out the existing line (using a pound sign / hash mark “#”), and add a new line. For example, to set the background color to light gray, change

backgroundColor (0.0, 0.0, 0.0, 1.0)

to

# backgroundColor (0.0, 0.0, 0.0, 1.0)
backgroundColor (0.75, 0.75, 0.75, 1.0)

Color charts can easily be found online

A common trick is to have multiple backgroundColor lines with a set of common colors, and comment out all but one to select the color value to be used next.

The terminal is a powerful tool, but requires knowledge of the commands needed to function successfully. The following is a list of commands and suggestions to make your terminal use more efficient: '#' indicates what command does and should not be included in terminal, ignore the # as well.

$ pwd                            # prints the directory you are presently in

$ ls                             #prints a list of files and folders in the present directory

$ ls –d */                       #prints a list of folders in the present directory

$ cd [/directory/directory]      #replace directory with name of existing directory and this changes the working directory 

$ mkdir [directory]              #create a new folder

$ open [file name]               #uses default program to open program

$ mv [file name] [directory]     #moves specified file to specified directory

$ cp [file name] [directory]     #copies specified file to specified directory

$ wc –l [file name]              #spits out the number of lines a txt/ascii file has (first number)

$ rm [file]                      #deletes the file – *caution* this is permanent (i.e. does not go to recycle bin)

$ rm –rf [folder]                #deletes a folder and all its contents – **caution** this is permanent 

• Press tab to complete a file name or directory after enough information is entered.
• Press tab twice (quickly) to display a list of files within the directory, or, if part of a file name or directory is typed in it will display the possibilities that will complete the file name or folder.
• The internet is an excellent source of information on this subject if you require more knowledge. A simple search for “Terminal Commands in Mac OS” returns numerous pages with helpful hints.

The LiDAR data were acquired by a collaborative effort between the U.S. Geological Survey (USGS) and the National Aeronautics and Space Administration (NASA). The funding was provided by the NASA’s Earth Surface and Interior Focus Area. The data were acquired and processed by TerraPoint, LLC whom where under contract by NASA’s Stennis Space Center. These data are in the public domain and there are no restrictions on their use.

The DEM data were acquired by the GeoEarthScope Northern California LiDAR project as part of the EarthScope Facility project which is funded by the National Science Foundation (NSF). GeoEarthScope is managed by UNAVCO. These data are in the public domain and there are no restrictions on their use.

Both datasets were downloaded from the Geosciences Network (GEON) project. The GEON project is funded by the NSF Information Technology Research program. The website, http://www.geongrid.org contains more information about the datasets available. The site offers the ability to download customized DEM data derived from LiDAR data or the raw point cloud data from numerous LiDAR datasets.

Vrui’s development was supported by the University of California, Davis, by the UC Davis W.M. Keck Center for Active Visualization in the Earth Sciences (KeckCAVES, http://www.keckcaves.org), and the W.M. Keck Foundation.

Vrui and all the LidarViewer components are all programmed by Oliver Kreylos, computer scientist at University of California, Davis. Parts of this document are provided by the READMEs and communication with Oliver Kreylos.