How to Process Laser Data

What You Need to Have:

• Laser scan files of the environment, 1 per laser
• Laser scan files of the data you want to process, 1 per laser
• One configuration file for each set of laser files.
• The model which describes the objects to be tracked by the tracker

Here you can find some examples of these files. Each section will contain exact commands for processing this example dataset. All examples assume that your working directory contains the programs you use, and that you maintain the directory structure in the examples archive. For collecting data, please see our Guide to Gathering Laser Data.


What You Need to Know:

1. The config files used in this process must take the following format
   • First line - The number of lasers described in this file
   • Subsequent lines (of a number matching the first line)
     <name> <x> <y> <theta> <color1> <color2> <color3> <filename>
     Where:
     • name = The name of the laser
     • x = The x-coordinate of the laser
     • y = The y-coordinate of the laser
     • theta = The theta orientation of the laser
     • colorN = The colors to be used (are unimportant to this process, but must be present to properly format the file)
     • filename = The filename of the laser scan file, including path (absolute or relative from the java working directory)
2. The x, y, and theta values for each laser location should be all in the same coordinate system, and expressed in centimeters and radians. Theta represents the direction the laser is pointing, or the middle scan. Approximations are sufficient, though if they are very rough, the Register program may have to be run twice.

What You Need to Do:

1. Register each dataset in time
   Purpose: The time register program creates laser scan files that are synchronized in time. The data is arranged into intervals of a set time step.
   
   Syntax: java -jar TimeRegister.jar <config_file> <output_path>
   The config_file is only used to find the laser files. The output_path should be an existing directory. If the specified output_path does not exist or is not specified, it will output the data in the current directory.
   
   Input: This program requires a set of laser scan files and a configuration file describing them.
   
   Output: A laser scan file for each input laser scan file. The format is the same except that the timestamp has been converted into one number instead of two. The output file names are the input file names with "_timeRegistered" appended for clarity. The rows between files with the same line numbers will have the same timestamps. This program also outputs a config file named "timeRegisterOutput.cfg" to be use in the next step.
   
   Example:
   java -jar TimeRegister.jar laserData/environment/init.cfg laserData/environment
   java -jar TimeRegister.jar laserData/nobump/init.cfg laserData/nobump
   
   
   
2. Register each dataset in space
   Purpose: This program aligns the scan files from muliple lasers into one synchronized (polar) coordinate system. This is important because even small errors in our estimates of laser placement can lead to very large divergences in the data from one laser to another. This step is only necessary once per physical laser placement. If the lasers have not been touched, locations can be copied manually into the new config files from the old. This should only be done if one is certain the lasers have not been adjusted (physically) at all.
   
   Syntax: java -jar -Xms256m -Xmx256m Register.jar <config_file> <out_file> <laser_line>
   Reads in config_file to find information about lasers (files & initial guess placement), Gets laser_line^th line (starting with 0 for the first line) from each file, and registers the lasers in space, outputing the exact laser locations in a new config file (out_file). This and the rest of the programs use a lot of memory, so the -Xms256m and -Xmx256m switches provide java with extra memory. You may need to increase this for very large data sets.
   
   Input: This program requires a set of time registered laser scan files and a configuration file describing them.
   
   Output: A config file with updated laser locations.
   
   Example:
   java -jar -Xms256m -Xmx256m Register.jar laserData/nobump/timeRegisterOutput.cfg laserData/nobump/registerOutput.cfg 15
   java -jar -Xms256m -Xmx256m Register.jar laserData/environment/timeRegisterOutput.cfg laserData/environment/registerOutput.cfg 15
   
   
   
3. Get statistical data for background subtraction
   Purpose: The Laser Scan Stats program creates statistics calculated from a baseline scan (the environment files) which can be used to eliminate the "uninteresting" points (i.e. perform background subtraction). This step is only necessary once per environment. Subsequent data sets in the same environment can use previously generated stats files.
   
   Syntax: java -jar -Xms256m -Xmx256m LaserScanStats.jar <config_file> <output_path>
   The config_file is only used to find the laser files. The output_path should be an existing directory. If the specified output_path does not exist or is not specified, it will output the data in the current directory.
   
   Input: This program requires a set of time and space registered laser scan files and a configuration file describing them. These should be the environment files.
   
   Output: A stats file (.stats). Line one contains the averages of all of the scans in the input files. Line two contains the input files' standard deviations. Also a config file to be used in the next program to process the data will be generated.
   
   Example:
   java -jar -Xms256m -Xmx256m LaserScanStats.jar laserData/environment/registerOutput.cfg laserData/environment
   
   
   
4. Subtract the background
   Purpose: The BackgroundSubtractor subtracts the background from laser scan files using the statistics calculated in the previous step. It does this by subtracting any point which is closer than a certain threshold to its statistical average. It also removes warnings and errors from scans (corresponding to laser readings above 8000).
   
   Syntax: java -jar -Xms256m -Xmx256m BackgroundSubtractor.jar <laser_config_file> <stats_config_file> <output_path>
   The output_path should be an existing directory. If the specified output_path does not exist or is not specified, it will output the data in the current directory. Both config files must list the lasers in the same order as each other.
   
   Input: This program requires a set of time and space registered laser scan files and a configuration file describing them. It also requires a set of stats files and a configuration file describing them.
   
   Output: Laser scan files which contain the data from their input laser log files with the "background" points set to -1.
   
   Example:
   java -jar -Xms256m -Xmx256m BackgroundSubtractor.jar laserData/nobump/registerOutput.cfg laserData/environment/laserScanStatsOutput.scfg laserData/nobump
   
   
   
5. Convert to BTF Files
   Purpose: The laser 2 BTF program translates the scan files into the lab's standard BTF format (described here). It essentially converts the data from polar coordinates to cartesian coordinates and combines all the laser data into one set of BTF files.
   
   Syntax: java -jar -Xms256m -Xmx256m Laser2BTF.jar <config_file> <output_dir>
   
   Input: This program requires a set of time and space registered laser scan files and a configuration file describing them. It can convert pre- or post-background subtraction files, depending on your needs.
   
   Output: A BTF directory containing the following files:
   • id.btf
   • type.btf
   • timestamp.btf
   • scanxscale.btf
   • scanyscale.btf
   
   Example:
   java -jar -Xms256m -Xmx256m Laser2BTF.jar laserData/nobump/bgSubOutput.cfg laserData/nobump
   
   
   
6. Collapse the data
   Purpose: The Collapser program collapses the btf to have one line of data per unique timestamp. This serves to combine a given scan across all lasers.
   
   Syntax: java -jar -Xms1024m -Xmx1024m Collapser.jar <input_btf_dir> <output_dir>
   
   Input: This program requires a directory of BTF files containing laser scan data.
   
   Output: The "collapsed" BTF files
   
   Example:
   java -jar -Xms1024m -Xmx1024m Collapser.jar laserData/nobump laserData/nobump/preTrackerBtfs
   
   
   
7. Run the tracker
   Purpose: Creates tracks of the objects by using a model to find the points that correspond to each object.
   
   Syntax: java -jar LaserTracker.jar <input_dir> <model_dir> <output_dir>
   
   Input: This program requires a directory of BTF files containing laser scan data, which have already been "collapsed". It also requires a model of the objects to be tracked.
   
   Output: A BTF directory containing the identified tracks.
   
   Example:
   java -jar LaserTracker.jar laserData/nobump/preTrkerBtfs laserData/nobump/preTrackerBtfs/model laserData/nobump/trackerOutput
   
   
   

Congratulations! You've processed laser data!