From b507e2e8f7ca00ce42e95a97a79306c13e0137c4 Mon Sep 17 00:00:00 2001 From: cnr-isti-vclab Date: Sun, 2 Aug 2009 21:43:13 +0000 Subject: [PATCH] added comments in doxygen style. --- vcg/complex/trimesh/overlap_estimation.h | 117 +++++++++++++++++------ 1 file changed, 87 insertions(+), 30 deletions(-) diff --git a/vcg/complex/trimesh/overlap_estimation.h b/vcg/complex/trimesh/overlap_estimation.h index 7fd4b115..8edc7548 100644 --- a/vcg/complex/trimesh/overlap_estimation.h +++ b/vcg/complex/trimesh/overlap_estimation.h @@ -1,20 +1,44 @@ +/**************************************************************************** +* MeshLab o o * +* A versatile mesh processing toolbox o o * +* _ O _ * +* Copyright(C) 2007 \/)\/ * +* Visual Computing Lab /\/| * +* ISTI - Italian National Research Council | * +* \ * +* All rights reserved. * +* * +* This program is free software; you can redistribute it and/or modify * +* it under the terms of the GNU General Public License as published by * +* the Free Software Foundation; either version 2 of the License, or * +* (at your option) any later version. * +* * +* This program is distributed in the hope that it will be useful, * +* but WITHOUT ANY WARRANTY; without even the implied warranty of * +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * +* GNU General Public License (http://www.gnu.org/licenses/gpl.txt) * +* for more details. * +* * +****************************************************************************/ + #ifndef OVERLAP_ESTIMATION_H #define OVERLAP_ESTIMATION_H #include #include -//#include #include #include #include -//#include #include using namespace std; using namespace vcg; - +/** + * \brief This class provides a strategy to estimate the overlap percentage of two range maps/point clouds. + * \author Francesco Tonarelli + */ template class OverlapEstimation { public: @@ -31,6 +55,7 @@ template class OverlapEstimation typedef tri::VertTmark MarkerVertex; private: + /** Private simple class needed to perform sampling of pointers to vertexes. */ class VertexPointerSampler { public: @@ -41,26 +66,28 @@ template class OverlapEstimation ~VertexPointerSampler(){ if(m) delete m; } vector sampleVec; - void AddVert(VertexType &p){ sampleVec.push_back(&p); } - + void AddVert(VertexType &p){ sampleVec.push_back(&p); } //this function is the only we really need void AddFace(const FaceType &f, const CoordType &p){} - void AddTextureSample(const FaceType &, const CoordType &, const Point2i &){} }; public: + /** \brief Public class to hold parameters. Used to avoid endless list of parameters inside functions. + * \author Francesco Tonarelli + */ class Parameters { public: - int samples; //number of samples - int bestScore; //used to paint mMove: paint only if is a best score - float consensusDist; //consensus distance - float consensusNormalsAngle; //holds the the consensus angle for normals, in gradients. - float threshold; //consensus % to win consensus; - bool normalEqualization; //to use normal equalization in consensus - bool paint; //to paint mMov according to consensus - void (*log)(int level, const char * f, ... ); //pointer to log function + int samples; ///< Number of samples. + int bestScore; ///< Score to overcome to paint \c mMov . Used inside loop to paint only the best result. + float consensusDist; ///< Consensus distance. + float consensusNormalsAngle; ///< Holds the the consensus angle for normals, in gradients. + float threshold; ///< Consensus percentage requested to win consensus. + bool normalEqualization; ///< Allows to use normal equalization sampling in consensus + bool paint; ///< Allows painting of \c mMov according to consensus. + void (*log)(int level, const char * f, ... ); ///< Pointer to a log function. + /** Constructor with default values. */ Parameters() { samples = 2500; @@ -74,21 +101,30 @@ template class OverlapEstimation } }; - MeshType* mFix, *mMov; + private: + MeshType* mFix; /** Pointer to mesh \c mFix. */ + MeshType* mMov; /** Pointer to mesh \c mMov. */ vector >* normBuckets; //structure to hold normals bucketing. Needed for normal equalized sampling during consensus MeshGrid* gridFix; //variable to manage uniform grid MarkerVertex markerFunctorFix; //variable to manage uniform grid + public: + /** Default constructor. */ OverlapEstimation() : normBuckets(NULL), gridFix(NULL){} + /** Default destructor. Deallocates structures. */ ~OverlapEstimation(){ if(normBuckets) delete normBuckets; if(gridFix) delete gridFix; } - + /** Set the fix mesh \c mFix. */ void SetFix(MeshType& m){ mFix = &m; } - + /** Set the move mesh \c mMov. */ void SetMove(MeshType& m){ mMov = &m; } + /** Paint \c mMov according to the overlap estimation result. Works only if \c Compute() or \c Check() have + * been previously called with \c Parameters.paint=true .
Legend: \arg \e red: points overlaps correctly. + * \arg \e blue: points are too far to overlap. \arg \e yellow: points are close, but normals mismatch. + */ void Paint() { for(VertexIterator vi=mMov->vert.begin(); vi!=mMov->vert.end(); vi++){ @@ -100,6 +136,10 @@ template class OverlapEstimation } } + /** Initializes structures. + * @param param A reference to a \c Parameter class containing all the desidered options to estimate overlap. + * \return \c true if everything goes right. + */ bool Init(Parameters& param){ //builds the uniform grid with mFix vertices gridFix = new MeshGrid(); @@ -115,13 +155,20 @@ template class OverlapEstimation return true; } + /** Compute the overlap estimation between \c mFix and \c mMov. + * @param param A reference to a \c Parameter class containing all the desidered options to estimate overlap. + * \return The percentage of overlap in the range \c [0..1] . + */ float Compute(Parameters& param) { return Check(param)/float(param.samples); } - //compute the randomized consensus beetween m1 e m2 (without taking in account any additional transformation) - //IMPORTANT: per vertex normals of m1 and m2 MUST BE PROVIDED JET NORMALIZED!!! + /** Compute the overlap estimation between \c mFix and \c mMov. + * @param param A reference to a \c Parameter class containing all the desidered options to estimate overlap. + * \return The number of points that overlap correctly. This number is in the range \c [0..param.samples] . + */ + //IMPORTANT: per vertex normals of mMov and mFix MUST BE PROVIDED YET NORMALIZED!!! int Check(Parameters& param) { //pointer to a function to compute distance beetween points @@ -182,9 +229,7 @@ template class OverlapEstimation } } - //apply colors if consensus is the best ever found. - //NOTE: we got to do this here becouse we need a handle to sampler. This is becouse vertex have been shuffled - //and so colors have been stored not in order in the buffer! + //Paint the mesh only if required and if consensus is the best ever found. Colors have been stores as numbers into quality attribute if(param.paint){ if(consensus>=param.bestScore && consensus>=cons_succ) Paint(); } @@ -193,21 +238,25 @@ template class OverlapEstimation } private: - + /** Fill the vector \c vert with \c sampleNum pointers to vertexes sampled uniformly from mesh \c m . + * @param m Source mesh. + * @param vert Destination vector. + * @param sampleNum Requested number of vertexes. + */ void SampleVertUniform(MESH_TYPE& m, vector& vert, int sampleNum) { VertexPointerSampler sampler; tri::SurfaceSampling::VertexUniform(m, sampler, sampleNum); for(unsigned int i=0; i >* BucketVertexNormal(typename MESH_TYPE::VertContainer& vert, int bucketDim = 30) { static vector NV; if(NV.size()==0) GenNormal::Uniform(bucketDim,NV); - // Bucket vector dove, per ogni normale metto gli indici - // dei vertici ad essa corrispondenti vector >* BKT = new vector >(NV.size()); //NV size is greater then bucketDim, so don't change this! int ind; @@ -218,7 +267,10 @@ template class OverlapEstimation return BKT; } - + /** Samples the \c vert vector in a normal equalized way. + * \return \c SampleNum pointers to vertexes sampled in a normal equalized way. Pointers are stored in + * the \c vert (i.e it is an \c in/out parameter). + */ bool SampleVertNormalEqualized(vector& vert, int SampleNum) { assert(normBuckets); @@ -244,16 +296,21 @@ template class OverlapEstimation vert.resize(SampleNum); return true; } - + /** Function to retrieve a static random number generator object. + * \return A \c SubtractiveRingRNG object. + */ static math::SubtractiveRingRNG &LocRnd(){ static math::SubtractiveRingRNG myrnd(time(NULL)); return myrnd; } - + /** Gets a random number in the interval \c [0..n] . Number is + * produced by a \c SubtractiveRingRNG object initialized once for all. + * \return A random number in the interval \c [0..n] . + */ static int LocRnd(int n){ return LocRnd().generate(n); } - + /** Put \c mFix into a grid. */ inline void SetupGrid() { gridFix->Set(mFix->vert.begin(),mFix->vert.end());