VIGRA - One-dimensional and separable convolution functions

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

| One-dimensional and separable convolution functions |
--- | --- | ---

## Functions
template<...> void | convolveLine (SrcIterator is, SrcIterator iend, SrcAccessor sa, DestIterator id, DestAccessor da, KernelIterator ik, KernelAccessor ka, int kleft, int kright, BorderTreatmentMode border)
| Performs a 1 dimensional convolution of the source signal using the given kernel.
template<...> void | separableConvolveX (SrcIterator supperleft, SrcIterator slowerright, SrcAccessor sa, DestIterator dupperleft, DestAccessor da, KernelIterator ik, KernelAccessor ka, int kleft, int kright, BorderTreatmentMode border)
| Performs a 1 dimensional convolution in x direction.
template<...> void | separableConvolveY (SrcIterator supperleft, SrcIterator slowerright, SrcAccessor sa, DestIterator dupperleft, DestAccessor da, KernelIterator ik, KernelAccessor ka, int kleft, int kright, BorderTreatmentMode border)
| 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 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. 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)
        }
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)
        }
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 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));

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

© Ullrich Köthe (koethe@informatik.uni-hamburg.de) Cognitive Systems Group, University of Hamburg, Germany | html generated using doxygen and Python VIGRA 1.5.0 (7 Dec 2006)