Standard data files format for alignment and volumetric integration

After acquiring multiple views of your object, you need (from matlab) to save all the data in the format that will allow you to use the provided alignment tool.

For a given view viewname, one needs to:

The extensions .range and .params are compulsory. We also HIGHLY RECOMMEND to name your different views in a consistant way, using as a basis the name of the object you are scanning followed by a number identifying the view index.
An example would be statue1.range, statue1.params for the first view, statue2.range, statue2.params for the second view, ...

Once those files are created, save the names of the views (without extension) into a final file statue.3dp:


The alignment tool 3dpalign will take tat file name statue.3dp as only argument, and will let you align all the views (look at the page describing the 3dpalign tool).

Let us now look in details at the .range and .params files content: let's say that we are working on the 13th view of the statue. The two files we have to generate are statue13.range and statue13.params.

Description of the statue13.range file

This file basically contains the ordered list of 3D coordinates of the points. Each point is stored in a matrix where the row index corresponds to the row position in the image plane (ycimg), and the column index corresponds to the projector coorinate (xpimg). Notice that this is possible since both quantities are integer (up to 0.5 for xpimg... do you remember why?). Once this arrangment is done, you obtain 3 matrices of Nrow rows and Ncol columns for each coordinate X, Y and Z.

The first row of that matrix will correspond to pixel row rngy0 in the original image, and the first column will correspond to pixel column rngx0 (both quantities will most likely be larger than 0, since the region of interest covered by the object does not generally occupy the complete range of values for the {xpimg,ycimg} coordinates).

The format of the file stature13.range:

File content
1st line: Nrow Ncol
The subsequent Nrow x Ncol lines: Xr Yr Zr [ C [ nx xny ny [ Cn [ color, other info]]]]

where Xrange = [Xr,Yr,Zr] is the 3D range coordinates vector of a generic point after normalization. Notice that all the points are ordered row-wise, meaning that we first list all the points of the first row (from left to right) before moving to the second row (look at the example file). If a point does not exist, assign to it Xr=Yr=0 and Zr=-1e308 (Note that the [ and ] signs only symbolize the optionality aspects of some of the parameters. They should not appear in the file itself (only spaces between two consecutive values).

Those normalized coordinates are computed from the coordinates in the camera frame (Xcam = [Xc,Yc,Zc]) after subtraction of a 3D translation vector trc and scaled by a scalar coefficient src. In other words, we have:

Xr = (Xc - trc(1))/src;
Yr = (Yc - trc(2))/src;
Zr = (Zc - trc(3))/src;

The two parameters trc and src can be chosen such that the center of mass of the cloud of points is located at the origin, and the maximum absolute value of the coordinates is "roughly" 1 (across the values Xr, Yr and Zr for all the points on the view).

VERY IMPORTANT: THE SCALE FACTOR scr HAS TO BE IDENTICAL FOR ALL THE VIEWS!!! One can compute src based on the points of the first view (statue1), and then used the same scale value for the all the subsequent views (statue2, statue3, ...). An alternative is to pick scr=1 for all views, and drop the coordinate normalization step all together (like in the example file). We recommend to choose that second alternative. This will prevent you from making mistakes. On the other hand, the normalizing translation vector trc does not need to be identical across views (it is recommended to set it so that the center of mass of the points is at the origin).

Those parameters will later be part of the parameter file statue13.params.

Notice that trc and src are in centimeters (like Xcam), however Xrange is unitless (if normalized by a non unitary scale src is applied).

Optionnally, one may also want to add to the 3D coordinates {Xr,Yr,Zr} some extra information on the points. You can successively add to each points:

We recommend to start with the minimal file format (the 3D coordinates only). That will prevent your files from being too large, and still allow you to perform the alignment task. Using that format, your file should look like:

236 246
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
1.39352 -8.28044 6.95516
1.45983 -8.27747 6.90222
1.5566 -8.27831 6.91911
1.62074 -8.27508 6.86122
1.70058 -8.2738 6.83921
1.74504 -8.26812 6.73656
1.83091 -8.2676 6.72831
1.89218 -8.26402 6.66409
1.97433 -8.26304 6.64729
2.04026 -8.26004 6.59374
2.10941 -8.25745 6.5475
2.16048 -8.25264 6.46056
2.23697 -8.25096 6.43098
2.37471 -8.25681 6.53888
2.52952 -8.26472 6.68453
2.6481 -8.26817 6.74846
3.01202 -8.30162 7.35992
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
0 0 -1e+308
5.37078 -8.48754 10.7455
5.42981 -8.48334 10.6689
5.49309 -8.47965 10.6017
5.53959 -8.47396 10.498
5.6085 -8.47097 10.4434

Notice that we picked here src=1 (this is why the coordinates are not within -1 and 1). You don't have to do that, however, it is recommended.

We will in the future exploit the full potential given by the extra available information (especially confidence numbers, and surface normals).

Description of the statue13.params file

This file contains a list of paramters used by the alignment tool, and later on used for building the volumetric model of the object. This file gives the various parameters needed to transform between different coordinate frames and to get texture coordinates for a view.

The format of the file statue13.params (this is just an example here, the numerical values should be yours of course):

Parameter description File content
Scale normalization factor (src)
Needs to be there even if equal to 1
src 1.00000000
Translation normalization vector(trc)
Sets the center of mass to the origin
trc -4.65601512 -1.59718542 172.60735398
Rigid body motion from camera to projector
Translation vector: T (tcp)
Rotation matrix: R (rcp)
Entries of R (rcp) are stored row-wise

tcp 76.80637107 -17.74639690 -35.14276573
0.88839168 0.09715148 -0.44868898
-0.02649762 0.98657392 0.16115139
0.45832095 -0.13127636 0.87903835
Intrinsic camera parameters
Radial distortion factor: kc (kcam)
Camera focal lengths: fc (fxcam,fycam)
Camera optical center: cc (cxcam,cycam)
kcam -0.44153276
fxcam 2689.85483872
fycam 2539.68919704
cxcam 319.50000000
cycam 239.50000000
Intrinsic projector parameters
Projector focal length: fp (fxprj,fyprj)
Projector optical center: cp (cxprj,cyprj)
fxprj 1495.21893057
fyprj 1208.35520126
cxprj 319.00000000
cyprj 239.50000000
Origin of area of interest
in the (xpimg,ycimg) grid: (rngx0,rngy0)
rngx0 128
rngy0 88

Note that you can also add comments with the pound sign (#). In that case, everything up to the end of line is comment. A parameter file could very well look like this:

# Scale and translation from range date to camera frame (cm)
src 1.00000000
trc -4.65601512 -1.59718542 172.60735398

# Rigid body motion from camera to projector
tcp 76.80637107 -17.74639690 -35.14276573
0.88839168 0.09715148 -0.44868898
-0.02649762 0.98657392 0.16115139
0.45832095 -0.13127636 0.87903835

# Intrinsic camera parameters
kcam -0.44153276
fxcam 2689.85483872
fycam 2539.68919704
cxcam 319.50000000
cycam 239.50000000

# Intrinsic projector parameters
fxprj 1495.21893057
fyprj 1208.35520126
cxprj 319.00000000
cyprj 239.50000000

# Origin of area of interest in the (xpimg,ycimg) grid
rngx0 128
rngy0 88

The alignement process will add to the file an additional parameter malign consisting of a 4x4 matrix describing the rigid motion bringing the range data coordinates to a common reference frame for all views. This reference frame will be next used for the volumetric representation (for voxels). Notice that malign will embed rotation R_align and translation T_align:

malign =
R_align T_align
[0 0 0]

The two following tables give a complete description of all the variables/parameters introduced here.

Global notations:

Xvol 3D coordinates in common coordinate
frame (after alignment) - voxels
Xcam = [Xc,Yc,Zc] 3D coordinates in camera frame
(of each individual view) - centimeters
Xrange = [Xr,Yr,Zr] 3D coordinates in .range file.
all components are between -1..1 - voxels
xc, yc 2D coordinates on camera focal plane
(at z=1:after perspective division) - unitless
Xprj = [Xp,Yp,Zp] 3D coordinates in projector frame
(of each individual view) - centimeters
xcimg, ycimg Coordinates in camera image;
between 0..639,0..479 - pixels
xpimg, ypimg Coordinates in projector pattern;
between 0..639,0..479 - pixels
xrng, yrng Integer indices in RANGE grid - pixels
xtex, ytex Inventor texture map coords in camera image (must be 0..1)


Descriptions Mathematical relations
After alignment:
From range coordinates
to commom reference frame
(malign is guaranteed to have only
rotation/translation components)
[Xvol,1] = malign * [Xrange,1]
Xvol = R_align * Xrange + T_align
Scale/Translation from range
coordinates to camera coordinates
Xcam = src * Xrange + trc
Camera perspective projection xc = Xc / Zc
yc = Yc / Zc
Conversion to image pixel coordinates xcimg = cxcam + fxcam*xc*(1+kcam*(xc^2+yc^2))
ycimg = cycam + fycam*yc*(1+kcam*(xc^2+yc^2))
Rigid body motion between camera and projector frames
(in old notations, rcp=R and tcp=T)
Xprj = rcp * Xcam + tcp
Projector perspective projection
(in pixel)
xpimg = cxprj + fxprj * Xp / Zp
ypimg = cyprj + fyprj * Yp / Zp
The column/row indices in
the RANGE grid.
xrng = xpimg - rngx0
yrng = ycimg - rngy0
Texture coordinates xtex = xcimg/639
ytex = 1 - ycimg/479

We recall that all coordinate frames have X going to the right, Y going down, Z going into the image.