nuklei::KernelCollection Class Reference

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.

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 writeMeshToPlyFile (const std::string &filename) const

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)

const kernel::baserandomKernel () 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 boost::serialization::access

## Detailed Description

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.

# Intermediary Results

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,

using namespace nuklei;
kc.computeKernelStatistics(); // kernel statistics stored internally
kc.buildKdTree(); // position kd-tree stored internally
... // choose a value for k
double e = kc.evaluationAt(k); // evaluationAt makes use of intermediary
// results

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():

using namespace nuklei;
kc.computeKernelStatistics();
kc.buildKdTree();
... // choose a value for k
double e = kc.evaluationAt(k); // ok!
i != as_const(kc).end(); ++i)
{
i->setLocH(10);
}
double e = kc.evaluationAt(k); // ok!
// In the following line, even though i is a const_iterator, kc.begin()
// calls the non-const begin() method, which destroys intermediary results.
i != kc.end(); ++i)
{
i->setLocH(10);
}
double e = kc.evaluationAt(k); // throws exception: no kernel statistics,
// no kd-tree.

If the intermediary results that a method requires have not been computed, the method throws an exception.

# Sample Iterators, Sort Iterators

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:

i != i.end(); ++i) // note i.end() instead of kc.end()
{
// *i returns a reference to a datapoint/kernel of kc
// i.index() returns the index (in kc) of that element.
}
i != i.end(); ++i) // note i.end() instead of kc.end()
{
// *i returns a reference to a datapoint/kernel of kc
// i.index() returns the index (in kc) of that element.
}

These iterators are implemented with the TRSL library. Refer to the doc of TRSL for more information.

Examples:
kde_evaluate.cpp, kde_sample.cpp, and klr_classify.cpp.

Definition at line 153 of file KernelCollection.h.

## Member Typedef Documentation

 typedef nuklei_trsl::reorder_iterator nuklei::KernelCollection::const_partialview_iterator

Partial View Iterator type.

Definition at line 491 of file KernelCollection.h.

 typedef nuklei_trsl::ppfilter_iterator< is_picked, const_iterator> nuklei::KernelCollection::const_sample_iterator

Sample Iterator type.

See sampleBegin().

Definition at line 256 of file KernelCollection.h.

 typedef nuklei_trsl::reorder_iterator nuklei::KernelCollection::const_sort_iterator

Sort Iterator type.

See sortBegin().

Definition at line 297 of file KernelCollection.h.

 typedef nuklei_trsl::ppfilter_iterator< is_picked, iterator> nuklei::KernelCollection::sample_iterator

Sample Iterator type.

See sampleBegin().

Definition at line 249 of file KernelCollection.h.

 typedef nuklei_trsl::reorder_iterator nuklei::KernelCollection::sort_iterator

Sort Iterator type.

See sortBegin().

Definition at line 291 of file KernelCollection.h.

## Member Function Documentation

 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".

Examples:
kde_sample.cpp.

Definition at line 139 of file KernelCollection.cpp.

Referenced by buildPartialViewCache(), and normalizeWeights().

 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.

 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.

Examples:
kde_evaluate.cpp.

Definition at line 235 of file KernelCollectionKDTree.cpp.

References NUKLEI_ASSERT, NUKLEI_THROW, and nuklei::kernel::base::polyType().

 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 143 of file KernelCollectionPartialView.cpp.

References NUKLEI_THROW.

 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.

References nuklei::kernel::base::getLoc(), and NUKLEI_THROW.

 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.

References begin(), end(), nuklei::kernel::se3::loc_, and NUKLEI_THROW.

 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.

References NUKLEI_ASSERT, and NUKLEI_THROW.

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.

References mean().

Referenced by mean().

 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 184 of file KernelCollectionPartialView.cpp.

References nuklei::as_const(), begin(), end(), and NUKLEI_THROW.

 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 258 of file KernelCollectionPartialView.cpp.

References begin(), and NUKLEI_THROW.

 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.

References empty(), NUKLEI_ASSERT, and sampleBegin().

Referenced by buildPartialViewCache().

 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.

References at(), begin(), end(), NUKLEI_ASSERT, NUKLEI_THROW, size(), and nuklei::Random::uniformInt().

 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.

Examples:
kde_sample.cpp.

Definition at line 277 of file KernelCollection.cpp.

Referenced by resetWithSampleOf().

 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().

Referenced by randomKernel(), and sample().

 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.

Examples:
kde_evaluate.cpp, kde_sample.cpp, and klr_classify.cpp.

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.

References begin(), and end().

 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.

References begin(), and end().

 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.

References NUKLEI_THROW.

Referenced by sampleBegin().

The documentation for this class was generated from the following files: