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

details ConvolutionOptions< dim > Class Template Reference VIGRA

Options class template for convolutions. More...

#include <vigra/multi_convolution.hxx>

Public Member Functions

ConvolutionOptions< dim > & filterWindowSize (double ratio)
 
ConvolutionOptions< dim > & innerScale (...)
 
ConvolutionOptions< dim > & outerScale (...)
 
ConvolutionOptions< dim > & resolutionStdDev (...)
 
ConvolutionOptions< dim > & stdDev (...)
 
ConvolutionOptions< dim > & stepSize (...)
 
ConvolutionOptions< dim > & subarray (Shape const &from, Shape const &to)
 

Detailed Description

template<unsigned dim>
class vigra::ConvolutionOptions< dim >

Options class template for convolutions.

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

This class enables the calculation of scale space convolutions such as gaussianGradientMultiArray() on data with anisotropic discretization. For these, the result of the ordinary calculation has to be multiplied by factors of $1/w^{n}$ for each dimension, where $w$ is the step size of the grid in said dimension and $n$ is the differential order of the convolution, e.g., 1 for gaussianGradientMultiArray(), and 0 for gaussianSmoothMultiArray(), respectively. Also for each dimension in turn, the convolution's scale parameter $\sigma$ has to be replaced by $\sqrt{\sigma_\mathrm{eff}^2 - \sigma_\mathrm{D}^2}\Big/w$, where $\sigma_\mathrm{eff}$ is the resulting effective filtering scale. The data is assumed to be already filtered by a gaussian smoothing with the scale parameter $\sigma_\mathrm{D}$ (such as by measuring equipment). All of the above changes are automatically employed by the convolution functions for MultiArrays if a corresponding options object is provided.

The ConvolutionOptions class must be parameterized by the dimension dim of the MultiArrays on which it is used. The actual per-axis options are set by (overloaded) member functions explained below, or else default to neutral values corresponding to the absence of the particular option.

All member functions set dim values of the respective convolution option, one for each dimension. They may be set explicitly by multiple arguments for up to five dimensions, or by a single argument to the same value for all dimensions. For the general case, a single argument that is either a C-syle array, an iterator, or a C++ standard library style sequence (such as std::vector, with member functions begin() and size()) supplies the option values for any number of dimensions.

Note that the return value of all member functions is *this, which provides the mechanism for concatenating member function calls as shown below.

usage with explicit parameters:

ConvolutionOptions<2> opt = ConvolutionOptions<2>().stepSize(1, 2.3);

usage with arrays:

const double step_size[3] = { x_scale, y_scale, z_scale };
ConvolutionOptions<3> opt = ConvolutionOptions<3>().stepSize(step_size);

usage with C++ standard library style sequences:

TinyVector<double, 4> step_size(1, 1, 2.0, 1.5);
TinyVector<double, 4> r_sigmas(1, 1, 2.3, 3.2);
ConvolutionOptions<4> opt = ConvolutionOptions<4>().stepSize(step_size).resolutionStdDev(r_sigmas);

usage with iterators:

ArrayVector<double> step_size;
step_size.push_back(0);
step_size.push_back(3);
step_size.push_back(4);
ArrayVector<double>::iterator i = step_size.begin();
++i;
ConvolutionOptions<2> opt = ConvolutionOptions<2>().stepSize(i);

general usage in a convolution function call:

MultiArray<3, double> test_image;
MultiArray<3, double> out_image;
double scale = 5.0;
gaussianSmoothMultiArray(test_image, out_image, scale,
ConvolutionOptions<3>()
.stepSize (1, 1, 3.2)
.resolutionStdDev(1, 1, 4)
);

Member Function Documentation

ConvolutionOptions<dim>& stepSize (   ...)

Step size(s) per axis, i.e., the distance between two adjacent pixels. Required for MultiArray containing anisotropic data.

Note that a convolution containing a derivative operator of order n results in a multiplication by ${\rm stepSize}^{-n}$ for each axis. Also, the above standard deviations are scaled according to the step size of each axis. Default value for the options object if this member function is not used: A value of 1.0 for each dimension.

ConvolutionOptions<dim>& resolutionStdDev (   ...)

Resolution standard deviation(s) per axis, i.e., a supposed pre-existing gaussian filtering by this value.

The standard deviation actually used by the convolution operators is $\sqrt{{\rm sigma}^{2} - {\rm resolutionStdDev}^{2}}$ for each axis. Default value for the options object if this member function is not used: A value of 0.0 for each dimension.

ConvolutionOptions<dim>& stdDev (   ...)

Standard deviation(s) of scale space operators, or inner scale(s) for structureTensorMultiArray().

Usually not needed, since a single value for all axes may be specified as a parameter sigma to the call of an convolution operator such as gaussianGradientMultiArray(), and anisotropic data requiring the use of the stepSize() member function. Default value for the options object if this member function is not used: A value of 0.0 for each dimension.

ConvolutionOptions<dim>& innerScale (   ...)

Standard deviation(s) of scale space operators, or inner scale(s) for structureTensorMultiArray().

Usually not needed, since a single value for all axes may be specified as a parameter sigma to the call of an convolution operator such as gaussianGradientMultiArray(), and anisotropic data requiring the use of the stepSize() member function. Default value for the options object if this member function is not used: A value of 0.0 for each dimension.

ConvolutionOptions<dim>& outerScale (   ...)

Standard deviation(s) of the second convolution of the structure tensor.

Usually not needed, since a single value for all axes may be specified as a parameter outerScale to the call of structureTensorMultiArray(), and anisotropic data requiring the use of the stepSize() member function. Default value for the options object if this member function is not used: A value of 0.0 for each dimension.

ConvolutionOptions<dim>& filterWindowSize ( double  ratio)

Size of the filter window as a multiple of the scale parameter.

This option is only used for Gaussian filters and their derivatives. By default, the window size of a Gaussian filter is automatically determined such that the error resulting from restricting the infinitely large Gaussian function to a finite size is minimized. In particular, the window radius is determined as radius = round(3.0 * sigma + 0.5 * order), where 'order' is the desired derivative order. In some cases, it is desirable to trade off accuracy for speed, and this function can be used to request a smaller window radius.

Default: 0.0 (i.e. determine the window size automatically)

ConvolutionOptions<dim>& subarray ( Shape const &  from,
Shape const &  to 
)

Restrict the filter to a subregion of the input array.

This is useful for speeding up computations by ignoring irrelevant areas in the array. Note: It is assumed that the output array of the convolution has the size given in this function. Negative ROI boundaries are interpreted relative to the end of the respective dimension (i.e. if(to[k] < 0) to[k] += source.shape(k);).

Default: from = Shape(), to = Shape() (i.e. use entire array)

The documentation for this class was generated from the following file:

© 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.11.1 (Fri May 19 2017)