vigra - Two-dimensional convolution functions

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

| Two-dimensional convolution functions |

## Functions
template<class SrcIterator , class SrcAccessor , class DestIterator , class DestAccessor , class KernelIterator , class KernelAccessor >
void | convolveImage (SrcIterator src_ul, SrcIterator src_lr, SrcAccessor src_acc, DestIterator dest_ul, DestAccessor dest_acc, KernelIterator ki, KernelAccessor ak, Diff2D kul, Diff2D klr, BorderTreatmentMode border)
| Performs a 2 dimensional convolution of the source image using the given kernel.
template<... >
void | convolveImageWithMask (...)
| Deprecated name of 2-dimensional normalized convolution, i.e. convolution with a mask image.
template<... >
void | normalizedConvolveImage (...)
| Performs a 2-dimensional normalized convolution, i.e. convolution with a mask image.

## Detailed Description

Perform 2D non-separable convolution, with and without ROI mask.

These generic convolution functions implement the standard 2D convolution operation for images that fit into the required interface. Arbitrary ROI's are supported by the mask version of the algorithm. The functions need a suitable 2D kernel to operate.

## Function Documentation

void vigra::convolveImage | ( | SrcIterator | src_ul,
|  | SrcIterator | src_lr,
|  | SrcAccessor | src_acc,
|  | DestIterator | dest_ul,
|  | DestAccessor | dest_acc,
|  | KernelIterator | ki,
|  | KernelAccessor | ak,
|  | Diff2D | kul,
|  | Diff2D | klr,
|  | BorderTreatmentMode | border
| ) |  |

Performs a 2 dimensional convolution of the source image using the given kernel.

The KernelIterator must point to the center of the kernel, and the kernel's size is given by its upper left (x and y of distance <= 0) and lower right (distance >= 0) corners. The image must always be larger than the kernel. At those positions where the kernel does not completely fit into the image, the specified BorderTreatmentMode is applied. You can choice between following BorderTreatmentModes:

- BORDER_TREATMENT_CLIP
- BORDER_TREATMENT_AVOID
- BORDER_TREATMENT_WRAP
- BORDER_TREATMENT_REFLECT
- BORDER_TREATMENT_REPEAT

The images's pixel 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 convolveImage(SrcIterator src_ul, SrcIterator src_lr, SrcAccessor src_acc,
                               DestIterator dest_ul, DestAccessor dest_acc,
                               KernelIterator ki, KernelAccessor ak,
                               Diff2D kul, Diff2D klr, 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 convolveImage(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                               pair<DestIterator, DestAccessor> dest,
                               tuple5<KernelIterator, KernelAccessor, Diff2D, Diff2D,
                               BorderTreatmentMode> kernel);
        }

Usage:

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

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

        // define horizontal Sobel filter
        vigra::Kernel2D<float> sobel;

        sobel.initExplicitly(Diff2D(-1,-1), Diff2D(1,1)) =  // upper left and lower right
                             0.125, 0.0, -0.125,
                             0.25,  0.0, -0.25,
                             0.125, 0.0, -0.125;
        sobel.setBorderTreatment(vigra::BORDER_TREATMENT_REFLECT);

        vigra::convolveImage(srcImageRange(src), destImage(dest), kernel2d(sobel));

Required Interface:

        ImageIterator src_ul, src_lr;
        ImageIterator dest_ul;
        ImageIterator ik;

        SrcAccessor src_accessor;
        DestAccessor dest_accessor;
        KernelAccessor kernel_accessor;

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

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

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

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

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

Preconditions:

        kul.x <= 0
        kul.y <= 0
        klr.x >= 0
        klr.y >= 0
        src_lr.x - src_ul.x >= klr.x + kul.x + 1
        src_lr.y - src_ul.y >= klr.y + kul.y + 1

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

void vigra::normalizedConvolveImage | ( |  | ... | ) |

Performs a 2-dimensional normalized convolution, i.e. convolution with a mask image.

This functions computes normalized convolution as defined in Knutsson, H. and Westin, C-F.: Normalized and differential convolution: Methods for Interpolation and Filtering of incomplete and uncertain data. Proc. of the IEEE Conf. on Computer Vision and Pattern Recognition, 1993, 515-523.

The mask image must be binary and encodes which pixels of the original image are valid. It is used as follows: Only pixel under the mask are used in the calculations. Whenever a part of the kernel lies outside the mask, it is ignored, and the kernel is renormalized to its original norm (analogous to the CLIP BorderTreatmentMode). Thus, a useful convolution result is computed whenever at least one valid pixel is within the current window Thus, destination pixels not under the mask still receive a value if they are near the mask. Therefore, this algorithm is useful as an interpolator of sparse input data. If you are only interested in the destination values under the mask, you can perform a subsequent copyImageIf().

The KernelIterator must point to the center of the kernel, and the kernel's size is given by its upper left (x and y of distance <= 0) and lower right (distance >= 0) corners. The image must always be larger than the kernel. At those positions where the kernel does not completely fit into the image, the specified BorderTreatmentMode is applied. Only BORDER_TREATMENT_CLIP and BORDER_TREATMENT_AVOID are currently supported.

The images's pixel 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 MaskIterator, class MaskAccessor,
                      class DestIterator, class DestAccessor,
                      class KernelIterator, class KernelAccessor>
            void
            normalizedConvolveImage(SrcIterator src_ul, SrcIterator src_lr, SrcAccessor src_acc,
                                    MaskIterator mul, MaskAccessor am,
                                    DestIterator dest_ul, DestAccessor dest_acc,
                                    KernelIterator ki, KernelAccessor ak,
                                    Diff2D kul, Diff2D klr, BorderTreatmentMode border);
        }

use argument objects in conjunction with Argument Object Factories :

        namespace vigra {
            template <class SrcIterator, class SrcAccessor,
                      class MaskIterator, class MaskAccessor,
                      class DestIterator, class DestAccessor,
                      class KernelIterator, class KernelAccessor>
            void normalizedConvolveImage(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                                         pair<MaskIterator, MaskAccessor> mask,
                                         pair<DestIterator, DestAccessor> dest,
                                         tuple5<KernelIterator, KernelAccessor, Diff2D, Diff2D,
                                         BorderTreatmentMode> kernel);
        }

Usage:

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

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

        // define 3x3 binomial filter
        vigra::Kernel2D<float> binom;

        binom.initExplicitly(Diff2D(-1,-1), Diff2D(1,1)) =   // upper left and lower right
                             0.0625, 0.125, 0.0625,
                             0.125,  0.25,  0.125,
                             0.0625, 0.125, 0.0625;

        vigra::normalizedConvolveImage(srcImageRange(src), maskImage(mask), destImage(dest), kernel2d(binom));

Required Interface:

        ImageIterator src_ul, src_lr;
        ImageIterator mul;
        ImageIterator dest_ul;
        ImageIterator ik;

        SrcAccessor src_accessor;
        MaskAccessor mask_accessor;
        DestAccessor dest_accessor;
        KernelAccessor kernel_accessor;

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

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

        if(mask_accessor(mul)) ...;

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

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

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

Preconditions:

        kul.x <= 0
        kul.y <= 0
        klr.x >= 0
        klr.y >= 0
        src_lr.x - src_ul.x >= klr.x + kul.x + 1
        src_lr.y - src_ul.y >= klr.y + kul.y + 1
        border == BORDER_TREATMENT_CLIP || border == BORDER_TREATMENT_AVOID

Sum of kernel elements must be != 0.

void vigra::convolveImageWithMask | ( |  | ... | ) |

Deprecated name of 2-dimensional normalized convolution, i.e. convolution with a mask image.

See normalizedConvolveImage() for documentation.

Declarations:

pass arguments explicitly:

        namespace vigra {
            template <class SrcIterator, class SrcAccessor,
                      class MaskIterator, class MaskAccessor,
                      class DestIterator, class DestAccessor,
                      class KernelIterator, class KernelAccessor>
            void
            convolveImageWithMask(SrcIterator src_ul, SrcIterator src_lr, SrcAccessor src_acc,
                                  MaskIterator mul, MaskAccessor am,
                                  DestIterator dest_ul, DestAccessor dest_acc,
                                  KernelIterator ki, KernelAccessor ak,
                                  Diff2D kul, Diff2D klr, BorderTreatmentMode border);
        }

use argument objects in conjunction with Argument Object Factories :

        namespace vigra {
            template <class SrcIterator, class SrcAccessor,
                      class MaskIterator, class MaskAccessor,
                      class DestIterator, class DestAccessor,
                      class KernelIterator, class KernelAccessor>
            void convolveImageWithMask(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                                       pair<MaskIterator, MaskAccessor> mask,
                                       pair<DestIterator, DestAccessor> dest,
                                       tuple5<KernelIterator, KernelAccessor, Diff2D, Diff2D,
                                       BorderTreatmentMode> kernel);
        }

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