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

| ConvolutionOptions< dim > Class Template Reference |

Options class template for convolutions. More...

`#include <vigra/multi_convolution.hxx>`

List of all members.

## 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>

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 for each dimension, where is the step size of the grid in said dimension and 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 has to be replaced by , where is the resulting effective filtering scale. The data is assumed to be already filtered by a gaussian smoothing with the scale parameter (such as by measuring equipment). All of the above changes are automatically employed by the convolution functions for `MultiArray`s if a corresponding options object is provided.

The `ConvolutionOptions` class must be parameterized by the dimension `dim` of the `MultiArray`s 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;
      gaussianSmoothMultiArray(srcMultiArrayRange(test_image),
                               destMultiArray(out_image),
                               5.0,
                               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 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 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.

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

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

- vigra/multi_convolution.hxx

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