Documentation
Quick Start
The best way to learn to use a new program is to be able to try it out. So a quick way to get started is to download and install the command line utility
MRFSurface. Secondly, download some sample data. For example a
3dMD facescan. This is a near-raw output from a clinical 3D scanner. Now create a .bat file in the data directory or execute the following command:
"C:\program files\MRFSurface\MRFSurface.exe" -t 1 -i facescan.txt -o facescan_MRF.vtk
After some minutes, this should create an output file (facescan_MRF.vtk) with a surface. The program can also read and write STL and PLY files (not all PLY files can be read though - blame the VTK PLY reader).
Now use your favourite 3D viewer to inspect the surface. Alternatively, you can install
Sumatra and use it to view and manipulate the surfaces.
The next step is to try with your own data. Check the input format section. Initially, the default parameters can be used and later adapted to your data. By far the most important issue is how point normals can be estimated from the input data. It is actually quite rare, that no normal information exists. Nearly all capture devices can provide some kind of estimate of a point normal.
Point Normals
It is crucial to have consistent point normals over the data set. The
toolkit provides some methods to do this. A PCA based methods can create
local estimates of point normals. The PCA methods will also remove
points considered noise. However, two neighbouring normals can point in
opposite directions due to the nature of the PCA. Therefore a graph
based method that divides the point set into connected components is
also supplied. In each component the normals are forced to have
consistent directions. However, there are still cases where two separate
components in a global sense do not agree on what is inside and what is
outside. It is therefore possible to use approximate normals (for
example from a scanner) in a voting scheme in the connected component
algorithm.
It is possible to supply a camera position (using the -v
argument). The algorithm will then compute normals pointing from each
point toward the camera. This can be useful for testing simple
prototype scanners (with two cameras, a camera and a projector etc). If
you have two cameras and use stereo-reconstruction, try to supply the
average position of the two cameras (see the Skull example).
Pre-defined Input Types
To make it easier to use the program some pre-defined
template types have been defined. They can be specified using the
t option.
| Type |
Description |
| 0: Points |
x,y,z points with no normals |
| 1: Points with approximate normals |
Normals estimated roughly by an acquisition device |
| 2: Points with good normals |
Points can be noise/outliers but still have good normal estimates |
| 3: Mesh |
Mesh with connectivity but no normals |
| 4: Mesh with approximate normals |
Mesh with connectivity and rough estimates of normal directions |
| 5: Mesh with good normalsMesh |
Mesh with connectivity and well defined normals |
As previuosly described, there are a set of methods to reestimate normals and remove noise. They are:
| ID |
Description |
| M1 |
Estimates normals using local PCA. Removes outliers and noise points |
| M2 |
Connected component analysis. Finds
connected groups of good points. Can remove small components, keep the
largest component, or keep them all. Create consistent normal
directions within the separate components. Can not create consistence
between components. |
| M3 |
Connected component analysis using reference
normals. Finds connected groups of good points. Can remove small
components, keep the largest component, or keep them all. Create
consistent normal directions within the separate components. Can not
create consistence between components. Uses reference normals to vote
for the overall component direction |
| M4 |
Create mesh normals using the standard VTK mesh normal generator (vtkPolyDataNormals) |
Based on the supplied input type some default behaviours are defined:
| Type |
Example |
Processing |
| 0 | - | m1, m2 |
| 1 | Many range scanners | m1, m3 |
| 2 | - | (m1), (m3) |
| 3 | Stanford models | m4, (m1), (m3) |
| 4 | - | (m1), m3 |
| 5 | Many 3D models | (m1), (m3) |
Most behaviours can be overridden using the command line arguments. A method in paranthesis means that it is not on by default. Using the combined m1 and m3 can results in large parts of the input points being cropped away.
Input and Output Formats
The program can read data in the following formats:
| VTK |
Visualization Toolkit polydata |
| STL |
Stereolithography files |
| PLY |
Stanford Triangle Format (not all though, vtkPLYReader is to blame) |
| TXT |
Raw 3dMD scanner output |
| CSV |
Comma seperated values (x,y,z), (x,y,z,scalar), (x,y,z,nx,ny,nz), or (x,y,z,nx,ny,nz,scalar) |
| DAT |
Space seperated values (x y z), (x y z scalar), (x y z nx ny nz), or (x y z nx ny nz scalar) |
The program can output data in VTK, STL, or PLY format. The format is automatically determined from the filename extensions.
Options
Command line options for the MRFSurface algorithm. Check the examples section to see how they are used in practise. An overview can also be obtained by:
"C:\program files\MRFSurface\MRFSurface.exe" --help
| Argument |
Type |
Description |
| -a |
on/off |
Pure surface reconstruction (off) or alignment and reconstruction (on) (default off). |
| -i |
string |
(required) input filename. If the software is used to align multiple surface, the input file is a txt file containing the surface names. |
| -o |
string |
(required) output filename |
| -t |
int |
input type (0-5) (default 1) |
| -p |
int |
Prior energy type (0 = Laplacian, 1 = Membrane) (default 0) |
| -b |
double |
Beta - Amount of smoothing (0 max smooth - 1 min smooth) (default 0.9) |
| -s |
int |
Maximum volume size in voxels (default 10000000) |
| -v |
string |
Filename of txt file containing view camera - for normal estimation |
| -n |
int |
Estimate normals and remove noise (0,1) (default based on the input type) |
| -c |
int |
Connected Component Analysis (0,1) (default based on the input type) |
| -l |
on/off |
Keep only largest connected component (default off) |
| -d |
on/off |
Output the data with estimated normals (default off) |
| -f |
on/off |
Output the full (uncropped) surface (default off) |
| -g |
on/off |
Use agressive cropping. If enabled, the parts of the surface that is not supported by input points will be cropped aways. This should be used if the interpolation fails (default off). |
| -m |
int |
Max number of points to use. The algorithm randomly samples the requested number of points before alignment or reconstruction. (Default is -1 meaning all points are used) |
| -N |
int |
Points per normal in normal estimation (Default is -1 meaning that an adaptive neighbourhood size is used, based on input data sampling density) |
| -D |
int |
Points used per distance estimate in a voxel (Default 5) |
| -x |
double |
Triangle size factor (< 1 fewer and larger triangles, 1 > more and smaller triangles) (default 1 meaning that triangles are approximately same size as the voxel side length) |
Other Things
The algorithm starts by estimating the nearest neighbour distance. For each point the distance to the nearest neighbour is calculated and the used distance is the median value of these distances. This value is used in several steps of the algorithm. For example for noise removal and connected component analysis. The most visible influence of the estimated distance is the triangle side-length of the output mesh that should be rather close to this distance.
The algorithm is not designed with sharp edges in mind. It is therefore best suited for
organic objects and less suited for scans of human made objects. A sharp edge will typically be smoothed and the amount of smoothing depends on the voxel size in the last step of the multi-scale solution. Input sample spacing and maximum number of voxels influence the voxel size and therefore the ability to reconstruct sharp edges.