[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

Kernel1D< ARITHTYPE > Class Template Reference

Generic 1 dimensional convolution kernel. More...

#include <vigra/separableconvolution.hxx>

Public Types

typedef StandardAccessor< ARITHTYPEAccessor
 
typedef InternalVector::const_iterator const_iterator
 
typedef InternalVector::const_reference const_reference
 
typedef StandardConstAccessor< ARITHTYPEConstAccessor
 
typedef InternalVector::iterator Iterator
 
typedef InternalVector::iterator iterator
 
typedef InternalVector::reference reference
 
typedef InternalVector::value_type value_type
 

Public Member Functions

Accessor accessor ()
 
ConstAccessor accessor () const
 
BorderTreatmentMode borderTreatment () const
 
iterator center ()
 
void initAveraging (int radius)
 
void initAveraging (int radius, value_type norm)
 
void initBackwardDifference ()
 
void initBinomial (int radius)
 
void initBinomial (int radius, value_type norm)
 
void initBurtFilter (double a=0.04785)
 
void initDiscreteGaussian (double std_dev)
 
void initDiscreteGaussian (double std_dev, value_type norm)
 
Kernel1DinitExplicitly (int left, int right)
 
void initForwardDifference ()
 
void initGaussian (double std_dev)
 
void initGaussian (double std_dev, value_type norm, double windowRatio=0.0)
 
void initGaussianDerivative (double std_dev, int order)
 
void initGaussianDerivative (double std_dev, int order, value_type norm, double windowRatio=0.0)
 
void initOptimalFirstDerivative5 ()
 
void initOptimalFirstDerivativeSmoothing3 ()
 
void initOptimalFirstDerivativeSmoothing5 ()
 
void initOptimalSecondDerivative5 ()
 
void initOptimalSecondDerivativeSmoothing3 ()
 
void initOptimalSecondDerivativeSmoothing5 ()
 
void initOptimalSmoothing3 ()
 
void initOptimalSmoothing5 ()
 
void initSecondDifference3 ()
 
void initSymmetricDifference ()
 
void initSymmetricGradient ()
 
void initSymmetricGradient (value_type norm)
 
 Kernel1D ()
 
 Kernel1D (Kernel1D const &k)
 
template<class U >
 Kernel1D (Kernel1D< U > const &k)
 
int left () const
 
value_type norm () const
 
void normalize ()
 
void normalize (value_type norm, unsigned int derivativeOrder=0, double offset=0.0)
 
Kernel1Doperator= (Kernel1D const &k)
 
InitProxy operator= (value_type const &v)
 
reference operator[] (int location)
 
int right () const
 
void setBorderTreatment (BorderTreatmentMode new_mode)
 
int size () const
 
 ~Kernel1D ()
 

Detailed Description

template<class ARITHTYPE = double>
class vigra::Kernel1D< ARITHTYPE >

Generic 1 dimensional convolution kernel.

This kernel may be used for convolution of 1 dimensional signals or for separable convolution of multidimensional signals.

Convolution functions access the kernel via a 1 dimensional random access iterator which they get by calling center(). This iterator points to the center of the kernel. The kernel's size is given by its left() (<=0) and right() (>= 0) methods. The desired border treatment mode is returned by borderTreatment().

The different init functions create a kernel with the specified properties. The kernel's value_type must be a linear space, i.e. it must define multiplication with doubles and NumericTraits.

Usage:

#include <vigra/separableconvolution.hxx>
Namespace: vigra

...
// define Gaussian kernel with std. deviation 3.0
Kernel1D kernel;
kernel.initGaussian(3.0);
// apply 1D kernel along the x-axis
Class for a single RGB value.
Definition rgbvalue.hxx:128
void separableConvolveX(...)
Performs a 1 dimensional convolution in x direction.

show deprecated examples

Member Typedef Documentation

◆ value_type

template<class ARITHTYPE = double>
typedef InternalVector::value_type value_type

the kernel's value type

◆ reference

the kernel's reference type

◆ const_reference

the kernel's const reference type

◆ Iterator

deprecated – use Kernel1D::iterator

◆ iterator

1D random access iterator over the kernel's values

◆ const_iterator

const 1D random access iterator over the kernel's values

◆ Accessor

the kernel's accessor

◆ ConstAccessor

the kernel's const accessor

Constructor & Destructor Documentation

◆ Kernel1D() [1/3]

template<class ARITHTYPE = double>
Kernel1D ( )

Default constructor. Creates a kernel of size 1 which would copy the signal unchanged.

◆ Kernel1D() [2/3]

template<class ARITHTYPE = double>
Kernel1D ( Kernel1D< ARITHTYPE > const k)

Copy constructor.

◆ Kernel1D() [3/3]

template<class ARITHTYPE = double>
template<class U >
Kernel1D ( Kernel1D< U > const k)

Construct from kernel with different element type, e.g. double => FixedPoint16.

◆ ~Kernel1D()

template<class ARITHTYPE = double>
~Kernel1D ( )

Destructor.

Member Function Documentation

◆ operator=() [1/2]

template<class ARITHTYPE = double>
Kernel1D & operator= ( Kernel1D< ARITHTYPE > const k)

Copy assignment.

◆ operator=() [2/2]

template<class ARITHTYPE = double>
InitProxy operator= ( value_type const v)

Initialization. This initializes the kernel with the given constant. The norm becomes v*size().

Instead of a single value an initializer list of length size() can be used like this:

In this case, the norm will be set to the sum of the init values. An initializer list of wrong length will result in a run-time error.

◆ initGaussian() [1/2]

template<class ARITHTYPE >
void initGaussian ( double  std_dev,
value_type  norm,
double  windowRatio = 0.0 
)

Init as a sampled Gaussian function. The radius of the kernel is always 3*std_dev. 'norm' denotes the sum of all bins of the kernel (i.e. the kernel is corrected for the normalization error introduced by windowing the Gaussian to a finite interval). However, if norm is 0.0, the kernel is normalized to 1 by the analytic expression for the Gaussian, and no correction for the windowing error is performed. If windowRatio = 0.0, the radius of the filter window is radius = round(3.0 * std_dev), otherwise it is radius = round(windowRatio * std_dev) (where windowRatio > 0.0 is required).

Precondition:

std_dev >= 0.0

Postconditions:

1. left() == -(int)(3.0*std_dev + 0.5)
2. right() == (int)(3.0*std_dev + 0.5)
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == norm
int right() const
Definition separableconvolution.hxx:2157
value_type norm() const
Definition separableconvolution.hxx:2175
BorderTreatmentMode borderTreatment() const
Definition separableconvolution.hxx:2165
int left() const
Definition separableconvolution.hxx:2153

◆ initGaussian() [2/2]

template<class ARITHTYPE = double>
void initGaussian ( double  std_dev)

Init as a Gaussian function with norm 1.

◆ initDiscreteGaussian() [1/2]

template<class ARITHTYPE >
void initDiscreteGaussian ( double  std_dev,
value_type  norm 
)

Init as Lindeberg's discrete analog of the Gaussian function. The radius of the kernel is always 3*std_dev. 'norm' denotes the sum of all bins of the kernel.

Precondition:

std_dev >= 0.0

Postconditions:

1. left() == -(int)(3.0*std_dev + 0.5)
2. right() == (int)(3.0*std_dev + 0.5)
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == norm

◆ initDiscreteGaussian() [2/2]

template<class ARITHTYPE = double>
void initDiscreteGaussian ( double  std_dev)

Init as a Lindeberg's discrete analog of the Gaussian function with norm 1.

◆ initGaussianDerivative() [1/2]

template<class ARITHTYPE >
void initGaussianDerivative ( double  std_dev,
int  order,
value_type  norm,
double  windowRatio = 0.0 
)

Init as a Gaussian derivative of order 'order'. The radius of the kernel is always 3*std_dev + 0.5*order. 'norm' denotes the norm of the kernel so that the following condition is fulfilled:

\[ \sum_{i=left()}^{right()}
             \frac{(-i)^{order}kernel[i]}{order!} = norm
\]

Thus, the kernel will be corrected for the error introduced by windowing the Gaussian to a finite interval. However, if norm is 0.0, the kernel is normalized to 1 by the analytic expression for the Gaussian derivative, and no correction for the windowing error is performed. If windowRatio = 0.0, the radius of the filter window is radius = round(3.0 * std_dev + 0.5 * order), otherwise it is radius = round(windowRatio * std_dev) (where windowRatio > 0.0 is required).

Preconditions:

1. std_dev >= 0.0
2. order >= 1

Postconditions:

1. left() == -(int)(3.0*std_dev + 0.5*order + 0.5)
2. right() == (int)(3.0*std_dev + 0.5*order + 0.5)
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == norm

◆ initGaussianDerivative() [2/2]

template<class ARITHTYPE = double>
void initGaussianDerivative ( double  std_dev,
int  order 
)

Init as a Gaussian derivative with norm 1.

◆ initOptimalSmoothing3()

template<class ARITHTYPE = double>
void initOptimalSmoothing3 ( )

Init an optimal 3-tap smoothing filter. The filter values are

[0.216, 0.568, 0.216]

These values are optimal in the sense that the 3x3 filter obtained by separable application of this filter is the best possible 3x3 approximation to a Gaussian filter. The equivalent Gaussian has sigma = 0.680.

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalFirstDerivativeSmoothing3()

template<class ARITHTYPE = double>
void initOptimalFirstDerivativeSmoothing3 ( )

Init an optimal 3-tap smoothing filter to be used in the context of first derivative computation. This filter must be used in conjunction with the symmetric difference filter (see initSymmetricDifference()), such that the difference filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.224365, 0.55127, 0.224365]

These values are optimal in the sense that the 3x3 filter obtained by combining this filter with the symmetric difference is the best possible 3x3 approximation to a Gaussian first derivative filter. The equivalent Gaussian has sigma = 0.675.

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalSecondDerivativeSmoothing3()

template<class ARITHTYPE = double>
void initOptimalSecondDerivativeSmoothing3 ( )

Init an optimal 3-tap smoothing filter to be used in the context of second derivative computation. This filter must be used in conjunction with the 3-tap second difference filter (see initSecondDifference3()), such that the difference filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.13, 0.74, 0.13]

These values are optimal in the sense that the 3x3 filter obtained by combining this filter with the 3-tap second difference is the best possible 3x3 approximation to a Gaussian second derivative filter. The equivalent Gaussian has sigma = 0.433.

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalSmoothing5()

template<class ARITHTYPE = double>
void initOptimalSmoothing5 ( )

Init an optimal 5-tap smoothing filter. The filter values are

[0.03134, 0.24, 0.45732, 0.24, 0.03134]

These values are optimal in the sense that the 5x5 filter obtained by separable application of this filter is the best possible 5x5 approximation to a Gaussian filter. The equivalent Gaussian has sigma = 0.867.

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalFirstDerivativeSmoothing5()

template<class ARITHTYPE = double>
void initOptimalFirstDerivativeSmoothing5 ( )

Init an optimal 5-tap smoothing filter to be used in the context of first derivative computation. This filter must be used in conjunction with the optimal 5-tap first derivative filter (see initOptimalFirstDerivative5()), such that the derivative filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.04255, 0.241, 0.4329, 0.241, 0.04255]

These values are optimal in the sense that the 5x5 filter obtained by combining this filter with the optimal 5-tap first derivative is the best possible 5x5 approximation to a Gaussian first derivative filter. The equivalent Gaussian has sigma = 0.906.

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalSecondDerivativeSmoothing5()

template<class ARITHTYPE = double>
void initOptimalSecondDerivativeSmoothing5 ( )

Init an optimal 5-tap smoothing filter to be used in the context of second derivative computation. This filter must be used in conjunction with the optimal 5-tap second derivative filter (see initOptimalSecondDerivative5()), such that the derivative filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.0243, 0.23556, 0.48028, 0.23556, 0.0243]

These values are optimal in the sense that the 5x5 filter obtained by combining this filter with the optimal 5-tap second derivative is the best possible 5x5 approximation to a Gaussian second derivative filter. The equivalent Gaussian has sigma = 0.817.

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initBurtFilter()

template<class ARITHTYPE = double>
void initBurtFilter ( double  a = 0.04785)

Init a 5-tap filter as defined by Peter Burt in the context of pyramid creation. The filter values are

[a, 0.25, 0.5-2*a, 0.25, a]

The default a = 0.04785 is optimal in the sense that it minimizes the difference to a true Gaussian filter (which would have sigma = 0.975). For other values of a, the scale of the most similar Gaussian can be approximated by

sigma = 5.1 * a + 0.731

Preconditions:

0 <= a <= 0.125

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initBinomial() [1/2]

template<class ARITHTYPE >
void initBinomial ( int  radius,
value_type  norm 
)

Init as a Binomial filter. 'norm' denotes the sum of all bins of the kernel.

Precondition:

radius >= 0

Postconditions:

1. left() == -radius
2. right() == radius
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == norm

◆ initBinomial() [2/2]

template<class ARITHTYPE = double>
void initBinomial ( int  radius)

Init as a Binomial filter with norm 1.

◆ initAveraging() [1/2]

template<class ARITHTYPE >
void initAveraging ( int  radius,
value_type  norm 
)

Init as an Averaging filter. 'norm' denotes the sum of all bins of the kernel. The window size is (2*radius+1) * (2*radius+1)

Precondition:

radius >= 0

Postconditions:

1. left() == -radius
2. right() == radius
3. borderTreatment() == BORDER_TREATMENT_CLIP
4. norm() == norm

◆ initAveraging() [2/2]

template<class ARITHTYPE = double>
void initAveraging ( int  radius)

Init as an Averaging filter with norm 1.

◆ initSymmetricGradient() [1/2]

template<class ARITHTYPE = double>
void initSymmetricGradient ( value_type  norm)

Init as a symmetric gradient filter of the form [ 0.5 * norm, 0.0 * norm, -0.5 * norm]

Deprecated. Use initSymmetricDifference() instead.

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REPEAT
4. norm() == norm

◆ initSymmetricGradient() [2/2]

template<class ARITHTYPE = double>
void initSymmetricGradient ( )

Init as a symmetric gradient filter with norm 1.

Deprecated. Use initSymmetricDifference() instead.

◆ initForwardDifference()

template<class ARITHTYPE = double>
void initForwardDifference ( )

Init as the 2-tap forward difference filter. The filter values are

[1.0, -1.0]

(note that filters are reflected by the convolution algorithm, and we get a forward difference after reflection).

Postconditions:

1. left() == -1
2. right() == 0
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initBackwardDifference()

template<class ARITHTYPE = double>
void initBackwardDifference ( )

Init as the 2-tap backward difference filter. The filter values are

[1.0, -1.0]

(note that filters are reflected by the convolution algorithm, and we get a forward difference after reflection).

Postconditions:

1. left() == 0
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initSymmetricDifference()

template<class ARITHTYPE = double>
void initSymmetricDifference ( )

Init as the 3-tap symmetric difference filter The filter values are

[0.5, 0, -0.5]

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initSecondDifference3()

template<class ARITHTYPE = double>
void initSecondDifference3 ( )

Init the 3-tap second difference filter. The filter values are

[1, -2, 1]

Postconditions:

1. left() == -1
2. right() == 1
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1

◆ initOptimalFirstDerivative5()

template<class ARITHTYPE = double>
void initOptimalFirstDerivative5 ( )

Init an optimal 5-tap first derivative filter. This filter must be used in conjunction with the corresponding 5-tap smoothing filter (see initOptimalFirstDerivativeSmoothing5()), such that the derivative filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.1, 0.3, 0.0, -0.3, -0.1]

These values are optimal in the sense that the 5x5 filter obtained by combining this filter with the corresponding 5-tap smoothing filter is the best possible 5x5 approximation to a Gaussian first derivative filter. The equivalent Gaussian has sigma = 0.906.

If the filter is instead separably combined with itself, an almost optimal approximation of the mixed second Gaussian derivative at scale sigma = 0.899 results.

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initOptimalSecondDerivative5()

template<class ARITHTYPE = double>
void initOptimalSecondDerivative5 ( )

Init an optimal 5-tap second derivative filter. This filter must be used in conjunction with the corresponding 5-tap smoothing filter (see initOptimalSecondDerivativeSmoothing5()), such that the derivative filter is applied along one dimension, and the smoothing filter along the other. The filter values are

[0.22075, 0.117, -0.6755, 0.117, 0.22075]

These values are optimal in the sense that the 5x5 filter obtained by combining this filter with the corresponding 5-tap smoothing filter is the best possible 5x5 approximation to a Gaussian second derivative filter. The equivalent Gaussian has sigma = 0.817.

Postconditions:

1. left() == -2
2. right() == 2
3. borderTreatment() == BORDER_TREATMENT_REFLECT
4. norm() == 1.0

◆ initExplicitly()

template<class ARITHTYPE = double>
Kernel1D & initExplicitly ( int  left,
int  right 
)

Init the kernel by an explicit initializer list. The left and right boundaries of the kernel must be passed. A comma-separated initializer list is given after the assignment operator. This function is used like this:

// define horizontal Roberts filter
roberts_gradient_x.initExplicitly(0, 1) = 1.0, -1.0;

The norm is set to the sum of the initializer values. If the wrong number of values is given, a run-time error results. It is, however, possible to give just one initializer. This creates an averaging filter with the given constant:

average5x1.initExplicitly(-2, 2) = 1.0/5.0;

Here, the norm is set to value*size().

Preconditions:

1. left <= 0
2. right >= 0
int size() const
Definition separableconvolution.hxx:2161

◆ center()

template<class ARITHTYPE = double>
iterator center ( )

Get iterator to center of kernel

Postconditions:

center()[left()] ... center()[right()] are valid kernel positions
iterator center()
Definition separableconvolution.hxx:2123

◆ operator[]()

template<class ARITHTYPE = double>
reference operator[] ( int  location)

Access kernel value at specified location.

Preconditions:

left() <= location <= right()

◆ left()

template<class ARITHTYPE = double>
int left ( ) const

left border of kernel (inclusive), always <= 0

◆ right()

template<class ARITHTYPE = double>
int right ( ) const

right border of kernel (inclusive), always >= 0

◆ size()

template<class ARITHTYPE = double>
int size ( ) const

size of kernel (right() - left() + 1)

◆ borderTreatment()

template<class ARITHTYPE = double>
BorderTreatmentMode borderTreatment ( ) const

current border treatment mode

◆ setBorderTreatment()

template<class ARITHTYPE = double>
void setBorderTreatment ( BorderTreatmentMode  new_mode)

Set border treatment mode.

◆ norm()

template<class ARITHTYPE = double>
value_type norm ( ) const

norm of kernel

◆ normalize() [1/2]

template<class ARITHTYPE >
void normalize ( value_type  norm,
unsigned int  derivativeOrder = 0,
double  offset = 0.0 
)

set a new norm and normalize kernel, use the normalization formula for the given derivativeOrder.

◆ normalize() [2/2]

template<class ARITHTYPE = double>
void normalize ( )

normalize kernel to norm 1.

◆ accessor() [1/2]

template<class ARITHTYPE = double>
ConstAccessor accessor ( ) const

get a const accessor

◆ accessor() [2/2]

template<class ARITHTYPE = double>
Accessor accessor ( )

get an accessor


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

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de)
Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany

html generated using doxygen and Python
vigra 1.11.2