One-dimensional and separable convolution functions

Functions
template<... >
void	convolveLine (...)
	Performs a 1-dimensional convolution of the source signal using the given kernel. More...
template<... >
void	separableConvolveX (...)
	Performs a 1 dimensional convolution in x direction. More...
template<... >
void	separableConvolveY (...)
	Performs a 1 dimensional convolution in y direction. More...

Detailed Description

Perform 1D convolution and separable filtering in 2 dimensions.

These generic convolution functions implement the standard convolution operation for a wide range of images and signals that fit into the required interface. They need a suitable kernel to operate.

Function Documentation

void vigra::convolveLine

(

...

)

Performs a 1-dimensional convolution of the source signal using the given kernel.

The KernelIterator must point to the center iterator, and the kernel's size is given by its left (kleft <= 0) and right (kright >= 0) borders. The signal must always be larger than the kernel. At those positions where the kernel does not completely fit into the signal's range, the specified BorderTreatmentMode is applied.

The signal's value_type (SrcAccessor::value_type) must be a linear space over the kernel's value_type (KernelAccessor::value_type), i.e. addition of source values, multiplication with kernel values, and NumericTraits must be defined. The kernel's value_type must be an algebraic field, i.e. the arithmetic operations (+, -, *, /) and NumericTraits must be defined.

If start and stop are non-zero, the relation 0 <= start < stop <= width must hold (where width is the length of the input array). The convolution is then restricted to that subrange, and it is assumed that the output array only refers to that subrange (i.e. id points to the element corresponding to start). If start and stop are both zero (the default), the entire array is convolved.

Declarations:

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void convolveLine(SrcIterator is, SrcIterator isend, SrcAccessor sa,
                      DestIterator id, DestAccessor da,
                      KernelIterator ik, KernelAccessor ka,
                      int kleft, int kright, BorderTreatmentMode border,
                      int start = 0, int stop = 0 )
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void convolveLine(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                      pair<DestIterator, DestAccessor> dest,
                      tuple5<KernelIterator, KernelAccessor,
                             int, int, BorderTreatmentMode> kernel,
                       int start = 0, int stop = 0)
}

Usage:

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

std::vector<float> src, dest;
...

// define binomial filter of size 5
static float kernel[] =
       { 1.0/16.0, 4.0/16.0, 6.0/16.0, 4.0/16.0, 1.0/16.0};

typedef vigra::StandardAccessor<float> FAccessor;
typedef vigra::StandardAccessor<float> KernelAccessor;


vigra::convolveLine(src.begin(), src.end(), FAccessor(), dest.begin(), FAccessor(),
         kernel+2, KernelAccessor(), -2, 2, BORDER_TREATMENT_REFLECT);
//       ^^^^^^^^  this is the center of the kernel

Required Interface:

RandomAccessIterator is, isend;
RandomAccessIterator id;
RandomAccessIterator ik;

SrcAccessor src_accessor;
DestAccessor dest_accessor;
KernelAccessor kernel_accessor;

NumericTraits<SrcAccessor::value_type>::RealPromote s = src_accessor(is);

s = s + s;
s = kernel_accessor(ik) * s;

dest_accessor.set(
    NumericTraits<DestAccessor::value_type>::fromRealPromote(s), id);

If border == BORDER_TREATMENT_CLIP:

NumericTraits<KernelAccessor::value_type>::RealPromote k = kernel_accessor(ik);

k = k + k;
k = k - k;
k = k * k;
k = k / k;

Preconditions:

kleft <= 0
kright >= 0
iend - is >= kright + kleft + 1

If border == BORDER_TREATMENT_CLIP: Sum of kernel elements must be != 0.

void vigra::separableConvolveX

(

...

)

Performs a 1 dimensional convolution in x direction.

It calls convolveLine() for every row of the image. See convolveLine() for more information about required interfaces and vigra_preconditions.

Declarations:

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2,
              class T3>
    void
    separableConvolveX(MultiArrayView<2, T1, S1> const & src,
                       MultiArrayView<2, T2, S2> dest,
                       Kernel1D<T3> const & kernel);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcImageIterator, class SrcAccessor,
              class DestImageIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void separableConvolveX(SrcImageIterator supperleft,
                            SrcImageIterator slowerright, SrcAccessor sa,
                            DestImageIterator dupperleft, DestAccessor da,
                            KernelIterator ik, KernelAccessor ka,
                            int kleft, int kright, BorderTreatmentMode border)
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcImageIterator, class SrcAccessor,
              class DestImageIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void separableConvolveX(triple<SrcImageIterator, SrcImageIterator, SrcAccessor> src,
                            pair<DestImageIterator, DestAccessor> dest,
                            tuple5<KernelIterator, KernelAccessor,
                                         int, int, BorderTreatmentMode> kernel)
}

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<double> kernel;
kernel.initGaussian(3.0);

// apply 1D filter along the x-axis
separableConvolveX(src, dest, kernel);

show deprecated examples

vigra::FImage src(w,h), dest(w,h);
...

// define Gaussian kernel with std. deviation 3.0
vigra::Kernel1D<double> kernel;
kernel.initGaussian(3.0);

// apply 1D filter along the x-axis
vigra::separableConvolveX(srcImageRange(src), destImage(dest), kernel1d(kernel));

Preconditions:

• The x-axis must be longer than the kernel radius: w > std::max(kernel.right(), -kernel.left()).
• If border == BORDER_TREATMENT_CLIP: The sum of kernel elements must be != 0.

Examples:

pyramid.cxx.

void vigra::separableConvolveY

(

...

)

Performs a 1 dimensional convolution in y direction.

It calls convolveLine() for every column of the image. See convolveLine() for more information about required interfaces and vigra_preconditions.

Declarations:

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2,
              class T3>
    void
    separableConvolveY(MultiArrayView<2, T1, S1> const & src,
                       MultiArrayView<2, T2, S2> dest,
                       Kernel1D<T3> const & kernel);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcImageIterator, class SrcAccessor,
              class DestImageIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void separableConvolveY(SrcImageIterator supperleft,
                            SrcImageIterator slowerright, SrcAccessor sa,
                            DestImageIterator dupperleft, DestAccessor da,
                            KernelIterator ik, KernelAccessor ka,
                            int kleft, int kright, BorderTreatmentMode border)
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcImageIterator, class SrcAccessor,
              class DestImageIterator, class DestAccessor,
              class KernelIterator, class KernelAccessor>
    void separableConvolveY(triple<SrcImageIterator, SrcImageIterator, SrcAccessor> src,
                            pair<DestImageIterator, DestAccessor> dest,
                            tuple5<KernelIterator, KernelAccessor,
                                         int, int, BorderTreatmentMode> kernel)
}

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 filter along the y-axis
separableConvolveY(src, dest, kernel);

show deprecated examples

vigra::FImage src(w,h), dest(w,h);
...

// define Gaussian kernel with std. deviation 3.0
vigra::Kernel1D kernel;
kernel.initGaussian(3.0);

vigra::separableConvolveY(srcImageRange(src), destImage(dest), kernel1d(kernel));

Preconditions:

• The y-axis must be longer than the kernel radius: h > std::max(kernel.right(), -kernel.left()).
• If border == BORDER_TREATMENT_CLIP: The sum of kernel elements must be != 0.

Examples:

pyramid.cxx.