Resampling Convolution Filters

Functions
template<... >
void	pyramidExpandBurtFilter (...)
	Two-fold up-sampling for image pyramid reconstruction. More...
template<class Image , class Alloc >
void	pyramidExpandBurtLaplacian (ImagePyramid< Image, Alloc > &pyramid, int fromLevel, int toLevel, double centerValue=0.4)
	Reconstruct a Laplacian pyramid. More...
template<... >
void	pyramidReduceBurtFilter (...)
	Two-fold down-sampling for image pyramid construction. More...
template<class Image , class Alloc >
void	pyramidReduceBurtLaplacian (ImagePyramid< Image, Alloc > &pyramid, int fromLevel, int toLevel, double centerValue=0.4)
	Create a Laplacian pyramid. More...
template<... >
void	resamplingConvolveImage (...)
	Apply two separable resampling filters successively, the first in x-direction, the second in y-direction. More...
template<... >
void	resamplingConvolveLine (...)
	Performs a 1-dimensional resampling convolution of the source signal using the given set of kernels. More...
template<... >
void	resamplingConvolveX (...)
	Apply a resampling filter in the x-direction. More...
template<... >
void	resamplingConvolveY (...)
	Apply a resampling filter in the y-direction. More...

Detailed Description

These functions implement the convolution operation when the source and target images have different sizes. This is realized by accessing a continuous kernel at the appropriate non-integer positions. The technique is, for example, described in D. Schumacher: General Filtered Image Rescaling, in: Graphics Gems III, Academic Press, 1992.

Function Documentation

void vigra::resamplingConvolveLine

(

...

)

Performs a 1-dimensional resampling convolution of the source signal using the given set of kernels.

This function is mainly used internally: It is called for each dimension of a higher dimensional array in order to perform a separable resize operation.

Declaration:

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

namespace vigra {
    template <class SrcIter, class SrcAcc,
              class DestIter, class DestAcc,
              class KernelArray,
              class Functor>
    void
    resamplingConvolveLine(SrcIter s, SrcIter send, SrcAcc src,
                           DestIter d, DestIter dend, DestAcc dest,
                           KernelArray const & kernels,
                           Functor mapTargetToSourceCoordinate)
}

void vigra::resamplingConvolveX

(

...

)

Apply a resampling filter in the x-direction.

This function implements a convolution operation in x-direction (i.e. applies a 1D filter to every row) where the width of the source and destination images differ. This is typically used to avoid aliasing if the image is scaled down, or to interpolate smoothly if the image is scaled up. The target coordinates are transformed into source coordinates by

xsource = (xtarget - offset) / samplingRatio

The samplingRatio and offset must be given as vigra::Rational in order to avoid rounding errors in this transformation. It is required that for all pixels of the target image, xsource remains within the range of the source image (i.e. 0 <= xsource <= sourceWidth-1. Since xsource is in general not an integer, the kernel must be a functor that can be accessed at arbitrary (double) coordinates. It must also provide a member function radius() which specifies the support (non-zero interval) of the kernel. VIGRA already provides a number of suitable functors, e.g. vigra::Gaussian, vigra::BSpline vigra::CatmullRomSpline, and vigra::CoscotFunction. The function resizeImageSplineInterpolation() is implemented by means of resamplingConvolveX() and resamplingConvolveY().

Declarations:

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2,
              class Kernel>
    void
    resamplingConvolveX(MultiArrayView<2, T1, S1> const & src,
                        MultiArrayView<2, T2, S2> dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIter, class SrcAcc,
              class DestIter, class DestAcc,
              class Kernel>
    void
    resamplingConvolveX(SrcIter sul, SrcIter slr, SrcAcc src,
                        DestIter dul, DestIter dlr, DestAcc dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIter, class SrcAcc,
              class DestIter, class DestAcc,
              class Kernel>
    void
    resamplingConvolveX(triple<SrcIter, SrcIter, SrcAcc> src,
                        triple<DestIter, DestIter, DestAcc> dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

Usage:

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

Rational<int> ratio(2), offset(0);

MultiArray<2, float> src(w,h),
                     dest(rational_cast<int>(ratio*w), h);

float sigma = 2.0;
Gaussian<float> smooth(sigma);
...

// simultaneously enlarge and smooth source image
resamplingConvolveX(src, dest,
                    smooth, ratio, offset);

show deprecated examples

Rational<int> ratio(2), offset(0);

FImage src(w,h),
       dest(rational_cast<int>(ratio*w), h);

float sigma = 2.0;
Gaussian<float> smooth(sigma);
...

// simultaneously enlarge and smooth source image
resamplingConvolveX(srcImageRange(src), destImageRange(dest),
                    smooth, ratio, offset);

Required Interface:

Kernel kernel;
int kernelRadius = kernel.radius();
double x = ...;  // must be <= radius()
double value = kernel(x);

void vigra::resamplingConvolveY

(

...

)

Apply a resampling filter in the y-direction.

This function implements a convolution operation in y-direction (i.e. applies a 1D filter to every column) where the height of the source and destination images differ. This is typically used to avoid aliasing if the image is scaled down, or to interpolate smoothly if the image is scaled up. The target coordinates are transformed into source coordinates by

ysource = (ytarget - offset) / samplingRatio

The samplingRatio and offset must be given as vigra::Rational in order to avoid rounding errors in this transformation. It is required that for all pixels of the target image, ysource remains within the range of the source image (i.e. 0 <= ysource <= sourceHeight-1. Since ysource is in general not an integer, the kernel must be a functor that can be accessed at arbitrary (double) coordinates. It must also provide a member function radius() which specifies the support (non-zero interval) of the kernel. VIGRA already provides a number of suitable functors, e.g. vigra::Gaussian, vigra::BSpline vigra::CatmullRomSpline, and vigra::CoscotFunction. The function resizeImageSplineInterpolation() is implemented by means of resamplingConvolveX() and resamplingConvolveY().

Declarations:

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2,
              class Kernel>
    void
    resamplingConvolveY(MultiArrayView<2, T1, S1> const & src,
                        MultiArrayView<2, T2, S2> dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIter, class SrcAcc,
              class DestIter, class DestAcc,
              class Kernel>
    void
    resamplingConvolveY(SrcIter sul, SrcIter slr, SrcAcc src,
                        DestIter dul, DestIter dlr, DestAcc dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIter, class SrcAcc,
              class DestIter, class DestAcc,
              class Kernel>
    void
    resamplingConvolveY(triple<SrcIter, SrcIter, SrcAcc> src,
                        triple<DestIter, DestIter, DestAcc> dest,
                        Kernel const & kernel,
                        Rational<int> const & samplingRatio, Rational<int> const & offset);
}

Usage:

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

Rational<int> ratio(2), offset(0);

MultiArray<2, float> src(w,h),
                     dest(w, rational_cast<int>(ratio*h));

float sigma = 2.0;
Gaussian<float> smooth(sigma);
...

// simultaneously enlarge and smooth source image
resamplingConvolveY(src, dest,
                    smooth, ratio, offset);

show deprecated examples

Rational<int> ratio(2), offset(0);

FImage src(w,h),
       dest(w, rational_cast<int>(ratio*h));

float sigma = 2.0;
Gaussian<float> smooth(sigma);
...

// simultaneously enlarge and smooth source image
resamplingConvolveY(srcImageRange(src), destImageRange(dest),
                    smooth, ratio, offset);

Required Interface:

Kernel kernel;
int kernelRadius = kernel.radius();
double y = ...;  // must be <= radius()
double value = kernel(y);

void vigra::resamplingConvolveImage

(

...

)

Apply two separable resampling filters successively, the first in x-direction, the second in y-direction.

This function is a shorthand for the concatenation of a call to resamplingConvolveX() and resamplingConvolveY() with the given kernels. See there for detailed documentation.

Declarations:

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2,
              class KernelX, class KernelY>
    void
    resamplingConvolveImage(MultiArrayView<2, T1, S1> const & src,
                            MultiArrayView<2, T2, S2> dest,
                            KernelX const & kx,
                            Rational<int> const & samplingRatioX, Rational<int> const & offsetX,
                            KernelY const & ky,
                            Rational<int> const & samplingRatioY, Rational<int> const & offsetY);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class KernelX, class KernelY>
    void resamplingConvolveImage(SrcIterator sul,SrcIterator slr, SrcAccessor src,
                       DestIterator dul, DestIterator dlr, DestAccessor dest,
                       KernelX const & kx,
                       Rational<int> const & samplingRatioX, Rational<int> const & offsetX,
                       KernelY const & ky,
                       Rational<int> const & samplingRatioY, Rational<int> const & offsetY);
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class KernelX, class KernelY>
    void
    resamplingConvolveImage(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                       triple<DestIterator, DestIterator, DestAccessor> dest,
                       KernelX const & kx,
                       Rational<int> const & samplingRatioX, Rational<int> const & offsetX,
                       KernelY const & ky,
                       Rational<int> const & samplingRatioY, Rational<int> const & offsetY);
}

Usage:

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

Rational<int> xratio(2), yratio(3), offset(0);

MultiArray<2, float> src(w,h),
                     dest(rational_cast<int>(xratio*w), rational_cast<int>(yratio*h));

float sigma = 2.0;
Gaussian<float> smooth(sigma);
...

// simultaneously enlarge and smooth source image
resamplingConvolveImage(src, dest,
                        smooth, xratio, offset,
                        smooth, yratio, offset);

void vigra::pyramidReduceBurtFilter

(

...

)

Two-fold down-sampling for image pyramid construction.

This function implements the reduction by one resolution level (first signature) or across several pyramid levels (last signature) of a Gaussian pyramid as described in

P. Burt, E. Adelson: "The Laplacian Pyramid as a Compact Image Code", IEEE Trans. Communications, 9(4):532-540, 1983

That is, it applies the smoothing filter

[0.25 - centerValue / 2.0, 0.25, centerValue, 0.25, 0.25 - centerValue / 2.0]

to the source image and then copies all pixels with even coordinates to the destination image. The destination image shape must be dest_shape = ceil(src_shape / 2.0). centerValue must be between 0.25 and 0.5 and determines the strength of smoothing (bigger values correspond to less smoothing). If toLevel - fromLevel > 1 in the pyramid variant of the function, this process is repeated until toLevel is reached.

Typically, this functions is used in connection with a vigra::ImagePyramid (last signature below) to perform several levels of reduction in one go.

Declarations:

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

pass 2D array views:

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidReduceBurtFilter(SrcIterator sul, SrcIterator slr, SrcAccessor src,
                                 DestIterator dul, DestIterator dlr, DestAccessor dest,
                                 double centerValue = 0.4);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidReduceBurtFilter(SrcIterator sul, SrcIterator slr, SrcAccessor src,
                                 DestIterator dul, DestIterator dlr, DestAccessor dest,
                                 double centerValue = 0.4);
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidReduceBurtFilter(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                                 triple<DestIterator, DestIterator, DestAccessor> dest,
                                 double centerValue = 0.4);
}

use a vigra::ImagePyramid :

namespace vigra {
    template <class Image, class Alloc>
    void pyramidReduceBurtFilter(ImagePyramid<Image, Alloc> & pyramid,
                                 int fromLevel, int toLevel,
                                 double centerValue = 0.4);
}

void vigra::pyramidExpandBurtFilter

(

...

)

Two-fold up-sampling for image pyramid reconstruction.

This function implements the expansion by one resolution level (first signature) or across several pyramid levels (last signature) of a Gaussian pyramid as described in

P. Burt, E. Adelson: "The Laplacian Pyramid as a Compact Image Code", IEEE Trans. Communications, 9(4):532-540, 1983

That is, the function first places the pixel values of the low-resolution image at the even pixel coordinates of the high-resolution image (pixels with at least one odd coordinate are zero-initialized) and then applies the interpolation filter

[0.5 - centerValue, 0.5, 2*centerValue, 0.5, 0.5 - centerValue]

to the high-resolution image. The source image shape must be src_shape = ceil(dest_shape / 2.0). centerValue must be between 0.25 and 0.5 and determines the sharpness of the interpolation (bigger values correspond to sharper images). If fromLevel - toLevel > 1 in the pyramid variant of the function, this process is repeated until toLevel is reached.

Typically, this functions is used in connection with a vigra::ImagePyramid (last signature below) to perform several levels of expansion in one go.

Declarations:

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

pass 2D array views:

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidExpandBurtFilter(SrcIterator sul, SrcIterator slr, SrcAccessor src,
                                 DestIterator dul, DestIterator dlr, DestAccessor dest,
                                 double centerValue = 0.4);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidExpandBurtFilter(SrcIterator sul, SrcIterator slr, SrcAccessor src,
                                 DestIterator dul, DestIterator dlr, DestAccessor dest,
                                 double centerValue = 0.4);
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void pyramidExpandBurtFilter(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                                 triple<DestIterator, DestIterator, DestAccessor> dest,
                                 double centerValue = 0.4);
}

use a vigra::ImagePyramid :

namespace vigra {
    template <class Image, class Alloc>
    void pyramidExpandBurtFilter(ImagePyramid<Image, Alloc> & pyramid,
                                 int fromLevel, int toLevel,
                                 double centerValue = 0.4);
}

void vigra::pyramidReduceBurtLaplacian	(	ImagePyramid< Image, Alloc > &	pyramid,
		int	fromLevel,
		int	toLevel,
		double	centerValue = 0.4
	)

Create a Laplacian pyramid.

This function implements the reduction across several resolution levels of a Laplacian pyramid as described in

P. Burt, E. Adelson: "The Laplacian Pyramid as a Compact Image Code", IEEE Trans. Communications, 9(4):532-540, 1983

It first creates a Gaussian pyramid using pyramidReduceBurtFilter(), then upsamples each level once using pyramidExpandBurtFilter(), and finally stores the difference between the upsampled and original versions of each level (i.e. the Laplacian of Gaussian is approximated by a difference of Gaussian).

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

void vigra::pyramidExpandBurtLaplacian	(	ImagePyramid< Image, Alloc > &	pyramid,
		int	fromLevel,
		int	toLevel,
		double	centerValue = 0.4
	)

Reconstruct a Laplacian pyramid.

This function implements the reconstruction of a Gaussian pyramid across several resolution levels of a Laplacian pyramid as described in

P. Burt, E. Adelson: "The Laplacian Pyramid as a Compact Image Code", IEEE Trans. Communications, 9(4):532-540, 1983

At each level starting from fromLevel, this function calls pyramidExpandBurtFilter() to interpolate the image to the next highest resolution, and then adds the interpolated image to the image stored at the next level.

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