This class acts as a vector-like container for kernels. It also provides methods related to kernel density estimation. More...
#include <KernelCollection.h>
Public Types | |
| enum | EvaluationStrategy { SUM_EVAL, MAX_EVAL, WEIGHTED_SUM_EVAL } |
| typedef boost::ptr_vector< kernel::base > | Container |
| Kernel container type. | |
| typedef Container::iterator | iterator |
| KernelCollection iterator. | |
| typedef Container::const_iterator | const_iterator |
| KernelCollection iterator. | |
| typedef Container::reverse_iterator | reverse_iterator |
| KernelCollection iterator. | |
| typedef Container::const_reverse_iterator | const_reverse_iterator |
| KernelCollection iterator. | |
| typedef nuklei_trsl::is_picked_systematic< kernel::base, weight_t, kernel::base::WeightAccessor > | is_picked |
| Used internally. | |
| typedef nuklei_trsl::ppfilter_iterator< is_picked, iterator > | sample_iterator |
| Sample Iterator type. More... | |
| typedef nuklei_trsl::ppfilter_iterator< is_picked, const_iterator > | const_sample_iterator |
| Sample Iterator type. More... | |
| typedef nuklei_trsl::reorder_iterator< iterator > | sort_iterator |
| Sort Iterator type. More... | |
| typedef nuklei_trsl::reorder_iterator< const_iterator > | const_sort_iterator |
| Sort Iterator type. More... | |
| typedef nuklei_trsl::reorder_iterator< const_iterator > | const_partialview_iterator |
| Partial View Iterator type. More... | |
Public Member Functions | |
| void | assertConsistency () const |
| Container::reference | at (Container::size_type n) |
Returns the kernel at index n. | |
| Container::const_reference | at (Container::size_type n) const |
Returns the kernel at index n. | |
| Container::reference | front () |
Returns the kernel at index 0. | |
| Container::const_reference | front () const |
Returns the kernel at index 0. | |
| Container::reference | back () |
| Returns the kernel at index size()-1. | |
| Container::const_reference | back () const |
| Returns the kernel at index size()-1. | |
| Container::size_type | size () const |
| Returns the number of kernels. | |
| bool | empty () const |
| Returns true if empty. | |
| Container::iterator | begin () |
| Returns an iterator pointing to the first kernel. | |
| Container::const_iterator | begin () const |
| Returns an iterator pointing to the first kernel. | |
| Container::iterator | end () |
| Returns an iterator pointing to the last kernel. | |
| Container::const_iterator | end () const |
| Returns an iterator pointing to the last kernel. | |
| Container::reverse_iterator | rbegin () |
| Returns an reverse iterator pointing to the last kernel. | |
| Container::const_reverse_iterator | rbegin () const |
| Returns an reverse iterator pointing to the last kernel. | |
| Container::reverse_iterator | rend () |
| Returns an reverse iterator pointing to the first kernel. | |
| Container::const_reverse_iterator | rend () const |
| Returns an reverse iterator pointing to the first kernel. | |
| void | clear () |
| Resets the class to its initial state. | |
| void | add (const kernel::base &f) |
Adds a copy of f. | |
| void | add (const KernelCollection &kv) |
Adds a copy of the kernels contained in kv. | |
| void | replace (const size_t idx, const kernel::base &k) |
Replaces the idx'th kernel with a copy of k. | |
| kernel::base::Type | kernelType () const |
| sample_iterator | sampleBegin (size_t sampleSize) |
Returns an iterator that iterates through sampleSize kernels selected randomly. More... | |
| const_sample_iterator | sampleBegin (size_t sampleSize) const |
Returns an iterator that iterates through sampleSize kernels. More... | |
| sort_iterator | sortBegin (size_t sortSize) |
Returns an iterator that iterates through the sortSize kernels of highest weight, in order of decreasing weight. More... | |
| const_sort_iterator | sortBegin (size_t sortSize) const |
Returns an iterator that iterates through the sortSize kernels of highest weight, in order of decreasing weight. More... | |
| void | computeKernelStatistics () |
| Computes the sum of all kernel weights (total weight), and the maximum kernel cut point. More... | |
| weight_t | totalWeight () const |
| Returns the sum of kernel weights. More... | |
| coord_t | maxLocCutPoint () const |
| void | normalizeWeights () |
| Divides all weights by the total weight. | |
| void | uniformizeWeights () |
| Sets all weights to \( 1 / t \), where \( t \) is the total weight of the collection. | |
| kernel::base::ptr | mean () const |
| Returns a kernel holding the mean position and orientation of the data. | |
| kernel::base::ptr | moments () const |
| Returns a kernel holding the mean and standard deviation in position and orientation of the data. More... | |
| void | transformWith (const kernel::se3 &t) |
Transforms the data with t. | |
| void | transformWith (const Vector3 &translation, const Quaternion &rotation) |
| Transforms the data with the provided translation and rotation. | |
| boost::tuple< Matrix3, Vector3, coord_t > | localLocationDifferential (const Vector3 &k) const |
Computes the local differential properties of the nearest neighbors of k. More... | |
| kernel::se3 | linearLeastSquarePlaneFit () const |
Fits a plane to the positions of the kernels contained in *this. More... | |
| kernel::se3 | ransacPlaneFit (coord_t inlinerThreshold, unsigned nSeeds=100) const |
Fits a plane to the positions of the kernels contained in *this. More... | |
| std::vector< Vector3 > | get3DPointCloud () const |
| Returns the locations of the contained kernels in an std::vector. | |
| void | computeSurfaceNormals () |
| Computes surface normals at all points. After running this method, all kernels are nuklei::kernel::r3xs2p. More... | |
| void | buildKdTree () |
| Builds a kd-tree of the kernel positions and stores the tree internally. See Intermediary Results. | |
| void | buildNeighborSearchTree () |
| Builds a neighbor search tree of the kernel positions and stores the tree internally. See Intermediary Results. | |
| void | buildConvexHull (unsigned n) |
| Builds the convex hull of kernel positions and stores the hull internally. See Intermediary Results. | |
| bool | isWithinConvexHull (const kernel::base &k) const |
Check if k is within the convex hull of contained kernel positions. More... | |
| void | buildMesh () |
| Builds a mesh from kernel positions. See Intermediary Results. | |
| void | writeMeshToOffFile (const std::string &filename) const |
| void | readMeshFromOffFile (const std::string &filename) |
| void | writeMeshToPlyFile (const std::string &filename) const |
| void | readMeshFromPlyFile (const std::string &filename) |
| void | buildPartialViewCache (const double meshTol, const bool useRayToSurfacenormalAngle=false) |
| Builds set of partial views of the object. See Intermediary Results. | |
| bool | isVisibleFrom (const Vector3 &p, const Vector3 &viewpoint, const coord_t &tolerance=FLOATTOL) const |
Assuming that the points in this collection form the surface of an object, this function computes whether a point p is visible from viewpoint, or if it is occluded by the object. More... | |
| bool | isVisibleFrom (const kernel::r3xs2p &p, const Vector3 &viewpoint, const coord_t &tolerance=FLOATTOL) const |
| Same as isVisibleFrom(), but additionally checks that the ray-to-surfacenormal angle is small enough. | |
| std::vector< int > | partialView (const Vector3 &viewpoint, const coord_t &tolerance=FLOATTOL, const bool useViewcache=false, const bool useRayToSurfacenormalAngle=false) const |
Assuming that the points in this collection form the surface of an object, this function returns the indices of points visible from viewpoint. More... | |
| const_partialview_iterator | partialViewBegin (const Vector3 &viewpoint, const coord_t &tolerance=FLOATTOL, const bool useViewcache=false, const bool useRayToSurfacenormalAngle=false) const |
Assuming that the points in this collection form the surface of an object, this function returns an iterator that iterates through the kernels that are visible from viewpoint. More... | |
| KernelCollection | sample (int sampleSize) const |
Returns sampleSize samples from the density modeled by *this. More... | |
| void | resetWithSampleOf (const KernelCollection &kc, int sampleSize) |
| Deprecated. Use sample() instead. | |
| const kernel::base & | randomKernel () const |
| Returns a kernel from the collection. More... | |
| void | setKernelLocH (coord_t h) |
| Sets the location bandwidth of all kernels. | |
| void | setKernelOriH (coord_t h) |
| Sets the orientation bandwidth of all kernels. More... | |
| weight_t | evaluationAt (const kernel::base &f, const EvaluationStrategy strategy=WEIGHTED_SUM_EVAL) const |
Evaluates the density represented by *this at f. More... | |
| void | clearDescriptors () |
| void | setFlag (const bitfield_t flag) |
Friends | |
| class | NUKLEI_SERIALIZATION_FRIEND_CLASSNAME |
This class acts as a vector-like container for kernels. It also provides methods related to kernel density estimation.
The KDE-related functions of this class are discussed in Kernel Density Estimation.
Note: In Nuklei, the kernel classes (kernel::base and its descendants) play the double role of representing kernels and points. For instance, there is no class specifically designed for holding an \( SE(3) \) point, the class kernel::se3 is used for that purpose. A KernelCollection is thus often used to contain a set of points that are entirely unrelated to a density function.
Some of the methods of this class can benefit from caching intermediary results. For instance, the evaluationAt() method requires a \(k\)d-tree of all kernel positions. \(k\)d-trees are expensive to construct, it is important to avoid reconstructing them in each call of evaluationAt().
KernelCollection provides methods for precomputing intermediary results, such as \(k\)d-trees. These structures are stored internally. For instance,
The functions responsible for computing intermediary results are:
When a KernelCollection is modified, intermediary results become invalid. To avoid inconsistencies, each call to a KernelCollection method which can potentially allow one to modify the contained kernels (for instance, add()) automatically destroys all intermediary results. In order to preserve intermediary results, one has to be careful to avoid calling these methods. In particular, several methods, such as front() and front()const, or begin() and begin()const, have a const and a non-const version. The const methods will always preserve intermediary results, while the non-const methods are likely to destroy them. One can force a call to the const version with as_const():
If the intermediary results that a method requires have not been computed, the method throws an exception.
KernelCollection provides iterators over a random permutation of its elements (sampleBegin()), and over a sorted permutation of its elements (sortBegin()). One will note that KernelCollection does not provide sampleEnd() or sortEnd() methods. Ends are provided by the iterators themselves, and should be accessed as follows:
These iterators are implemented with the TRSL library. Refer to the doc of TRSL for more information.
Definition at line 153 of file KernelCollection.h.
| typedef nuklei_trsl::reorder_iterator<const_iterator> nuklei::KernelCollection::const_partialview_iterator |
Partial View Iterator type.
See partialViewBegin().
Definition at line 491 of file KernelCollection.h.
| typedef nuklei_trsl::ppfilter_iterator< is_picked, const_iterator> nuklei::KernelCollection::const_sample_iterator |
| typedef nuklei_trsl::reorder_iterator<const_iterator> nuklei::KernelCollection::const_sort_iterator |
| typedef nuklei_trsl::ppfilter_iterator< is_picked, iterator> nuklei::KernelCollection::sample_iterator |
| typedef nuklei_trsl::reorder_iterator<iterator> nuklei::KernelCollection::sort_iterator |
| void nuklei::KernelCollection::computeKernelStatistics | ( | ) |
Computes the sum of all kernel weights (total weight), and the maximum kernel cut point.
See Kernel Density Estimation for an explanation of "cut point".
Definition at line 139 of file KernelCollection.cpp.
| void nuklei::KernelCollection::computeSurfaceNormals | ( | ) |
Computes surface normals at all points. After running this method, all kernels are nuklei::kernel::r3xs2p.
The orientations/directions that may be associated to the kernels prior to calling this method are ignored and replaced with the normals computed from local neighbors.
This function requires a neighbor search tree. Its call must thus be preceded by a call to buildNeighborSearchTree(). See Intermediary Results.
Definition at line 100 of file KernelCollectionJetFitting.cpp.
References add(), nuklei::as_const(), localLocationDifferential(), NUKLEI_THROW, and nuklei::kernel::base::setWeight().
| weight_t nuklei::KernelCollection::evaluationAt | ( | const kernel::base & | f, |
| const EvaluationStrategy | strategy = WEIGHTED_SUM_EVAL |
||
| ) | const |
Evaluates the density represented by *this at f.
See Kernel Density Estimation for a description of this method.
Precede by a call to computeKernelStatistics() and buildKdTree(). See Intermediary Results.
Definition at line 235 of file KernelCollectionKDTree.cpp.
| bool nuklei::KernelCollection::isVisibleFrom | ( | const Vector3 & | p, |
| const Vector3 & | viewpoint, | ||
| const coord_t & | tolerance = FLOATTOL |
||
| ) | const |
Assuming that the points in this collection form the surface of an object, this function computes whether a point p is visible from viewpoint, or if it is occluded by the object.
This function requires prior computation of a surface mesh from the points of the collection. See buildMesh().
This function computes whether a segment linking viewpoint to p intersects with the mesh.
If tolerance is greater than 0, the function computes whether a segment linking viewpoint to
\[ viewpoint + (p - viewpoint) \frac{|p-viewpoint|-tolerance}{|p-viewpoint|} \]
intersects with the mesh.
Definition at line 153 of file KernelCollectionPartialView.cpp.
| bool nuklei::KernelCollection::isWithinConvexHull | ( | const kernel::base & | k | ) | const |
Check if k is within the convex hull of contained kernel positions.
Precede by a call to buildConvexHull(). See Intermediary Results.
Definition at line 42 of file KernelCollectionConvexHull.cpp.
| kernel::se3 nuklei::KernelCollection::linearLeastSquarePlaneFit | ( | ) | const |
Fits a plane to the positions of the kernels contained in *this.
The location of the returned kernel is a point of the plane. The orientation of the returned kernel is such that its \( z \) axis is normal to the plane.
Definition at line 14 of file KernelCollectionPCA.cpp.
| boost::tuple< Matrix3, Vector3, coord_t > nuklei::KernelCollection::localLocationDifferential | ( | const Vector3 & | k | ) | const |
Computes the local differential properties of the nearest neighbors of k.
This function requires a neighbor search tree. Its call must thus be preceded by a call to buildNeighborSearchTree(). See Intermediary Results.
This function uses the CGAL Monge fit functions.
Definition at line 34 of file KernelCollectionJetFitting.cpp.
Referenced by computeSurfaceNormals().
| kernel::base::ptr nuklei::KernelCollection::moments | ( | ) | const |
Returns a kernel holding the mean and standard deviation in position and orientation of the data.
Standard deviations for position and orientation are stored in the kernel bandwidths.
Definition at line 240 of file KernelCollection.cpp.
| std::vector< int > nuklei::KernelCollection::partialView | ( | const Vector3 & | viewpoint, |
| const coord_t & | tolerance = FLOATTOL, |
||
| const bool | useViewcache = false, |
||
| const bool | useRayToSurfacenormalAngle = false |
||
| ) | const |
Assuming that the points in this collection form the surface of an object, this function returns the indices of points visible from viewpoint.
See isVisibleFrom() for more details.
Definition at line 253 of file KernelCollectionPartialView.cpp.
| KernelCollection::const_partialview_iterator nuklei::KernelCollection::partialViewBegin | ( | const Vector3 & | viewpoint, |
| const coord_t & | tolerance = FLOATTOL, |
||
| const bool | useViewcache = false, |
||
| const bool | useRayToSurfacenormalAngle = false |
||
| ) | const |
Assuming that the points in this collection form the surface of an object, this function returns an iterator that iterates through the kernels that are visible from viewpoint.
See isVisibleFrom() for more details.
See Sample Iterators, Sort Iterators for more details.
Definition at line 268 of file KernelCollectionPartialView.cpp.
| const kernel::base & nuklei::KernelCollection::randomKernel | ( | ) | const |
Returns a kernel from the collection.
The probability of returning the \( i^{\rm th} \) kernel is proportional to the weight of that kernel. This methods is \( O(n) \), where \( n \) is the number of kernels contained in the collection. To efficiently select multiple kernels randomly, use sampleBegin().
Definition at line 301 of file KernelCollection.cpp.
| kernel::se3 nuklei::KernelCollection::ransacPlaneFit | ( | coord_t | inlinerThreshold, |
| unsigned | nSeeds = 100 |
||
| ) | const |
Fits a plane to the positions of the kernels contained in *this.
The location of the returned kernel is a point of the plane. The orientation of the returned kernel is such that its \( z \) axis is normal to the plane.
Definition at line 60 of file KernelCollectionPCA.cpp.
| KernelCollection nuklei::KernelCollection::sample | ( | int | sampleSize | ) | const |
Returns sampleSize samples from the density modeled by *this.
See Kernel Density Estimation for a description of this method.
Precede by a call to computeKernelStatistics(). See Intermediary Results.
Definition at line 277 of file KernelCollection.cpp.
| KernelCollection::sample_iterator nuklei::KernelCollection::sampleBegin | ( | size_t | sampleSize | ) |
Returns an iterator that iterates through sampleSize kernels selected randomly.
Iterates through sampleSize kernels. The probability that a kernel is selected is proportional to its weight: The probability that the \( i^{th} \) kernel returned by the iterator is the \( l^{th} \) kernel of the KernelCollection is proportional to the weight of the \( l^{th} \) kernel, as
\[ P(i = \ell) \propto w_{\ell}. \]
This iterator does not return samples of the density! It returns a random subset of the kernels. To get samples from the density, one needs to get exactly one sample from each kernel returned by the iterator.
See Sample Iterators, Sort Iterators for more details.
This method runs in \( O(n+\textrm{sampleSize}) \) time, where \( n \) is the number of kernels in the collection.
Definition at line 106 of file KernelCollection.cpp.
References begin(), end(), and totalWeight().
| KernelCollection::const_sample_iterator nuklei::KernelCollection::sampleBegin | ( | size_t | sampleSize | ) | const |
Returns an iterator that iterates through sampleSize kernels.
This is the const version of sampleBegin().
Definition at line 117 of file KernelCollection.cpp.
References begin(), end(), and totalWeight().
| void nuklei::KernelCollection::setKernelOriH | ( | coord_t | h | ) |
Sets the orientation bandwidth of all kernels.
This method calls kernel::base::setOriH on all kernels. If the kernels do not have an orientation, this method does nothing.
Definition at line 320 of file KernelCollection.cpp.
| KernelCollection::sort_iterator nuklei::KernelCollection::sortBegin | ( | size_t | sortSize | ) |
Returns an iterator that iterates through the sortSize kernels of highest weight, in order of decreasing weight.
See Sample Iterators, Sort Iterators for more details.
Definition at line 124 of file KernelCollection.cpp.
| KernelCollection::const_sort_iterator nuklei::KernelCollection::sortBegin | ( | size_t | sortSize | ) | const |
Returns an iterator that iterates through the sortSize kernels of highest weight, in order of decreasing weight.
This is the const version of sortBegin().
Definition at line 132 of file KernelCollection.cpp.
| weight_t nuklei::KernelCollection::totalWeight | ( | ) | const |
Returns the sum of kernel weights.
Precede by a call to computeKernelStatistics(). See Intermediary Results.
Definition at line 152 of file KernelCollection.cpp.
Referenced by sampleBegin().