0、DgmOctree
//包含八叉树的构建， 最近邻搜索、相邻搜索等
//! DgmOctree constructor
/** \param cloud the cloud to construct the octree on
**/
explicit DgmOctree(GenericIndexedCloudPersist* cloud);
//! DgmOctree destructor
virtual ~DgmOctree();
//! Clears the octree
virtual void clear();
//! Builds the structure
/** Octree 3D limits are determined automatically.
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return the number of points projected in the octree
**/
int build(GenericProgressCallback* progressCb = nullptr);
//! Builds the structure with constraints
/** Octree spatial limits must be specified. Also, if specified, points falling outside
the "pointsFilter" limits won't be projected into the octree structure. Otherwise, all
points will be taken into account. Octree 3D limits in space should be cubical.
\param octreeMin the lower limits for the octree cells along X, Y and Z
\param octreeMax the upper limits for the octree cells along X, Y and Z
\param pointsMinFilter the lower limits for the projected points along X, Y and Z (is specified)
\param pointsMaxFilter the upper limits for the projected points along X, Y and Z (is specified)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return the number of points projected in the octree
**/
int build( const CCVector3& octreeMin,
const CCVector3& octreeMax,
const CCVector3* pointsMinFilter = 0,
const CCVector3* pointsMaxFilter = 0,
GenericProgressCallback* progressCb = 0);
-------------------------------------------------------------------------------------------------------------------------------------
1、KDTree
//! Builds the KD-tree 建树
/** \param cloud the point cloud from which to buil the KDtree
\param progressCb the client method can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return success
**/
bool buildFromCloud(GenericIndexedCloud *cloud, GenericProgressCallback *progressCb = nullptr);
//! Gets the point cloud from which the tree has been build 获取点云
/** \return associated cloud
**/
GenericIndexedCloud* getAssociatedCloud() const { return m_associatedCloud; }
//! Nearest point search 查询临近点
/** \param queryPoint coordinates of the query point from which we want the nearest point in the tree
\param nearestPointIndex [out] index of the point that lies the nearest from query Point. Corresponding coordinates can be retrieved using getAssociatedCloud()->getPoint(nearestPointIndex)
\param maxDist distance above which the function doesn't consider points
\return true if it finds a point p such that ||p-queryPoint||<=maxDist. False otherwise
**/
bool findNearestNeighbour( const PointCoordinateType *queryPoint,
unsigned &nearestPointIndex,
ScalarType maxDist);
//! Optimized version of nearest point search method 距离半径内搜索点
/** Only checks if there is a point p into the tree such that ||p-queryPoint||<=maxDist (see FindNearestNeighbour())
**/
bool findPointBelowDistance(const PointCoordinateType *queryPoint,
ScalarType maxDist);
//! Searches for the points that lie to a given distance (up to a tolerance) from a query point 距离缓冲区半径（圆环内）搜索点
/** \param queryPoint query point coordinates
\param distance distance wished between the query point and resulting points
\param tolerance error allowed by the function : each resulting point p is such that distance-tolerance<=||p-queryPoint||<=distance+tolerance
\param points [out] array of point m_indexes. Each point stored in this array lie to distance (up to tolerance) from queryPoint
\return the number of matching points
**/
unsigned findPointsLyingToDistance(const PointCoordinateType *queryPoint,
ScalarType distance,
ScalarType tolerance,
std::vector<unsigned> &points);
-----------------------------------------------------------------------------------------------------------------------------------------
2、CloudSamplingTools
//! Octree cell resampling methods (see CloudSamplingTools::resampleCloudWithOctree) 点云重采样方法
enum RESAMPLING_CELL_METHOD {CELL_CENTER, CELL_GRAVITY_CENTER};
//! Octree cell simplifying methods (see CloudSamplingTools::subsampleCloudWithOctree) 点云降采样方法
enum SUBSAMPLING_CELL_METHOD {RANDOM_POINT, NEAREST_POINT_TO_CELL_CENTER};
//! Resamples a point cloud (process based on the octree) 基于八叉树层 点云重采样
/** A resampling algorithm is applied inside each cell of the octree. The
different resampling methods are represented as an enumerator
(see RESAMPLING_CELL_METHOD) and consist in simple processes
such as replacing all the points lying in a cell by the cell center or
by the points gravity center.
\param cloud the point cloud to resample
\param octreeLevel the octree level at which to perform the resampling process
\param resamplingMethod resampling method (applied to each octree cell)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param inputOctree if the octree has been already computed, it can be used by the process (avoid recomputation)
\return the resampled cloud (new cloud)
**/
static PointCloud* resampleCloudWithOctreeAtLevel( GenericIndexedCloudPersist* cloud,
unsigned char octreeLevel,
RESAMPLING_CELL_METHOD resamplingMethod,
GenericProgressCallback* progressCb = nullptr,
DgmOctree* inputOctree = nullptr);
//! Resamples a point cloud (process based on the octree)基于八叉树 点云重采样
/** Same as 'resampleCloudWithOctreeAtLevel' method, apart the fact that instead
of giving a specific octree subdivision level as input parameter, one can specify
an approximative number of points for the resulting cloud (algorithm will
automatically determine the corresponding octree level).
\param cloud the point cloud to resample
\param newNumberOfPoints desired number of points (approximative)
\param resamplingMethod resampling method (applied to each octree cell)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param inputOctree if the octree has been already computed, it can be used by the process (avoid recomputation)
\return the resampled cloud (new cloud)
**/
static GenericIndexedCloud* resampleCloudWithOctree(GenericIndexedCloudPersist* cloud,
int newNumberOfPoints,
RESAMPLING_CELL_METHOD resamplingMethod,
GenericProgressCallback* progressCb = nullptr,
DgmOctree* inputOctree = nullptr);
//! Subsamples a point cloud (process based on the octree) 基于八叉树层 点云降采样
/** A subsampling algorithm is applied inside each cell of the octree. The
different subsampling methods are represented as an enumerator
(see SUBSAMPLING_CELL_METHOD) and consist in simple processes
such as choosing a random point, or the one closest to the cell center.
\param cloud point cloud to subsample
\param octreeLevel octree level at which to perform the subsampling process
\param subsamplingMethod subsampling method (applied to each octree cell)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param inputOctree if the octree has been already computed, it can be used by the process (avoid recomputation)
\return a reference cloud corresponding to the subsampling 'selection'
**/
static ReferenceCloud* subsampleCloudWithOctreeAtLevel(GenericIndexedCloudPersist* cloud,
unsigned char octreeLevel,
SUBSAMPLING_CELL_METHOD subsamplingMethod,
GenericProgressCallback* progressCb = nullptr,
DgmOctree* inputOctree = nullptr);
//! Subsamples a point cloud (process based on the octree)基于八叉树 点云降采样
/** Same as 'subsampleCloudWithOctreeAtLevel' method, apart the fact that instead
of giving a specific octree subdivision level as input parameter, one can specify
an approximative number of points for the resulting cloud (algorithm will
automatically determine the corresponding octree level).
\param cloud point cloud to subsample
\param newNumberOfPoints desired number of points (approximative)
\param subsamplingMethod resampling method (applied to each octree cell)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param inputOctree if the octree has been already computed, it can be used by the process (avoid recomputation)
\return a reference cloud corresponding to the subsampling 'selection'
**/
static ReferenceCloud* subsampleCloudWithOctree(GenericIndexedCloudPersist* cloud,
int newNumberOfPoints,
SUBSAMPLING_CELL_METHOD subsamplingMethod,
GenericProgressCallback* progressCb = nullptr,
DgmOctree* inputOctree = nullptr);
//! Subsamples a point cloud (process based on random selections) 基于随机数 点云降采样
/** A very simple subsampling algorithm that simply consists in selecting
"n" different points, in a random way.
\param cloud point cloud to subsample
\param newNumberOfPoints desired number of points (exact)
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return a reference cloud corresponding to the subsampling 'selection'
**/
static ReferenceCloud* subsampleCloudRandomly( GenericIndexedCloudPersist* cloud,
unsigned newNumberOfPoints,
GenericProgressCallback* progressCb = nullptr);
//! Parameters for the scalar-field based modulation of a parameter
struct SFModulationParams
{
//! Default constructor
explicit SFModulationParams(bool state = false) : enabled(state), a(0.0), b(1.0) {}
//! Whether the modulation is enabled or not
bool enabled;
//! Modulation scheme: y = a.sf + b
double a;
//! Modulation scheme: y = a.sf + b
double b;
};
//! Resamples a point cloud (process based on inter point distance) 基于空间 点云降采样
/** The cloud is resampled so that there is no point nearer than a given distance to other points
It works by picking a reference point, removing all points which are to close to this point, and repeating these two steps until the result is reached
\param cloud the point cloud to resample
\param minDistance the distance under which a point in the resulting cloud cannot have any neighbour
\param modParams parameters of the subsampling behavior modulation with a scalar field (optional)
\param octree associated octree if available
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return a reference cloud corresponding to the resampling 'selection'
**/
static ReferenceCloud* resampleCloudSpatially( GenericIndexedCloudPersist* cloud,
PointCoordinateType minDistance,
const SFModulationParams& modParams,
DgmOctree* octree = nullptr,
GenericProgressCallback* progressCb = nullptr);
//! Statistical Outliers Removal (SOR) filter // 基于滤波 剔除外点
/** This filter removes points based on their mean distance to their distance (by comparing it to the average distance of all points to their neighbors).
It is equivalent to PCL StatisticalOutlierRemoval filter (see http://pointclouds.org/documentation/tutorials/statistical_outlier.php)
\param cloud the point cloud to resample
\param knn number of neighbors
\param nSigma number of sigmas under which the points should be kept
\param octree associated octree if available
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return a reference cloud corresponding to the filtered cloud
**/
static ReferenceCloud* sorFilter( GenericIndexedCloudPersist* cloud,
int knn = 6,
double nSigma = 1.0,
DgmOctree* octree = nullptr,
GenericProgressCallback* progressCb = nullptr);
//! Noise filter based on the distance to the approximate local surface 基于距离 噪声滤波
/** This filter removes points based on their distance relatively to the best fit plane computed on their neighbors.
\param cloud the point cloud to resample
\param kernelRadius neighborhood radius
\param nSigma number of sigmas under which the points should be kept
\param removeIsolatedPoints whether to remove isolated points (i.e. with 3 points or less in the neighborhood)
\param useKnn whether to use a constant number of neighbors instead of a radius
\param knn number of neighbors (if useKnn is true)
\param useAbsoluteError whether to use an absolute error instead of 'n' sigmas
\param absoluteError absolute error (if useAbsoluteError is true)
\param octree associated octree if available
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return a reference cloud corresponding to the filtered cloud
**/
static ReferenceCloud* noiseFilter( GenericIndexedCloudPersist* cloud,
PointCoordinateType kernelRadius,
double nSigma,
bool removeIsolatedPoints = false,
bool useKnn = false,
int knn = 6,
bool useAbsoluteError = true,
double absoluteError = 0.0,
DgmOctree* octree = nullptr,
GenericProgressCallback* progressCb = nullptr);
-------------------------------------------------------------------------------------------------------------------------------------------
3、Delaunay2dMesh
//USE_CGAL_LIB 依赖于CGAL库
-------------------------------------------------------------------------------------------------------------------------------------------
4、DistanceComputationTools
// 里面封装了 各种计算距离的方法
// 如：两个点云之间的最短距离、点云到mesh的最短距离、点到三角形的距离等等
-------------------------------------------------------------------------------------------------------------------------------------------
5、FastMarching //Fast Marching Algorithm http://www.slicer.org
-------------------------------------------------------------------------------------------------------------------------------------------
6、ManualSegmentationTools
// 在平面2d闭合线内 分割点云
-------------------------------------------------------------------------------------------------------------------------------------------
7、MeshSamplingTools
// 计算mesh 表面积，封闭mesh的体积，采样mesh顶点
//! Computes the mesh area
/** \param mesh triangular mesh
\return mesh area
**/
static double computeMeshArea(GenericMesh* mesh);
//! Computes the mesh volume
/** \warning Make sure the input mesh is closed!
See MeshSamplingTools::computeMeshEdgesConnectivity.
\param mesh triangular mesh (closed!)
\return mesh volume
**/
static double computeMeshVolume(GenericMesh* mesh);
//! Statistics on the edges connectivty of a mesh
struct EdgeConnectivityStats
{
EdgeConnectivityStats()
: edgesCount(0)
, edgesNotShared(0)
, edgesSharedByTwo(0)
, edgesSharedByMore(0)
{}
//! Total number of edges
unsigned edgesCount;
//! Edges not shared (i.e. used by only one triangle)
unsigned edgesNotShared;
//! Edges shared by exactly two triangles
unsigned edgesSharedByTwo;
//! Edges shared by more than two triangles
unsigned edgesSharedByMore;
};
//! Computes some statistics on the edges connectivty of a mesh
/** This methods counts the number of edges shared by 1, 2 or more faces.
One ore more edges used only by 1 face each indicates the presence of
at least one hole. Edges used by more than two faces are non-manifold.
\param[in] mesh triangular mesh
\param[out] stats output statistics
\return false if an error occurred (invalid input or not enough memory)
**/
static bool computeMeshEdgesConnectivity(GenericIndexedMesh* mesh, EdgeConnectivityStats& stats);
//! Flags used by the MeshSamplingTools::flagMeshVerticesByType method.
enum VertexFlags
{
VERTEX_NORMAL = 0, /**< Normal vertex **/
VERTEX_BORDER = 1, /**< Vertex on a border/hole **/
VERTEX_NON_MANIFOLD = 2 /**< Vertex on a non-manifold edge **/
};
//! Flags the vertices of a mesh depending on their type
/** See MeshSamplingTools::VertexFlags.
\param[in] mesh triangular mesh
\param[in] flags already allocated scalar field to store the per-vertex flags
\param[out] stats output statistics (optional)
\return false if an error occurred (invalid input or not enough memory)
**/
static bool flagMeshVerticesByType(GenericIndexedMesh* mesh, ScalarField* flags, EdgeConnectivityStats* stats = nullptr);
//! Samples points on a mesh
/** The points are sampled on each triangle randomly, by generating
two numbers between 0 and 1 (a and b). If a+b > 1, then a = 1-a and
b = 1-b. Let ABC be the triangle, then the new point P will be as
AP = a.AB+b.AC (AP,AB and AC are vectors here). The number of
points sampled on each triangle depends on the triangle's area.
Let s be this area, and µ the sampling density, then N = s*µ is
the theoretic (floating) number of points to sample. The floating
part of N (let's call it Nf, and let Ni be the integer part) is
handled by generating another random number between 0 and 1.
If this number is less than Nf, then Ni = Ni+1. The number of points
sampled on the triangle will simply be Ni.
\param mesh the mesh to be sampled
\param samplingDensity the sampling surface density
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param[out] triIndices triangle index for each samples point (output only - optional)
\return the sampled points
**/
static PointCloud* samplePointsOnMesh( GenericMesh* mesh,
double samplingDensity,
GenericProgressCallback* progressCb = nullptr,
std::vector<unsigned>* triIndices = nullptr);
//! Samples points on a mesh
/** See the other version of this method. Instead of specifying a
density, it is possible here to specify the total number of
points to sample (approximative).
\param mesh the mesh to be sampled
\param numberOfPoints the desired number of points on the whole mesh
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param[out] triIndices triangle index for each samples point (output only - optional)
\return the sampled points
**/
static PointCloud* samplePointsOnMesh( GenericMesh* mesh,
unsigned numberOfPoints,
GenericProgressCallback* progressCb = nullptr,
std::vector<unsigned>* triIndices = nullptr);
-------------------------------------------------------------------------------------------------------------------------------------------
8、PointProjectionTools //依赖与 delaunay2d mesh 因此需要 cgal库
//! A scaled geometrical transformation (scale + rotation + translation)
/** P' = s.R.P + T
**/
struct Transformation
{
//! Rotation
CCLib::SquareMatrix R;
//! Translation
CCVector3 T;
//! Scale
PointCoordinateType s;
//! Default constructor
Transformation() : s(PC_ONE) {}
//! Applies the transformation to a point
inline CCVector3 apply(const CCVector3& P) const { return s * (R * P) + T; }
//! Applies the transformation to a cloud
/** \warning THIS METHOD IS NOT COMPATIBLE WITH PARALLEL STRATEGIES
\warning The caller should invalidate the bounding-box manually afterwards
**/
CC_CORE_LIB_API void apply(GenericIndexedCloudPersist& cloud) const;
};
//! Applys a geometrical transformation to a point cloud
/** \param cloud the point cloud to be "transformed"
\param trans the geometrical transformation
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return the "transformed" cloud
**/
static PointCloud* applyTransformation( GenericCloud* cloud,
Transformation& trans,
GenericProgressCallback* progressCb = nullptr);
-------------------------------------------------------------------------------------------------------------------------------------------
9、RegistrationTools
// 介绍了三种点云注册的方法：基于角点、基于迭代icp、基于四点。
//! (1) Horn point cloud registration algorithm
/** See 'Closed-form solution of absolute orientation using unit quaternions', B.K.P. Horn, 1987.
**/
class CC_CORE_LIB_API HornRegistrationTools : public RegistrationTools
{
public:
//! Returns "absolute orientation" (scale + transformation) between two set of (unordered) points
/** Warning: both clouds must have the same size (and at least 3 points)
Output transformation is from the left (L) to the right (R) coordinate system
\param lCloud left cloud {Pl}
\param rCloud right cloud {Pr}
\param trans resulting transformation: Pr = s.R.Pl + T
\param fixedScale force scale parameter to 1.0
\return success
**/
static bool FindAbsoluteOrientation(GenericCloud* lCloud,
GenericCloud* rCloud,
ScaledTransformation& trans,
bool fixedScale = false);
//! Computes RMS between two clouds given a transformation and a scale
/** Warning: both clouds must have the same size (and at least 3 points)
RMS = Sqrt ( Sum( square_norm( Pr - s*R*Pl+T ) ) / count )
\param lCloud left cloud {Pl}
\param rCloud right cloud {Pr}
\param trans transformation: Pr = s.R.Pl + T
\return RMS (or -1.0 if an error occurred)
**/
static double ComputeRMS( GenericCloud* lCloud,
GenericCloud* rCloud,
const ScaledTransformation& trans);
};
//! (2)ICP point cloud registration algorithm (Besl et al.).
class CC_CORE_LIB_API ICPRegistrationTools : public RegistrationTools
{
public:
//! Convergence control method
enum CONVERGENCE_TYPE
{
MAX_ERROR_CONVERGENCE = 0,
MAX_ITER_CONVERGENCE = 1,
};
//! Errors
enum RESULT_TYPE
{
ICP_NOTHING_TO_DO = 0,
ICP_APPLY_TRANSFO = 1,
ICP_ERROR = 100,
//all errors should be greater than ICP_ERROR
ICP_ERROR_REGISTRATION_STEP = 101,
ICP_ERROR_DIST_COMPUTATION = 102,
ICP_ERROR_NOT_ENOUGH_MEMORY = 103,
ICP_ERROR_CANCELED_BY_USER = 104,
ICP_ERROR_INVALID_INPUT = 105,
};
//! ICP Parameters
struct Parameters
{
Parameters()
: convType(MAX_ERROR_CONVERGENCE)
, minRMSDecrease(1.0e-5)
, nbMaxIterations(20)
, adjustScale(false)
, filterOutFarthestPoints(false)
, samplingLimit(50000)
, finalOverlapRatio(1.0)
, modelWeights(nullptr)
, dataWeights(nullptr)
, transformationFilters(SKIP_NONE)
, maxThreadCount(0)
{}
//! Convergence type
CONVERGENCE_TYPE convType;
//! The minimum error (RMS) reduction between two consecutive steps to continue process (ignored if convType is not MAX_ERROR_CONVERGENCE)
double minRMSDecrease;
//! The maximum number of iteration (ignored if convType is not MAX_ITER_CONVERGENCE)
unsigned nbMaxIterations;
//! Whether to release the scale parameter during the registration procedure or not
bool adjustScale;
//! If true, the algorithm will automatically ignore farthest points from the reference, for better convergence
bool filterOutFarthestPoints;
//! Maximum number of points per cloud (they are randomly resampled below this limit otherwise)
unsigned samplingLimit;
//! Theoretical overlap ratio (at each iteration, only this percentage (between 0 and 1) will be used for registration
double finalOverlapRatio;
//! Weights for model points (i.e. only if the model entity is a cloud) (optional)
ScalarField* modelWeights;
//! Weights for data points (optional)
ScalarField* dataWeights;
//! Filters to be applied on the resulting transformation at each step (experimental) - see RegistrationTools::TRANSFORMATION_FILTERS flags
int transformationFilters;
//! Maximum number of threads to use (0 = max)
int maxThreadCount;
};
//! Registers two clouds or a cloud and a mesh
/** This method implements the ICP algorithm (Besl et al.).
\warning Be sure to activate an INPUT/OUTPUT scalar field on the point cloud.
\warning The mesh is always the reference/model entity.
\param modelCloud the reference cloud or the vertices of the reference mesh --> won't move
\param modelMesh the reference mesh (optional) --> won't move
\param dataCloud the cloud to register --> will move
\param params ICP parameters
\param[out] totalTrans the resulting transformation (once the algorithm has converged)
\param[out] finalRMS final error (RMS)
\param[out] finalPointCount number of points used to compute the final RMS
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\return algorithm result
**/
static RESULT_TYPE Register( GenericIndexedCloudPersist* modelCloud,
GenericIndexedMesh* modelMesh,
GenericIndexedCloudPersist* dataCloud,
const Parameters& params,
ScaledTransformation& totalTrans,
double& finalRMS,
unsigned& finalPointCount,
GenericProgressCallback* progressCb = nullptr);
};
//! (3) Four Points Congruent Sets (4PCS) registration algorithm (Dror Aiger, Niloy J. Mitra, Daniel Cohen-Or)
class CC_CORE_LIB_API FPCSRegistrationTools : public RegistrationTools
{
public:
//! Registers two point clouds
/** Implements the 4 Points Congruent Sets Algorithm (Dror Aiger, Niloy J. Mitra, Daniel Cohen-Or
\param modelCloud the reference cloud (won't move)
\param dataCloud the cloud to register (will move)
\param transform the resulting transformation (output)
\param delta maximal distance to the reference cloud for the data points to be considered as registered
\param beta is used for bases selection (error tolerance)
\param overlap estimation of the two clouds overlap rate
\param nbBases number of iteration for the algorithm
\param nbTries number of tries to find a base in the reference cloud
\param progressCb the client application can get some notification of the process progress through this callback mechanism (see GenericProgressCallback)
\param nbMaxCandidates if>0, maximal number of candidate bases allowed for each step. Otherwise the number of candidates is not bounded
\return false: failure ; true: success.
**/
static bool RegisterClouds( GenericIndexedCloud* modelCloud,
GenericIndexedCloud* dataCloud,
ScaledTransformation& transform,
ScalarType delta,
ScalarType beta,
PointCoordinateType overlap,
unsigned nbBases,
unsigned nbTries,
GenericProgressCallback* progressCb = nullptr,
unsigned nbMaxCandidates = 0);
}
