PCL
pcl::KernelFilter Class Reference

Kernel filter in two dimensions. More...

#include <KernelFilter.h>

+ Inheritance diagram for pcl::KernelFilter:

Public Types

using coefficient = float
 
using coefficient_matrix = GenericMatrix< coefficient >
 

Public Member Functions

 KernelFilter (const coefficient_matrix &F, const String &name=String())
 
 KernelFilter (const KernelFilter &)=default
 
 KernelFilter (const String &name=String())
 
template<typename T >
 KernelFilter (const T *k, int n, const String &name=String())
 
 KernelFilter (int n, const String &name=String())
 
template<typename T >
 KernelFilter (int n, const T &x, const String &name=String())
 
 KernelFilter (KernelFilter &&)=default
 
virtual ~KernelFilter ()
 
virtual SeparableFilter AsSeparableFilter (float tolerance=__PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE) const
 
const coefficientBegin () const
 
const coefficientbegin () const
 
virtual void Clear ()
 
virtual KernelFilterClone () const
 
coefficient_matrix Coefficients () const
 
const coefficientEnd () const
 
const coefficientend () const
 
void Flip ()
 
KernelFilter Flipped () const
 
bool IsEmpty () const
 
bool IsFlipped () const
 
bool IsHighPassFilter () const
 
virtual bool IsSeparable () const
 
double Modulus () const
 
String Name () const
 
void Normalize ()
 
KernelFilter Normalized () const
 
int NumberOfCoefficients () const
 
 operator bool () const
 
KernelFilteroperator= (const coefficient &x)
 
KernelFilteroperator= (const coefficient_matrix &F)
 
KernelFilteroperator= (const KernelFilter &)=default
 
KernelFilteroperator= (KernelFilter &&)=default
 
bool operator== (const KernelFilter &f) const
 
const coefficientoperator[] (int row) const
 
virtual void Rename (const String &newName)
 
virtual void Resize (int n)
 
bool SameCoefficients (const KernelFilter &f) const
 
int Size () const
 
template<class P >
void ToImage (GenericImage< P > &image) const
 
void ToImage (ImageVariant &v) const
 
double Weight () const
 

Detailed Description

KernelFilter stores a square matrix of floating point filter coefficients and an optional filter name. This class provides automatic allocation and deallocation of coefficients, implicit data sharing, thread-safe access and a number of utility functions for filter management.

KernelFilter can be used along with a variety of PCL classes, such as Convolution and ATrousWaveletTransform.

For separable filters and convolutions, see the SeparableFilter and SeparableConvolution PCL classes.

See also
GaussianFilter, VariableShapeFilter, Convolution, ATrousWaveletTransform

Definition at line 89 of file KernelFilter.h.

Member Typedef Documentation

◆ coefficient

Represents a filter coefficient.

Definition at line 96 of file KernelFilter.h.

◆ coefficient_matrix

Represents a filter coefficient matrix.

Definition at line 101 of file KernelFilter.h.

Constructor & Destructor Documentation

◆ KernelFilter() [1/7]

pcl::KernelFilter::KernelFilter ( const String name = String())
inline

Constructs an empty KernelFilter object with optional name.

Definition at line 106 of file KernelFilter.h.

◆ KernelFilter() [2/7]

pcl::KernelFilter::KernelFilter ( int  n,
const String name = String() 
)
inline

Constructs a KernelFilter object with the specified size n and optional name. Filter elements are not initialized, so they will contain unpredictable values.

A KernelFilter object must be initialized with either a zero size (which yields an empty filter), or an odd size >= 3.

Definition at line 119 of file KernelFilter.h.

◆ KernelFilter() [3/7]

template<typename T >
pcl::KernelFilter::KernelFilter ( int  n,
const T &  x,
const String name = String() 
)
inline

Constructs a KernelFilter object with the specified size n, initial element value x, and optional name.

Definition at line 132 of file KernelFilter.h.

◆ KernelFilter() [4/7]

pcl::KernelFilter::KernelFilter ( const coefficient_matrix F,
const String name = String() 
)
inline

Constructs a KernelFilter object with the specified filter coefficient matrix F and optional name.

Definition at line 144 of file KernelFilter.h.

◆ KernelFilter() [5/7]

template<typename T >
pcl::KernelFilter::KernelFilter ( const T *  k,
int  n,
const String name = String() 
)
inline

Constructs a KernelFilter object with the specified size n and optional name. Copies nxn filter coefficients from the specified static array k.

Definition at line 158 of file KernelFilter.h.

◆ KernelFilter() [6/7]

pcl::KernelFilter::KernelFilter ( const KernelFilter )
default

Copy constructor.

◆ KernelFilter() [7/7]

pcl::KernelFilter::KernelFilter ( KernelFilter &&  )
default

Move constructor.

◆ ~KernelFilter()

virtual pcl::KernelFilter::~KernelFilter ( )
inlinevirtual

Virtual destructor.

Definition at line 179 of file KernelFilter.h.

Member Function Documentation

◆ AsSeparableFilter()

virtual SeparableFilter pcl::KernelFilter::AsSeparableFilter ( float  tolerance = __PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE) const
virtual

Returns a separable filter equivalent to this kernel filter matrix.

The default implementation computes the singular value decomposition of the filter matrix, which yields the separable filter as a couple of row and column vectors. Filter separability is then verified by computing the resulting filter by matrix multiplication of the separable filter components. If the resulting filter differs by more than the specified tolerance from the original, then the filter is non-separable and an empty SeparableFilter object is returned.

For known separable filters, this member function must be reimplemented in derived classes to bypass the default (and expensive) separability tests. For example, Gaussian filters are separable, so this function is conveniently reimplemented by the GaussianFilter class to return a separable filter consisting of the central row and column vectors of the Gaussian filter matrix representation.

Reimplemented in pcl::VariableShapeFilter, pcl::MoffatFilter, pcl::GaussianFilter, and pcl::MeanFilter.

◆ Begin()

const coefficient* pcl::KernelFilter::Begin ( ) const
inline

Returns a pointer to the beginning of the internal matrix of (immutable) filter coefficients.

All filter coefficients are guaranteed to be stored at consecutive locations addressable from the pointer returned by this function. Filter coefficients are stored in row order (all coefficients of row 0 followed by all coefficients of row 1, and so on).

Definition at line 365 of file KernelFilter.h.

◆ begin()

const coefficient* pcl::KernelFilter::begin ( ) const
inline

STL-compatible iteration. Equivalent to Begin() const.

Definition at line 389 of file KernelFilter.h.

◆ Clear()

virtual void pcl::KernelFilter::Clear ( )
inlinevirtual

Deallocates filter coefficients and yields an empy KernelFilter object. Note that this member function does not change the current filter name.

Definition at line 519 of file KernelFilter.h.

◆ Clone()

virtual KernelFilter* pcl::KernelFilter::Clone ( ) const
inlinevirtual

Returns a pointer to a dynamically allocated duplicate of this kernel filter.

Note
All derived classes from KernelFilter must reimplement this virtual member function.

Reimplemented in pcl::VariableShapeFilter, pcl::MoffatFilter, pcl::GaussianFilter, pcl::MeanFilter, and pcl::LinearFilter.

Definition at line 190 of file KernelFilter.h.

Referenced by pcl::ATrousWaveletTransform::WaveletScalingFunction::Set(), pcl::Convolution::SetFilter(), pcl::FFTConvolution::SetFilter(), and pcl::ATrousWaveletTransform::WaveletScalingFunction::WaveletScalingFunction().

◆ Coefficients()

coefficient_matrix pcl::KernelFilter::Coefficients ( ) const
inline

Returns a copy of the internal matrix of filter coefficients.

Definition at line 351 of file KernelFilter.h.

◆ End()

const coefficient* pcl::KernelFilter::End ( ) const
inline

Returns a pointer to the end of the internal matrix of (immutable) filter coefficients.

All filter coefficients are guaranteed to be stored at consecutive locations in reverse order, addressable from the pointer returned by this function minus one. Filter coefficients are stored in row order (all coefficients of row 0 followed by all coefficients of row 1, etc.).

Definition at line 380 of file KernelFilter.h.

◆ end()

const coefficient* pcl::KernelFilter::end ( ) const
inline

STL-compatible iteration. Equivalent to End() const.

Definition at line 397 of file KernelFilter.h.

◆ Flip()

void pcl::KernelFilter::Flip ( )
inline

Flips this kernel filter. Flipping a filter consists of rotating its coefficients by 180 degrees.

Definition at line 458 of file KernelFilter.h.

Referenced by Flipped().

◆ Flipped()

KernelFilter pcl::KernelFilter::Flipped ( ) const
inline

Returns a flipped copy of this filter. Flipping a filter consists of rotating its coefficients by 180 degrees.

Definition at line 468 of file KernelFilter.h.

References Flip().

◆ IsEmpty()

bool pcl::KernelFilter::IsEmpty ( ) const
inline

Returns true iff this is an empty filter, that is, if it has no filter coefficients.

Definition at line 327 of file KernelFilter.h.

◆ IsFlipped()

bool pcl::KernelFilter::IsFlipped ( ) const
inline

Returns true iff this kernel filter has been flipped (rotated by 180 degrees). Note that after an even number of successive flippings (which is a no-op) this member function will return false.

Definition at line 480 of file KernelFilter.h.

◆ IsHighPassFilter()

bool pcl::KernelFilter::IsHighPassFilter ( ) const
inline

Returns true if this is a high-pass kernel filter; false if this is a low-pass kernel filter.

A high-pass kernel filter has one or more negative coefficients. A low-pass kernel filter is either empty or all of its coefficients are positive or zero.

Definition at line 493 of file KernelFilter.h.

◆ IsSeparable()

virtual bool pcl::KernelFilter::IsSeparable ( ) const
inlinevirtual

Returns true iff this filter is separable,

A two-dimensional filter matrix is separable if it can be expressed as the product of two vectors. The default implementation of this function tries to compute a separable filter by calling AsSeparable(). Then it returns true if the computed separable filter is nonempty.

For known separable (and non-separable) filters, this member function must be reimplemented in derived classes to bypass the above, expensive procedure.

Reimplemented in pcl::VariableShapeFilter, pcl::GaussianFilter, pcl::MoffatFilter, and pcl::MeanFilter.

Definition at line 227 of file KernelFilter.h.

◆ Modulus()

double pcl::KernelFilter::Modulus ( ) const
inline

Returns the sum of the absolute values of all filter coefficients.

Definition at line 425 of file KernelFilter.h.

◆ Name()

String pcl::KernelFilter::Name ( ) const
inline

Returns the name of this KernelFilter object.

Definition at line 283 of file KernelFilter.h.

Referenced by operator==().

◆ Normalize()

void pcl::KernelFilter::Normalize ( )
inline

Normalizes filter coefficients. Divides each filter coefficient by the result of the Modulus() member function. If Modulus() is zero or insignificant this function does nothing.

Definition at line 435 of file KernelFilter.h.

References pcl::Modulus().

Referenced by Normalized().

◆ Normalized()

KernelFilter pcl::KernelFilter::Normalized ( ) const
inline

Returns the normalization of this kernel filter. This member function creates a new KernelFilter instance as a copy of this object, normalizes it, and returns it.

Definition at line 447 of file KernelFilter.h.

References Normalize().

◆ NumberOfCoefficients()

int pcl::KernelFilter::NumberOfCoefficients ( ) const
inline

Returns the total number of filter coefficients, or Size()*Size().

Definition at line 343 of file KernelFilter.h.

◆ operator bool()

pcl::KernelFilter::operator bool ( ) const
inline

Returns true iff this is a non-empty filter. Equivalent to !IsEmpty().

Definition at line 335 of file KernelFilter.h.

◆ operator=() [1/4]

KernelFilter& pcl::KernelFilter::operator= ( const coefficient x)
inline

Assigns the specified scalar x to all filter coefficients. Returns a reference to this object.

Definition at line 263 of file KernelFilter.h.

◆ operator=() [2/4]

KernelFilter& pcl::KernelFilter::operator= ( const coefficient_matrix F)
inline

Assigns the specified filter coefficient matrix F to this object. Returns a reference to this object.

The specified matrix F must be either an empty matrix or a square matrix of odd size. If these conditions are not met, this member function throws an Error exception.

Definition at line 250 of file KernelFilter.h.

◆ operator=() [3/4]

KernelFilter& pcl::KernelFilter::operator= ( const KernelFilter )
default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [4/4]

KernelFilter& pcl::KernelFilter::operator= ( KernelFilter &&  )
default

Move assignment operator. Returns a reference to this object.

◆ operator==()

bool pcl::KernelFilter::operator== ( const KernelFilter f) const
inline

Returns true iff this KernelFilter object is equal to another instance f. Two KernelFilter instances are equal if their name and filter coefficients are equal.

Definition at line 275 of file KernelFilter.h.

References pcl::ColorSpace::Name(), and Name().

◆ operator[]()

const coefficient* pcl::KernelFilter::operator[] ( int  row) const
inline

Subscript operator. Returns a pointer to the first (immutable) filter coefficient of the specified row in this filter. row must be a valid vertical index: it must be 0 <= row < Size().

Definition at line 408 of file KernelFilter.h.

◆ Rename()

virtual void pcl::KernelFilter::Rename ( const String newName)
inlinevirtual

Sets the name of this KernelFilter object.

Definition at line 291 of file KernelFilter.h.

◆ Resize()

virtual void pcl::KernelFilter::Resize ( int  n)
inlinevirtual

Sets the size of this filter kernel. Previous filter contents are lost; the internal matrix of filter coefficients will contain unpredictable values after calling this function.

Reimplemented in pcl::VariableShapeFilter, pcl::MoffatFilter, pcl::GaussianFilter, pcl::LinearFilter, and pcl::MeanFilter.

Definition at line 309 of file KernelFilter.h.

Referenced by pcl::LinearFilter::Resize().

◆ SameCoefficients()

bool pcl::KernelFilter::SameCoefficients ( const KernelFilter f) const
inline

Returns true iff this KernelFilter object has the same coefficients as other instance f.

Definition at line 510 of file KernelFilter.h.

◆ Size()

int pcl::KernelFilter::Size ( ) const
inline

Returns the size of this filter kernel.

Definition at line 299 of file KernelFilter.h.

◆ ToImage() [1/2]

template<class P >
void pcl::KernelFilter::ToImage ( GenericImage< P > &  image) const
inline

Renders this filter as an image. The contents of the specified target image will be replaced with a grayscale rendition of this filter, where each image pixel has a value proportional to its corresponding filter coefficient counterpart.

Note that if this filter has out-of-range values for the pixel sample type of the target image, pixel saturation will occur at either the white or black points, or at both. This only happens when the target image is of an integer type and this filter contains floating point values outside the normalized [0,1] range.

If the target image is of a floating-point type (either real or complex), it may require a rescaling or normalization operation to constrain all pixel values to the normalized [0,1] range after calling this function.

Definition at line 544 of file KernelFilter.h.

◆ ToImage() [2/2]

void pcl::KernelFilter::ToImage ( ImageVariant v) const
inline

Renders this filter as an image. The contents of the image transported by the specified ImageVariant object v will be replaced with a grayscale rendition of this filter, where each image pixel has a value proportional to its corresponding filter coefficient counterpart.

If the ImageVariant object v does not transport an image, a new one is created in 32-bit floating point format.

Also take into account the information given for ToImage( GenericImage<P>& ), relative to out-of-range values, which is entirely applicable to this member function.

Definition at line 562 of file KernelFilter.h.

◆ Weight()

double pcl::KernelFilter::Weight ( ) const
inline

Returns the weight of this kernel filter. The weight is equal to the sum of all filter coefficients.

Definition at line 417 of file KernelFilter.h.


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