Fuzzy Correspondences - Using Binaries

← Home

Download FuzzyCorrs1.0 Binaries (this zip file includes SurfCorr2.1)
Download Spherical Harmonics Binaries

0. Before you start

Running this code can be as simple as A) providing a dataset in the appropriate format (see 1.2) and B) analyzing the dataset:
     ./AnalyzeDB.sh $dbDir

Note that the script also requires MATLAB (edge rank, eigendecomposition) and Spherical Harmonics Shape Descriptor is provided separately (copy ./gaps_shd.bins/* to ./FuzzyCorrs1.0.bins/FuzzyAnalysis/ShapeDescriptors).

The rest of this document explains the execution in more details so you could adapt it to your needs.

1. Initializing the Database

1.1 (optional) Obtaining the models collection

For example, to get 20 chairs:
        ./InitDB.sh MyDBChair chair 20 GOOGLE_WAREHOUSE all

NOTE 1: Run ./InitDB.sh MyDBChair for interactive interface, press '`' to see options, you can delete models that are not within class. (`'/"`: next, prev page, 's' - show editing modes, '0-3' - model to delete in 'deletion' mode, '1-3' - put in main window in 'delete CC' mode, right click - select CC in 'delete CC' mode, 'd' - delete CC (once selected in red)., w - write. You can use the interface for simple cleanup: to delete walls / ground planes, and prune out models that are not of the desired class.

1.2 Organization of the 'database'

You don't need to use Init.sh to create the database. A database needs to have:
database.txt - list of models, ASCII file format (no spaces in $id and $modelName, $id=0...N):
        Model$id: ModelName $modelName ModelID $id
Models - directory with all models
        $modelName/$modelname.model3d - Model meta data. ASCII file format:
                        Geometry $dbDir/Models/$modelname/Geometry/$modelname.ply
                        GeomType IRREGULAR_POLYGON_SOUP (or UNIFORM_MANIFOLD)
        $dbDir/Models/$modelname/Geometry/$modelname.ply (.off) - Model geometry. *.off, *.ply

2. Analyzing the database

You should be able to just run:
        ./AnalyzeDB.sh MyDBChair
to analyze the DB (as long as it is in the format described in 1.2).
Also if you want to use intrinsic matching make sure that you have ../BIM directory with appropriate binaries, and use the following script ./AnalyzeDB_BIM.sh. NOTE: Blended Intrinsic Maps is MUCH slower than ICP alignments. Thus, for any reasonably-sized collection use a cluster (e.g. set runJobsAs="qsubEach" in AnalyzeDB_BIM.sh, or see RunBIMBatch.sh and modify it to work with your distributed system).

See Example Data and Format

2.1 Execution

Note that each Analyze*.sh script can also run on a cluster, using qsub. Just set runJobsAs="qsubEach" in the beginning. You can also set the up vector (or upVec="none"), it's set to z-up by default.
During the execution a monitoring script will be running in a background, waiting for a file to process. This could be: Blended Map (align a pair of maps using external script, only if running ./AnalyzeDB_BIM.sh), Spherical Harmonics Descriptor, matlab (edgerank, eigendecomposition).

2.2 Shape Descriptors

Some portion of our algorithm requires shape descriptors. You can pre-compute these descriptors in Models/$modelname/SD/$modelname.shd. These are just feature vectors stored as binary files (where similarity is dot product of feature vectors). First 4 bytes is integer N, followed by N floating-point numbers (single precision). Unfortunately, due to license restrictions we are not distributing Spherical Harmonics code (see the script and binaries in ./ShapeDescriptors/ directory). You might consider using Misha Kazhdan's implementation, or modify the script to compute any other shape signature.

2.2 ../BIM

This directory contains exectuables for alternative implementation of blended intrinsic maps. The only difference is that these files output 'fuzzy correspondences' for pair of shapes, instead of point-to-point map. Note also that it prints all possible maps extracted due to all eigenvectors.
All map files are printed to $dbDir/BIM directory, note that they can take quite a bit of space and also you don't need them after fuzzy correspondence analysis - i.e. after deleting $dbDir/BIM directory you still can visualize fuzzy corrs. results.

3. User Interface

NOTE: this user interface is for debugging fuzzy correspondences. Although it has some functionalities of the exploration interface, please use the exploration interface provided by Wilmot Li.

3.0 Quick Reference

     Select Cor in Top-left pane (right list)
     Select CorrsDiffused in Top-left pane (left list)
     Press 'p'
     Press 'u'
     Move mouse over a point and press SPACE (select points this way)

3.1 Top-left pane

Top-left pane allows to select from multiple menues:
Mdl - list of models. You can select a sub-window by clicking on it, selected window is outliend in blue (windows have ids: 0,1,2,3). Then you can select a name in the model list (name gets highlighted in blue), and this model will appear in the selected window.
Pts - point set to visualize (irrelevant)
Dst - distances (not implemented)
Val - model values (irrelevant)
Cor - Correspondence. Select CorrsDiffused (==fuzzy correspondences)
<-> - next / previous correspondences (irrelevant for Fuzzy Correspondences, can use to visualize pairwise alignments)
CVal - correspondence values (irrelevant)

3.2 Hot keys

'`' - see help (more keys listed there)
'p' - visualize K points w/ fuzzy corrs.
'SPACE' - select a point under the mouse
'u' - visualize fuzzy correspondence values
'RIGHT-CLICK' - Click on point to add it to 'currently selected region'
'/' - Clear Selection
'?' - sort based on correspondence value (interactive sorting in the exploration interface).
NOTE: big-red points == dark blue region.
'k' - add current selection to the facet 'Y' - clear all facets
NOTE: I cannot guarantee that above functionalities work as in the paper. See exploration interface by Wilmot Li for actual implementation