How to Process Data to generate labeled tracks

What You Need to Have:

• Laser scan files of the data you want to process, 1 per laser
• Laser scan files of the calibration data, 1 per laser
• One laser configuration file for each set of laser files

The following examples assume two data sets, game1 and calibration1. The directory structure should be and .\data\game1\laser-raw for the initial data. Some of our data can be found here.


What You Need to Know:

1. The laser 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. It is recommended that the lasers are placed such that all data points remain positive in x and y (for compatibility with Teamview) - the laser range finders have a range of 8000 centimeters.

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. The interval is set currently set for 50ms. If there are two scans that would round to the same time, the second one is used to fill in a potential gap at the next timestamp, or else discarded.
   
   Syntax: java TimeRegister <input_dir> <output_dir>
   
   Input: This program requires a directory of raw laser scan files, one from each laser.
   
   Output: A directory of laser scan files, one for each input laser scan file.
   
   Example:
   java TimeRegister data\calibration1\laser-raw data\calibration1\laser-synchronized
   java TimeRegister data\game1\laser-raw data\game1\laser-synchronized
   
   
   
2. Register each dataset in space
   Purpose: This program aligns the scan files from muliple lasers into one global 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 additional config files. This should only be done if one is certain the lasers have not been adjusted (physically) at all.
   
   Syntax: java -Xmx256m Register <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, based on that line, 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 -Xmx256m switch provide java with extra memory. You may need to increase this for very large data sets.
   
   Input: This program requires a set of laser scan files and a configuration file describing them. It can be run before or after Time Register, but should be run before Background Subtraction.
   
   Output: A config file with updated laser locations.
   
   Example:
   java -Xms256m -Xmx256m Register data\calibration1\calibration1.cfg data\calibration1\calibration1-new.cfg 100
   
   
   
   
3. Update configuration files
   Purpose: Update the x, y and theta values in the configuration files based on the output from Register (above). This can be accomplished by replacing the old config file with the new one (for example, rename calibration1-new.cfg to calibration1.cfg after deleting the original calibration1.cfg). For additional datasets, merely edit the other config files to reflect the updated x, y and theta values for each laser (for example, edit game1.cfg to reflect the values (but not the file names) in calibration1-new.cfg).
   
   
   
   
4. Subtract the background - Part 1 (Background Subtractor)
   Purpose: The Background Subtractor subtracts the background from laser scan files. It does this by eliminating, for each scan angle of each laser, any data point at or farther away than distance band in which many points fall.
   
   Syntax: java -Xmx256m ???? <input_dir> <output_dir>
   
   Input: This program requires a set of raw laser scan files (can be space and/or time registered).
   
   Output: Laser scan files which contain the data from their input laser log files with the "background" points set to -1.
   
   Example:
   java -Xmx256m LaserBackgroundSubtract 25 data\calibration1\laser-synchronized data\calibration1\laser-BGSub
   java -Xmx256m LaserBackgroundSubtract 25 data\game1\laser-synchronized data\game1\laser-BGSub
   
   
   
5. Adjust config files
   Purpose: The configuration files (for example, game1.cfg and calibration.cfg) must be updated to point to the background subtracted laser scan files. This can be done by changing the path in each file (for example, from laser-raw to laser-BGSub in game1.cfg, and likewise for calibration1.cfg)
   
   
   
6. Convert to BTF Files
   Purpose: The Laser2BTF 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 -Xmx256m Laser2BTF <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 (contains the the number of the laser from which this data came)
   • type.btf (currently, always reads 'laser')
   • timestamp.btf
   • scanxscale.btf
   • scanyscale.btf
   
   Example:
   java -Xmx256m Laser2BTF data\calibration1\calibration1.cfg data\calibration1\laser-btf
   java -Xmx256m Laser2BTF data\game1\game1.cfg data\game1\laser-btf
   
   
   
7. Subtract the background - Part 2 (Out of Bounds Subtractor)
   Purpose: This program removes all data points which are outside the given bounds.
   
   Syntax: java -Xmx256m OutOfBounds <input_BTF_dir> <output_dir> <min_x> <max-x> <min-y> <max-y>
   
   Input: This program requires a directory of laser BTF files (must contain scanxscale.btf and scanyscale.btf).
   
   Output: New scanxscale.btf and scanyscale.btf, without the removed points.
   
   Example:
   java -Xmx256m OutOfBounds data\calibration1\laser-btf data\calibration1\laser-btf-outofbounds
   java -Xmx256m OutOfBounds data\game1\laser-btf data\game1\laser-btf-outofbounds
   
   
   
8. Run the tracker
   Purpose: Creates tracks of the objects by finding clusters of data points.
   
   Syntax: java -Xmx256m laser.blobdetect.BlobLaserTracker <input_dir> <model_dir> <output_dir>
   
   Input: This program requires a directory of BTF files containing laser scan data.
   
   Output: A BTF directory containing the tracks.
   
   Example:
   java laser.blobdetect.BlobLaserTracker data\calibration1\laser-btf-outofbounds data\calibration1\laser-btf-tracked
   java laser.blobdetect.BlobLaserTracker data\game1\laser-btf-outofbounds data\game1\laser-btf-tracked

Congratulations! You've generated tracks from the laser data!