Points Consolidation API

H. Huang, D. Li, H. Zhang, U. Ascher, D.Cohen-Or

Points Consolidation API is used in SIGGRAPH Asia 2009 paper: "Consolidation of Unorganized Point Clouds for Surface Reconstruction" by H. Huang, D. Li, H. Zhang, U. Ascher, D.Cohen-Or. [Project Page]

This API is provided "as is".

Acknowledgments

Our code is based on the VCG library from the Visual Computing Lab in Pisa, Italy. We would like to thank Federico Ponchio for the original LOP implementation and consultation on VCG.

Also, our API relies on the ANN library (http://www.cs.umd.edu/~mount/ANN/) to find k-nearest neighbors. It calls RG_NearestNeighbors.exe at run time. Three intermediate files will be generated (point_cloud.txt, query.txt, and query_result.txt).  Please allow write access to the directory where the API is installed.

Academic Use of the API

If you use this API to generate results that you use in an academic publication you should include the following citation in your paper:

@article {hlzac09,
title = {Consolidation of Unorganized Point Clouds for Surface Reconstruction},
author = {H. Huang and D. Li and H. Zhang and U. Ascher and D. Cohen-Or},
journal = {ACM Transactions on Graphics, (Proceedings SIGGRAPH Asia 2009)},
volume = {28},
number = {5},
pages = {176},
year = {2009}
}

How to Install

- The .exe and .dll files are all in Points-Consolidation.zip (5MB).

-- Download this and unzip it. Please make sure you allow write access to the directory where the package is saved.

--- Double click Points-Consolidation.exe.

Details of the Controls

 

There are three groups of controls in the Points-Consolidation API.

  • WLOP: allows users to clean data first.
    • Load Particles: loads point clouds in .ply format.
    • Sub: denotes the ratio of the number of the original unorganized points to the number of projected particles. For example, Sub = 20 means 1/20 of the original points are randomly selected as initial projected particles.
    • h: defines the size of the influence neighborhood. The default value is 4*sqrt(d_bb/m).
    • Mu: controls the repulsion force, 0 <= Mu < 0.5. The default value is 0.45.
    • Iter: denotes the number of WLOP iterations to run.
    • Density weights: controls if density weights are used or not. This option is enabled by default.
    • Run: runs WLOP iterations and the number of iterations is given as Iter.
    • Save (.ply): saves the current results (projected particles) as .ply file.

     

  • Normal: allows users to estimate and consolidate normals.
    • KNN: denotes how many nearest neighbors are considered when a particle is orientated. The default value is 6.
    • Detect Feature: identifies feature particles on thin surfaces. These particles can be oriented, but are not allowed to propagate their orientations.
    • Normal Estimation: orients PCA normals using our propagation scheme.
    • OPCA: performs local orientation-aware PCA.
    • Re-Orientate: flips all normals to the opposite directions.
    • Save Results (.txt): saves the current results as .txt file. The file has the following structure: the first line is the number of particles saved; each following line has 6 components, such that the first three are the coordinates of the particle and the next three are directions of the normal vector.
    • Load Results: loads a previously saved .txt file.

     

  • View: allows users to change the observation view.
    • Show Inputs: shows the original unorganized points as gray dots.
    • Show Features: shows the feature particles detected as green boxes.
    • Show Particles: shows the projected particles as disks, quads, or dots.
    • Back_culling: culls particles with back-facing normals.
    • Width: controls the size of the particle splats shown in window.
    • Red, Green, Blue, Alpha: control the color and opaqueness of the particles.

     

How to Use

Before you load any point cloud, adjust the "Sub" value. In general, a higher "Sub" produces a more regular point distribution. After loading and before clicking "Run", you might also want to adjust "h", "Mu" or "Iter". In particular, the supporting radius "h" is an important parameter. The automatic default value gives the users a good hint (see the length of the blue line in window) and should be further tuned based on the size and shape of the loaded initial particle set.

After WLOP, a thinned, outlier-free, and uniformly distributed set of particles is obtained. Before execute the next step of "Normal Estimation", users may change "KNN" or "Detect Feature" first. If one pass of our propagation scheme does not provide the overall correct normals, which can be simply and visually checked using "Back-culling", click "OPCA" and then "Normal Estimation" to fix errors iteratively.
 

Raw Data Available

For demo, download the following models and run with default setting: Sub = 20, Mu = 0.45, Iter = 50, KNN = 6.