3dpalign user's manual
Daniel Azuma (dazuma@kagi.com)
Multi-Res Modeling Group
3dpalign files
  1. Introduction
  2. 3dpalign files <=
  3. Using 3dpalign
  4. Tips and techniques
  5. Appendices


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:


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

The .range file

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.

The .params file

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.

Daniel Azuma (dazuma@kagi.com)
Last updated 29 August 1997