MURI Surface Reconstruction Project
Browser applet Documentation

Romanian translation courtesy of Science Spaces

General

The purpose of this document is to describe the usage and options of the programs for reconstruction and comparison of surfaces from terrain-like point cloud data. The programs can be downloaded from Here.

Workflow

Generally, processing of the point cloud data is done in the following order, where not all of these steps are necessary or sensible for all input data:

 

.         Format conversion

.         Pre-processing

.         Surface reconstruction

.         Post-processing

.         Viewing

Programs

WizardGUI

This program will take you through all of the stages of surface reconstruction and comparison within a graphical interface. Complete documentation on how to use the wizard is found Here.

Format conversion

StmToPts

This program converts a '.stm' file to a '.pts' file. The program takes command line arguments in the form :

stmtopts <height map file> [scale]

First, the height map file in the '.stm' format must be given, and optionally the scale can be given. The '.stm' file specifies the height at each cell in a 2D grid as a 16 bit integer, and those values are divided by the scale. Each cell in the grid is considered to be one unit on a side.

IhmToPts

This program converts a '.ihm' file to a '.pts' file. The program takes command line arguments in the form :

ihmtopts <ihm file> [scale]

Like the StmToPts conversion, the scale can be given optionally.

XyzToPts

Each point in the '.xyz' file is converted to a point in the '.pts' file. The normal at each point is undefined. The output file will have the same name as the input file, except that the extension '.pre' is added. A '.pre' file is the same as a '.pts' file, but is named differently for workflow convenience. The usage follows:

xyztopts <xyz file>

XyzToPtsView

Each point in the '.xyz' file is converted to a point in the '.pts' file. The normal at each point is set to point at the camera position specified by the index into the trajectory file. The trajectory file must have the same file name and coordinate system as the '.xyz' file. The filename must be given without the extension. The usage follows:

xyztoptsveiw <xyz file without extension>

 

Pre-processing

FixBBoxShared

Any number of input data sets are given, and the bounding box of all data sets will be set to the bounding box of the union of the points from the sets. The input files are overwritten. Usage is as follows:

Fixbboxshared [.pts [.pts [...]]]

SortPoints

This program performs and out-of-core merge sort of a pts file along the z axis. If the longest axis is not the z axis, the model will be rotated so that the longest axis is the z axis. Nothing fancy is done, just 90 degree rotations. To use the program, supply an input file as an argument, and optionally give an output file name as a second argument. If no output file name is specified, the input file will be overwritten. The usage follows:

sortpoints <infile> [outfile]

CalcNorms

This program calculates approximate normals for '.pts' and '.pre' files that were created without trajectory information. This is done by dividing the scanned volume into a grid assuming that the scene is of a terrain. Namely, that there is sky above and ground below the scanned data. Space that lies below an overhang could potentially be either air or dirt. All known areas propagate their values of filled or unfilled into all undetermined neighbors that do not contain points until all areas have been determined to be either filled or unfilled.

If an area is filled it is given a value of 1, if it is empty, it is given a value of -1, and if it contains points, it is given a value of 0. The gradient of this function coarsly approximates the normals of the points. The normal of each point is set to a best-fit plane through the local neighborhood of points, and the direction of the plane's normal (in or out) is determined from the gradient of the inside-outside function.

Usage follows:

Parameters can be passed to the command line by first

giving the name of the parameter to modify followed

by its value.

 

pts [.pre]

res [integer]

res_x [integer]

res_y [integer]

res_z [integer]

fillgaps (t|f)

 

.         Pts - specifies the input point file to use

.         Res - the grid resolution in the x,y,z directions

.         Res_x - the grid resolution in the x direction

.         Res_y - the grid resolution in the y direction

.         Res_z - the grid resolution in the z direction

.         Fillgaps - when set to true, points are added in x,y coordinates where there are no input data.

CalcNormsView

This program calculates approximate normals for '.pts' and '.pre' files that were created with trajectory information. The trajectory information simply tells the location that each point was scanned from. The normal of each point is set to a best-fit plane through the local neighborhood of points, and the direction of the plane's normal (in or out) is determined from the direction towards the camera. The point cannot have been scanned from inside of an object, so the plane's normal must point in the direction of the camera.

Parameters can be passed to the command line by first

giving the name of the parameter to modify followed

by its value.

 

pts [.pre]

res [integer]

res_x [integer]

res_y [integer]

res_z [integer]

fillgaps (t|f)

extend_avg (t|f)

floodfill (t|f)

thin_struct (t|f)

 

.         Pts - specifies the input point file to use

.         Res - the grid resolution in the x,y,z directions

.         Res_x - the grid resolution in the x direction

.         Res_y - the grid resolution in the y direction

.         Res_z - the grid resolution in the z direction

.         Fillgaps - when set to true, points are added in x,y coordinates where there are no input data.

.         Extended_avg - when fillgaps is true, then the points that are added for the ground are added at a height that is equal to the average heights of the surrounding points.

.         Floodfill - a different method of determining what parts of the terrain are inside or outside that is rarely better than the default method.

.         Thin_struct - thin structures such as fences and power lines are thickened in an attempt to preserve fine details that are often lost during surface reconstruction.

 

FilterPoints

Points that are not near other points or whose normals are very different from the surrounding points are removed from a data set. The input file must have the points in sorted order, because the program runs out-of-core. The filtered output file has the same name as the input file, except that the '.filter' extension is added. Usage is as follows:

Parameters can be passed to the command line by first

giving the name of the parameter to modify followed

by its value.

 

pts [.pts]

depth [integer]

marks [integer]

dist_dev [float]

angle_dev [float]

 

.         Pts - the sorted input data set

.         Depth - the resolution of the underlying grid that calculations are performed on is 2dx2dx2d cells on a side, where d is the depth.

.         Marks - for each neighboring cell that has no points, a mark is given. A mark is also given for every cell that is greater than the allowed deviation in distance from the plane or difference in normal to the plane that fits the local neighborhood of points. The marks parameter sets the maximum number of marks a point can get before it is removed.

.         Dist_dev - if the point is greater than this specified deviation in distance from the locally fitted plane relative to the other points in the neighborhood, the point gets a mark.

.         Angle_dev - if the point is greater than this specified deviation in normal from the normal of the locally fitted plane, the point gets a mark.

FilterOutliers

Parameters can be passed to the command line by first

giving the name of the parameter to modify followed

by its value.

 

pts [.pre]

res [integer]

res_x [integer]

res_y [integer]

res_z [integer]

ratio [float]

 

.         Pts - specifies the input point file to use

.         Res - the grid resolution in the x,y,z directions

.         Res_x - the grid resolution in the x direction

.         Res_y - the grid resolution in the y direction

.         Res_z - the grid resolution in the z direction

.         Ratio - if the point density near a point is below the ratio times the average density, then the point is removed.

LOP - Locally Optimal Projection

This program performs as a pre-processing of the WaveletPipeRecon. It uses the Locally Optimal
Projection operator[1] to project noisy points as a noise filtering, and adjust the point distribution
of the scanned point cloud. The program uses an Octree-based implementation as an optimization to
minimize the run-time cost of the original algorithm.

Reference of the LOP: [1] Lipman, Y., Cohen-Or, D., Levin, D., and Tal-Ezer,
H. 2007. Parameterization-free projection for geometry
reconstruction. ACM Trans. Graph. 26, 3 (Jul. 2007), 22.


Parameters can be passed to the command line by first giving the name
of the parameter to modify followed by its value.

pts [.pts]
pts2 [.pts]
mu [float]
h [float]
k [int]
r [float]


.         pts - the original input data set.

.         pts2 - an arbitrary data set, which will be sampled accoridng to the sample rate to generate a guess set to be projected onto the original input data set.

.         mu - a repulsion parameter whose range is [0, 1/2), please see[1] for detail.

.         h - the support radius of the gaussian weight function used by [1].

.         k - the number of iterations of the fix point algorithm for computing the projection.

.         r - the sample rate for sampling from the arbitrary set to generate the guess set.

SurfFitFill

The program performs as a separate procedure for filling more points to an input data set.
It first divides the data set into cells according to the user-provided resolution, then fits the points in
each cell to a plane, and adds more points onto the plane. This program turns out to be very useful for estimating
the missed detail of a input data set due to a sparse scan, such as the underpass dataset.

The following external libraries are needed in order to compile the
code:

1. BLAS
2. LAPACK
3. FLENS (A C++ interface to BLAS and LAPACK)

We recommend to compile the code under Linux based system to
ease the installation of the required libraries above.

Parameters can be passed to the command line by first giving the name
of the parameter to modify followed by its value.

pts [.pre]
res [integer]
res_x [integer]
res_y [integer]
res_z [integer]


.         pts - specifies the input point file to use

.         res - the grid resolution in the x,y,z directions

.         res_x - the grid resolution in the x direction

.         res_y - the grid resolution in the y direction

.         res_z - the grid resolution in the z direction

Surface reconstruction

WaveletPipeRecon

For how to use the program, please refer to the documentation at: http://people.cs.tamu.edu/jmanson/programs_wavelet_reconstruct.html

For source code documentation, please refer to the documentation Here

Daub3DCompare

This program performs surface reconstruction on two input data sets using the Daubechies 4 wavelet basis. The symmetric difference between the reconstructed indicator functions can be calculated, or the surfaces can be reconstructed from each data set only at the intersection of the data sets. The usage of this program is similar to that of WaveletPipeRecon. Usage is as follows:

Parameters can be passed to the command line by first

giving the name of the parameter to modify followed

by its value.

pts1 [.pts]

pts2 [.pts]

depth [N]

to_screen (t|f)

to_file (t|f)

blur (t|f)

surf_at_pts (t|f)

surf_at_int (t|f)

shared_pts (t|f)

cmp_thresh (t|f)

cfg [config_file]

Only the options that are different than the options in WaveletPipeRecon are described here:

.         Surf_at_int - when set to true, the surface is only extracted at x,y locations that have points from both input data sets.

.         Shared_pts - when set to true, only points that share the same x,y location in both input data sets are used to perform the reconstructions.

.         Cmp_thresh - when set to true, the symmetric difference between indicator functions is performed by taking the symmetric difference of thresholded indicator functions, where thresholding means setting the function values to either 0 or 1.

Post-processing

SurfDistColor

The distances between the surfaces are computed at each vertex. This distance information is then used later to color the surfaces to highlight areas where the surfaces do not coincide.

Viewing

ViewDists

This program is used to view the results from SurfDistColor to spot tanks.

ViewPts

This program views '.pts' files.

ViewXYZ

This program views '.xyz' files.

3dViewer

This program views various surface formats, including '.bobj'.

File formats

.pts

The surface reconstruction programs accept input in the .pts file format. This binary format is a simple description of a set of points in three-dimensional space with assigned unit outward normal vectors. It consists of a header, that has two 3D vectors that describe the maximal and minimal extents of the scenery, followed by an integer containing the number of points in the data file. Following the header is a list of points, where each point consists of a normal and a position that are represented as 3D vectors. Pseudo-C code describing the format follows:

 

struct xyz

{

float x, y, z;

};

 

struct bbox

{

xyz min_corner, max_corner;

};

 

struct header

{

bbox bounds;

int number_of_points;

};

 

struct point

{

xyz normal, position;

};

 

struct pts_file

{

header head;

point points[];

};

.stm

STM files are heightmaps that specify one height value for each point in a regular rectangular 2D grid. A more detailed description of this format is available on the MURI website under ``formats".

.ihm

An .ihm file is a simple terrain map (.stm file) with extended IMI footer. The footer is optional, and are denoted by '#' without the quotes. The hash marks the rest of the current line as comment,
which needs to be skipped during the interpretation (i.e. conversion). A more detailed description of this format is available here .

.xyz

XYZ files are ASCII files that contain the xyz coordinates and return signal strength of the points, one point per line.

.xyzrgba, .traj

XYZRGBA format is similar to XYZ, with the difference that each line is preceeded by an integer number. These indices refer to a file with suffix .traj, which for each index contains an xyz position of the sensor location from which the points with that index were recorded. This sensor location is frequently useful in determining the orientation of the surface normal to a point (it should always point within 90 degrees of the direction of the camera). As the name suggests, XYZRGBA files additionally specify an RGBA color of the scanned surface at each point. RGBA is a representation of color that specifies the red, green, and blue components and the opacity of the surface.



Browser applet Documentation


General

This is the online documentation of the Jviewer applet, and the GUI to use it, that views point cloud data from a browser environment. This GUI can be used to process your point cloud data without installation or compilation of the program and its dependencies on your computer. The only necessary component for you as the user is an updated installation of Java for your operating system. If you do not have this, you should be prompted to install it. If you are not please visit http://www.java.com and install the latest version for your operating system.

Workflow

Generally, the process for viewing point cloud data via the applet is as follows: Some sections are the same as described above and will not be repeated here

GUI

The Graphical User Interface, and the beginning of the process is located here the purpose of the GUI is the same as the WizardGUI program described above. It Allows the user to specify all the options they would like to employ while running the script to generate their visualized data.
For the specifics on the GUI please follow this link: GUI specifics

Program

The only new program (in addition to those discussed above) is the Jviewer applet. The applet JAR is called along with a single parameter to function:

file - the name of the point cloud filed uploaded (ex. african_statue.pts)

Jviewer

This program is the java applet that translates the point cloud into Java 3D and visualizes it in a window.

File Upload

Following the input of options in the GUI a point cloud file of the specified type is uploaded. This is done directly below the GUI itself. The current file upload maximum size limit is 10MB as stated in the GUI.

Format Conversion

This is described above and the same programs are used when necessary.

Pre-processing

This is described above and the same programs are used when necessary.

Surface Reconstruction

This is described above and the same programs are used when necessary.

Viewing

This is accomplished through the Jviewer program which accomplishes the same task as the 3dViewer described above through a browser window.

Private files

coeff_filtering.pdf

minimization.pdf

New data (june 2009) on pdf

References

1.       Josiah Manson, Guergana Petrova, Scott Schaefer. "Streaming Surface Reconstruction Using Wavelets." Symposium on Geometry Processing 2008. <http://students.cs.tamu.edu/jmanson/wavelet_reconstruct.pdf>.