3dpalign requires as input three types of files: range image data point files (*.range), calibration data files (*.params), and a master file (*.3dp).

Each range image is described by one .range file and one .params file, and an entry in the .3dp file. When invoking 3dpalign, you pass it the name of the master (.3dp) file. The master file should contain the names of all the range images in the set, one name per line. Then, for each range image name, 3dpalign looks for a file with that name plus the suffix ".range", and a file with that name plus the suffix ".params", and loads the range image from those two files.

For example, if you have three range images called "box1", "box2" and "box3", then your master file should look like this:

   box1
   box2
   box3

Furthermore, you should have files called "box1.range", "box1.params", "box2.range", "box2.params", "box3.range", and "box3.params".

General format

Blank lines-- lines with no non-whitespace characters-- are ignored. Furthermore, lines in which the first non-whitespace character is the pound sign (#) are treated as comment lines and ignored. However, comments that begin in the middle of a line are not allowed.

The first two fields are interpreted as height and width, respectively. These should be integer values. The following height*width non-blank, non-comment lines in the file are interpreted as points, one point per line. Lines are read one at a time, and the matrix of points is filled in first across the top row (y=0, x=0..width-1), then across the next row (y=1), and so forth.

Point format

Each line of the file should be of the following format:

xcor ycor zcor [conf [xnorm ynorm znorm [normconf [red green blue]]]]

The coordinate vector should consist of floating-point numbers. Confidence values should be floating point numbers between 0.0 and 1.0. The norm vector should consist of floating point numbers, and is automatically normalized when read in. The color value is currently ignored. Any nonspecified confidence values are set to 1.0 (if the point is reasonable) or 0.0 (if the point is greater than 10^10 units away). If the norm is not specified, norms are automatically computed based on neighboring points.

The first line is treated as the "format defining line". All subsequent lines are expected to contain the same number of fields. If there is a mismatch while reading the .range file, an error will be signaled and the program will abort.

General format

Blank lines, and lines in which the first non-whitespace character is the pound sign are ignored.

The first field encountered is interpreted as a parameter name. The next several tokens are then interpreted as values for that parameter. There may be anywhere between one and sixteen values, depending on the parameter, separated by any kind of white space (including newlines). Once all the values have been read in, the next token encountered is interpreted as the next parameter.

Recognized parameters

Parameter description	File content
Scale normalization factor	src value
Translation normalization vector Sets the center of mass to the origin	trc xvalue yvalue zvalue
Rigid body motion from camera to projector Translation vector: tcp Rotation matrix (row-wise): rcp	tcp xvalue yvalue zvalue rcp value1 value2 value3 value4 value5 value6 value7 value8 value9
Intrinsic camera parameters Radial distortion factor: kcam Camera focal lengths: fxcam, fycam Camera optical center: cxcam cycam	kcam value fxcam value fycam value cxcam value cycam value
Intrinsic projector parameters Projector focal length: fxprj, fyprj Projector optical center: cxprj, cyprj	fxprj value fyprj value cxprj value cyprj value
Origin of area of interest in the (xpimg,ycimg) grid	rngx0 integer rngy0 integer

These parameters must be present and must be accurate, as 3dpalign uses them in the process of calculating refined global alignments.

3dpalign generates output by adding an malign (pronounced "em-align") parameter to the .params file of each range image, replacing any existing malign. This matrix is a 4x4 matrix (16 values) stored row-wise, and contains the rigid-body transform (rotation and translation) necessary to transform this range image into the global coordinate frame.

3dpalign also generates a private file whose name is the name of the master file, plus ".dat". For example, if your master file is called "metronome.3dp", 3dpalign will generate a private file called "metronome.3dp.dat". This file contains information such as your current set of feature correspondences and your current view transforms. You should not attempt to edit this file. If you delete it, you will lose all the feature correspondences you have identified, and all the view transforms will revert to default.

To invoke 3dpalign, use:

3dpalign [-v] 3dpfile.3dp

Specify the name of your master .3dp file. The -v flag turns on verbose output, but this is typically only useful for debugging purposes.