vigra - One-dimensional and separable convolution functions

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

| One-dimensional and separable convolution functions |

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

## 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 arguments explicitly:

        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>

        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 arguments explicitly:

        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>

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

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

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

Examples:
  pyramid.cxx, and smooth.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 arguments explicitly:

        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>

        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));

Examples:
  pyramid.cxx, and smooth.cxx.

© 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.9.0 (Tue Nov 6 2012)