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.
 
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::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;
readObservations("file.txt", kc);
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;
readObservations("file.txt", kc);
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

Partial View Iterator type.

See partialViewBegin().

Definition at line 491 of file KernelCollection.h.

Sample Iterator type.

See sampleBegin().

Definition at line 256 of file KernelCollection.h.

typedef nuklei_trsl::reorder_iterator<const_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<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.

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.

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.

References add(), and sampleBegin().

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:
© Copyright 2007-2013 Renaud Detry.
Distributed under the terms of the GNU General Public License (GPL).
(See accompanying file LICENSE.txt or copy at http://www.gnu.org/copyleft/gpl.html.)
Revised Fri Feb 6 2015 13:51:54.
SourceForge.net Logo