|
Vision and Mobile Robotics Laboratory | Software
|
|
| Home | Members | Projects | Publications | Software | Videos | Internal |
SpinRecognize is a program for aligning surface meshes when the transformation that aligns the views is completely unknown. SpinRecognize takes as input two surface meshes and ouputs the rigid transformation that aligns them. The registration procedure is based on matching spin-images. The theory behind this program is presented in the Ph.D. dissertation Spin-Images: A Representation for 3-D Surface Matching and the papers Surface Registration by Matching Oriented Points appearing in 3DIM '97 and Object Recognition by Matching Oriented Points appearing in CVPR '97.
SpinRecognize is input a scene and model surface meshes. By matching points with uncompressed spin-images, SpinRecognize aligns the model with the scene. The transformation(s) that transforms the model to the scene is printed to standard output and a 3-D viewer will pop up displaying the alignment of the surfaces; the model will be displayed in red wireframe and the scene will be displayed as white shaded. If no alignment is found, then the viewer will be empty. The best transformation is chosen as the one that produces the greatest number of correspondences between the model and scene. Through command line options, alignment parameters and display options can be set.
SpinRecognize uses surface normals to align surfaces; normals for surfaces being aligned must be oriented in the same direction. Having normals oriented in the opposite directions is a common mistake when using SpinRecognize. By default the normals on a surface mesh are oriented to point away from the centroid of the mesh. Sometimes this is not the desired behavior, especially when a data set comes from a single range view of a scene. Command line options (detailed below) can be used to orient normals so that they always point toward the sensor origin. The program ShowNormals can be used to display the surface normals generated for a surface mesh.
main.c main control function that reads in surface meshes and parameters from command line and outputs and displays the aligned surface meshes.
analyze.c contains the code for analyzing the recognition process. This includes creation of matching histograms and outputing spin-images.
analysisState.h contains the analysisState class which stores relevant state information (running times, number of correspondences, best transformation,...)
By typing 'SpinRecognize -' the following options (format description default) are printed:
Usage: SpinRecognize (see SpinRecognize.html for more details)
%S set scene mesh filename [required]
%S set model mesh filename [required]
-genStack %F %d %d %F set spin-image generation parameters
[bin size=1,width=15,height=15,angle threshold=180]
-readStack %S name of file for writing model stack [off]
-writeStack %S name of file for reading model stack [off]
-sOrig %F %F %F sensor origin [off]
-mOrig %F %F %F sensor origin [off]
-selectF %F percentage of scene points to search for [0.50]
-seed %d set random number seed [1]
-flatT %F filter possible scene points on flatness error [off]
-simT %F filter correspondences on similarity measure [0.5]
-gcT %F geometric consistency threshold [0.25]
-icpT %F verification threshold[2*model resolution]
-noDisplay do not open graphics display [off]
-showNormals display normals [off]
-showMatches display matched points [off]
-nm %d number of matches to display [1]
-saveResult %S name of file to save display in [off]
-writeTrans %S file to store transformation in [off]
-spinMethod %d
-abBounds %F %F %F %F bounds on alpha,beta
-restrict %F %F %F %F %F %F %F %F %F %F %F %F rough limits on the transformation between views
-hashed hashed
-gridSize %F grid size
%S set scene mesh filename [required]
The scene surface mesh filname. This parameter is required.
%S set model mesh filename [required]
The model surface mesh filename. This parameter is required.
-genStack %F %d %d %F set spin-image generation parameters
[bin size=1,width=15,height=15,angle threshold=180]
This option specifies the model spin-image generation parameters. Bin size is set as a multiple of the model resolution. Width is the width of the spin-image in pixels (alpha direction). Height is the height of the spin-image in pixels (beta direction). Spin-images generated will have height/2 pixels above beta = 0 and height/2 pixels below beta = 0. Angle threshold is the threshold on the angle (in degrees) between the oriented point basis and the surface normals of points being accumulated in the spin-image. Detailed analysis of these parameters is given in Chapters 2 and 9 of the Ph.D. dissertation Spin-Images: A Representation for 3-D Surface Matching.
-readStack %S name of file for writing model stack [off]
This option indicates that the model stack should be read from the file given.
-writeStack %S name of file for reading model stack [off]
This option indicates that the generated model stack should be written out to the file given.
-sOrig %F %F %F sensor origin [off]
This option specifies the sensor origin (x,y,z) for the scene data. If provided, the surface normals generated for the surface mesh will be forced to point toward the sensor origin. Since adjacent surface normals must be consistently oriented, some of the surface normals near the mesh borders may point away from the sensor origin. If this option is not provided, then the sensor origin is assumed to be the centroid of the surface mesh vertices.
-mOrig %F %F %F sensor origin [off]
This option is the same as the previous option except it is applied to the model surface mesh.
-selectF %F percentage of scene points to search for [0.50]
This option indicates the percentage of scene points to select from the scene. If it is set to 1.0 then all scene points that do not lie on mesh boundaries will be used in the matching process. If it is set to 0.0, then no points will be used.
-seed %d set random number seed [1]
This option defines the random number generation seed. Change this option each time a new random selection of scene points is desired.
-flatT %F filter possible scene points on flatness error [off]
Supplying this option will engage prefiltering of the scene points selected based on error residual in surface normal computation. When not engaged, any scene point can be selected for matching. When set to 0.5 then the half of the scene points with the larger residuals will not be selected from the scene
-simT %F filter correspondences on similarity measure [0.5]
This option controls the number of correspondences kept once all of the scene points have been matched to model points. When set to 0.5, all correspondences with similarity measure less than 0.5 times the maximum similarity measure of all correspondences are eliminated. This parameter must be between 0 and 1.
-gcT %F geometric consistency threshold [0.25]
This option controls the grouping of correspondences for computation os plausible transformations. It should generally be set between 0 and 1.
-icpT %F verification threshold[2*model resolution]
This parameter controls the Iterative Closest Point Verification search threshold. It is set as a function of model resolution. For example, when set to 1.5, the ICPV search distance is 1.5 times the model mesh resolution. This parameter should take values between 0 and 4. Setting this parameter to 0 turns off the matching verification.
-noDisplay do not open graphics display [off]
Use this flag to turn off the graphics display of the result when running in batch mode.
-showNormals display normals [off]
Use this flag to turn on the surface normals (displayed as green lines) in the recognition display.
-showMatches display matched points [off]
Use this flag to display correspondences between model and scene vertices (displayed as blue lines) in the recognition display.
-nm %d number of matches to display [1]
This option sets the number of matches displayed at the end of recognition. The default mode is to display only the best match.
-saveResult %S name of file to save display in [off]
Write the recognition display to the Inventor file specified.
-witeTrans %S file to store transformation in [off]
Write the transformation from the best match computed to a file as 6 floats (tx,ty,tz,rx,ry,rz).
-spinMethod %d
Spin image generation method: 0=vertices only, 1=interpolate in spin-image space, 2=interpolate in 3D space. Using methods 1 or 2 allows matching and recognition between meshes of differing resolution, since they create spin-images based on the entier surface of the mesh rather than just the vertices . Method 1 projects each mesh face into spin-image space (the alpha-beta coordinate system) and then raster scans the projected shape to find the contribution of the face to the spin-image. Method 2 discretizes each face with a regular grid (the resolution of which is set by the -gridSize parameter), and projects each point into spin-image space just as is done with the vertices. These ideas are described in Toward a General 3-D Matching Engine: Multiple Models, Complex Scenes, and Efficient Data Filtering.
-abBounds %F %F %F %F bounds on alpha,beta
Sets the size of the spin-image's region of influence. The order of parameters is alpha min, alpha max, beta min, beta max. Alpha is the dimension in the radial direction (along the surface tangent), and beta is the dimension along the surface normal axis. For example, to create a spin image with radius 200 and height 100, use -abBounds 0 200 -50 50. Typically, spin-image radius and height are chosen to be equal.
-restrict %F %F %F %F %F %F %F %F %F %F %F %F rough limits on the transformation between views
Limit the transform between views (as described in Unconstrained Registration of Large 3D Point Sets for Complex Model Building). If you have advance knowledge of the limits on rotation and translation between the two meshes being registered, these constraints will eliminate solutions that are outside those constraints. The parameters are rot_x_min (minimum rotation about the x axis), rot_y_min, rot_z_min, trans_x_min (minimum translation along the x axis), trans_y_min, trans_z_min, rot_x_max (maximum rotation about the x axis), rot_y_max, rot_z_max, trans_x_max (maximum translation along the x axis), trans_y_max, trans_z_max. All rotations are in degrees, and translations are in sensor units.
-hashed hashed
Stores vertices of the meshes in a hash table for speeding up spin-image generation. Only the vertices in the neighborhood of the query point can possibly fall within the spin-image's region of influence, so it is not necessary to iterate over all vertices.
-gridSize %F grid size
This option sets the size of the grid over which interpolated points are sampled. See the spinMethod option for details.
To align two surface meshes using the default parameters
SpinRecognize scene.wrl model.wrl
To align a partial scene with sensor origin (-100 -100 100) and to save the model stack to model.stack
SpinRecognize scene.wrl model.wrl -genStack 2 10 20 60 -writeStack model.stack -sOrig 100 -100 100
To align a model whose stack has already been created, to a scene and then display normals and matched points
SpinRecognize scene.wrl model.wrl -readStack model.stack -showNormals -showMatches
To align a model with a scene in batch mode, using as many scene points as possible, where the results are stored to files use
SpinRecognize scene.wrl model.wrl -selectF 1.0 -noDisplay -saveResult result.wrl -writeTrans result.trans
To align a partial scene to a complete model when alignment is not working with the default parameters use
SpinRecognize scene.wrl model.wrl -genStack 1 10 10 60 -selectF 1.0 -simT 0.75 -gcT 0.5
To align a partial model (sensor origin (0 0 100)) to a partial scene (sensor origin (100 0 100)) and display the best 2 matches with a small amount of spreading during verification use
SpinRecognize scene.wrl model.wrl -sOrig 0 0 100 -mOrig 100 0 100 -nm 2 -icpT 1.0
To align a model to a scene using a new (different seed) random set of scene points selected from flat areas in the scene use
SpinRecognize scene.wrl model.wrl -seed 11 -flatT 0.5 -selectF 0.25