RecognizeMesh

Description

RecognizeMesh is a program for recognizing multiple models represented as surface meshes in a scene represented as a surface mesh. Before using RecognizeMesh, the library of objects to be recognized must be built and then described using a library file. (.lf) The procedure for building object libraries a and making library files is explained in the tutorial on Library Building. After running RecognizeMesh, the recognized models are displayed superimposed on the scene data in a 3-D viewer. The theory behind this program is presented in the Ph.D. dissertation Spin-Images: A Representation for 3-D Surface Matching and the paper Object Recognition by Matching Oriented Points appearing in CVPR '97.

Recognize mesh is input a library file describing the location and parameters of the library used in recognition, a scene mesh, and the type of matching algorithm to use. RecognizeMesh can be run using the four matching algorithms described in the above dissertation: no compression, model compression, library compression and combination model and library compression. After surface matching, RecognizeMesh displays a 3-D viewer with the recognized models from the library superimposed on the scene data. Options can be specified to save the recognition result in which case a recognition file (.rf) describing the recognized models and their locations is output. This file can be read by DisplayRecognition which will show the recognized models superimposed on the scene data.

RecognizeMesh 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.

Files

main.c contains the main controlling function for multi-object recognition using spin-images. This file parses the library files.

scene.c contains the functions for manipulating scene data.

library.c contains the control functions for the four matching algorithms. These functions establish correspondences between scene data and model points.

register.c contains the functions that take model/scene point correspondences and produce disjoint model/scene surface matches.

Usage

By typing 'RecognizeMesh -' the following options (format description default) are printed:

Usage: RecognizeMesh (See RecognizeMesh.html for complete usage)

%S library filename [required]

%S scene prefix [required]

%S matching algorithm [required] (MA1,MA2,MA3,MA4)

-restrict %F %F %F %F %F %F %F %F %F %F %F %F

-sOrig %F %F %F sensor origin [-100 -100 100]

-epsMod %F model search distance [1.00]

-epsLib %F library search distance [1.00]

-selectF %F fraction of scene points searched [1.0]

-flatF %F flatness filter [1.0]

-saveResult %S save result in files with this prefix

-salT %F saliency threshold

-noDisplay turn off the display

-weight_thresh %F threshold for weighting scene points

-simT %F filter correspondences on similarity measure [0.5]

-trueIDs %S true scene ids

-write write new vector arrays

-displayPoints display which points were picked

-displayModels display recognized models

-corrThresh %F correlation threshold

-seed %d random number seed for picking initial points

-hashed use fast spin-image-making data structure

-abBounds %F %F %F %F bounds on alpha,beta

-nn %d number of neighbors for weighting

-showConsideredPts %d Show the points with spin images compared to this point

-consideredStats Print out stats about how many points this point was compared to

Detailed Usage

%S library filename [required]

The name of the library file that describes the library of objects to be used in recognition. Changing the library file changes the library used.

%S scene prefix [required]

Prefix of scene to compare to models in library. Used to determine mesh, projection matrix and camera image files.

%S matching algorithm [required] (MA1,MA2,MA3,MA4,MA5)

The type of matching algorithm used. The first four are described in Chapter 6 of Spin-Images: A Representation for 3-D Surface Matching: MA1 = n compression, MA2 = model compression, MA3 = library and model compression and MA4 = library compression. The last, MA5, is described briefly in the paper Large Data Sets and Confusing Scenes in 3-D Surface Matching and Recognition. Given examples of spin images from past scenes, we use a nearest-neighbor classifier to determine whether spin images in the current scene come from the background or from points on the object we're looking for. No other options will have any effect.

-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.

-sOrig %F %F %F sensor origin [-100 -100 100]

Origin of scene sensor. Used to orient normals as described in SpinRecognize documentation.

-epsMod %F model search distance [1.00]

Epsilon used when searching for closest matching model tuples. This parameter is set based as a fraction of the median distance between model tuples in the model closest point search structure (as proposed by Nene and Nayar).E.g., If the parameter is 1.5 then the search distance is 1.5 times the median distance between model tuples. If few matches are being found for model matching, increase this parameter.

-epsLib %F library search distance [1.00]

Epsilon used when searching for closest matching library tuples. This parameter is set based as a fraction of the median distance between library tuples in the model closest point search structure (as proposed by Nene and Nayar). E.g., If the parameter is 1.5 then the search distance is 1.5 times the median distance between library tuples. If few matches are being found for ibrary matching, increase this parameter.

-selectF %F fraction of scene points searched [1.0]

Fraction of scene points selected for matching to the models in the model library . If fraction is 1.0 then all vertices that are not on the boundary of the scene mesh will be selected.

-flatF %F flatness filter [1.0]

Fraction of points eliminated from matching due to high planar fit residuals. If this parameter is 0.5, then the half of the vertices in the scene with the highest planar fit residuals will be eliminated from matching to models. When the fraction is 1.0, not vertices will be eliminated. This parameter is used to eliminate vertices with possibly erroneous surface normals.

-saveResult %S save result in files with this prefix

Turn on result saving. A result file and a VRML describing the result of recognition are a output with this parameter as a prefix. The recognition file can be input into DisplayRecognition to see the recognition result at a later time.

-salT %F saliency threshold [1.0]

This option controls how selective we are in accepting a correspondence between scene points and a model point. A model point is compared to all scene points, giving one similarity measurement per scene point. A histogram of these similarities is constructed; if U is the upper quartile of the histogram and L is the lower quartile, then we accept correspondences with all scene points whose similarity measure is higher than U + saliency_threshold*(U-L). Setting this parameter higher will cause more scene-model correspondences to be thrown away.

-noDisplay turn off the display

Turns off the display of recognized models so that RecognizeMesh can be run in batch mode.

-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.

-trueIDs %S true scene ids

This parameter is useful for evaluating the accuracy of spin image correspondences when ground truth is known about which points in the scene belong to the object we're looking for and which are background. The string is the name of a file contains a list of vertex ID numbers for points in the scene that are on the object; at run time we compare this list to the scene vertices our spin image comparisons say are on the object. We then print out what percentage of the correct scene points are found in our list of spin image correspondences (detection rate) versus how many background scene points are in our list of spin image correspondences (false alarm rate).

-write write new vector arrays

This parameter is used in conjunction with -trueIDs to write out vector arrays (i.e. eigen-spin-images) for scene points that are on the objects we're looking for. Compressed spin images are gathered up from the scene points listed in the -trueIDs file, and written to the file named here, if this parameter is set. These vector arrays could be useful for analysis of the spin images of points that we're looking for in the scene.

-displayPoints display which points were picked

If this parameter is set, a VRML file called "savePrefix<\em>.picked.wrl" will be output, where savePrefix<\em> is the output file prefix set by the -saveResult parameter. In RecognizeMesh, we start by using spin images to find initial correspondences between points on the object and points in the scene; these correspondences are then filtered and clustered into hypotheses about where the objects are using geometric reasoning. Contained in this output file are the points identified by the first phase in the process as points on the object we were looking for. This output file is useful for analyzing which points on our target object and background have been correctly classified by spin image matching. This in turn can give us insight into the performance of the overall system: if spin-image matching finds many false correspondences between the object and background, or not enough of the correct corresponcences, the geometric reasoning will be more difficult.