vigra - Kernel1D< ARITHTYPE > Class Template Reference

[ 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 < ARITHTYPE > | Accessor
typedef InternalVector::const_iterator | const_iterator
typedef InternalVector::const_reference | const_reference
typedef StandardConstAccessor < ARITHTYPE > | ConstAccessor
typedef InternalVector::iterator | Iterator
typedef InternalVector::iterator | iterator
typedef InternalVector::reference | reference
typedef InternalVector::value_type | value_type

## Public Member Functions
ConstAccessor | accessor () const
Accessor | accessor ()
BorderTreatmentMode | borderTreatment () const
iterator | center ()
void | initAveraging (int radius, value_type norm)
void | initAveraging (int radius)
void | initBackwardDifference ()
void | initBinomial (int radius, value_type norm)
void | initBinomial (int radius)
void | initBurtFilter (double a=0.04785)
void | initDiscreteGaussian (double std_dev, value_type norm)
void | initDiscreteGaussian (double std_dev)
Kernel1D & | initExplicitly (int left, int right)
void | initForwardDifference ()
void | initGaussian (double std_dev, value_type norm, double windowRatio=0.0)
void | initGaussian (double std_dev)
void | initGaussianDerivative (double std_dev, int order, value_type norm, double windowRatio=0.0)
void | initGaussianDerivative (double std_dev, int order)
void | initOptimalFirstDerivative5 ()
void | initOptimalFirstDerivativeSmoothing3 ()
void | initOptimalFirstDerivativeSmoothing5 ()
void | initOptimalSecondDerivative5 ()
void | initOptimalSecondDerivativeSmoothing3 ()
void | initOptimalSecondDerivativeSmoothing5 ()
void | initOptimalSmoothing3 ()
void | initOptimalSmoothing5 ()
void | initSecondDifference3 ()
void | initSymmetricDifference ()
void | initSymmetricGradient (value_type norm)
void | initSymmetricGradient ()
| Kernel1D ()
| Kernel1D (Kernel1D const &k)
template<class U >
| Kernel1D (Kernel1D< U > const &k)
int | left () const
value_type | norm () const
void | normalize (value_type norm, unsigned int derivativeOrder=0, double offset=0.0)
void | normalize ()
Kernel1D & | operator= (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>
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

MultiArray<2, float> src(w,h), dest(w,h);
...
// define Gaussian kernel with std. deviation 3.0
Kernel1D kernel;
kernel.initGaussian(3.0);
// apply 1D kernel along the x-axis
separableConvolveX(src, dest, kernel);

show deprecated examples

The kernel defines a factory function kernel1d() to create an argument object (see Kernel Argument Object Factories).
vigra::FImage src(w,h), dest(w,h);
...
// define Gaussian kernel with std. deviation 3.0
vigra::Kernel1D kernel;
kernel.initGaussian(3.0);
vigra::separableConvolveX(srcImageRange(src), destImage(dest), kernel1d(kernel));

Required Interface:

value_type v = vigra::NumericTraits<value_type>::one(); // if norm is not
// given explicitly
double d;
v = d * v;

Examples:
  pyramid.cxx, and smooth_convolve.cxx.

## Member Typedef Documentation

typedef InternalVector::value_type value_type

the kernel's value type

typedef InternalVector::reference reference

the kernel's reference type

typedef InternalVector::const_reference const_reference

the kernel's const reference type

typedef InternalVector::iterator Iterator

deprecated – use Kernel1D::iterator

typedef InternalVector::iterator iterator

1D random access iterator over the kernel's values

typedef InternalVector::const_iterator const_iterator

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

typedef StandardAccessor<ARITHTYPE> Accessor

the kernel's accessor

typedef StandardConstAccessor<ARITHTYPE> ConstAccessor

the kernel's const accessor

## Constructor & Destructor Documentation

Kernel1D | ( | ) |  |

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

Kernel1D | ( | Kernel1D< ARITHTYPE > const & | k) |  |

Copy constructor.

Kernel1D | ( | Kernel1D< U > const & | k) |  |

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

~Kernel1D | ( | ) |  |

Destructor.

## Member Function Documentation

Kernel1D& operator= | ( | Kernel1D< ARITHTYPE > const & | k) |  |

Copy assignment.

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:

vigra::Kernel1D<float> roberts_gradient_x;
roberts_gradient_x.initExplicitly(0, 1) = 1.0, -1.0;

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.

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

void initGaussian | ( | double | std_dev) |  |

Init as a Gaussian function with norm 1.

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

void initDiscreteGaussian | ( | double | std_dev) |  |

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

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:

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

void initGaussianDerivative | ( | double | std_dev,
|  | int | order
| ) |  |

Init as a Gaussian derivative with norm 1.

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

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

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

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

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

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

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

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

void initBinomial | ( | int | radius) |  |

Init as a Binomial filter with norm 1.

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

void initAveraging | ( | int | radius) |  |

Init as an Averaging filter with norm 1.

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

void initSymmetricGradient | ( | ) |  |

Init as a symmetric gradient filter with norm 1.

Deprecated. Use initSymmetricDifference() instead.

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

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

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

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

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

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

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
vigra::Kernel1D<float> roberts_gradient_x;
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:

vigra::Kernel1D<float> average5x1;
average5x1.initExplicitly(-2, 2) = 1.0/5.0;

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

Preconditions:

1. left <= 0
2. right >= 0
3. the number of values in the initializer list
is 1 or equals the size of the kernel.

iterator center | ( | ) |  |

Get iterator to center of kernel

Postconditions:

center()[left()] ... center()[right()] are valid kernel positions

reference operator[] | ( | int | location) |  |

Access kernel value at specified location.

Preconditions:

left() <= location <= right()

int left | ( | ) |  | const

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

int right | ( | ) |  | const

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

int size | ( | ) |  | const

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

BorderTreatmentMode borderTreatment | ( | ) |  | const

current border treatment mode

void setBorderTreatment | ( | BorderTreatmentMode | new_mode) |  |

Set border treatment mode.

value_type norm | ( | ) |  | const

norm of kernel

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

void normalize | ( | ) |  |

normalize kernel to norm 1.

ConstAccessor accessor | ( | ) |  | const

get a const accessor

Accessor accessor | ( | ) |  |

get an accessor

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

- vigra/separableconvolution.hxx

© 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.10.0 (Thu Jan 8 2015)