vigra - Argument Object Factories

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

Argument Object Factories |

Factory functions to create argument objects which simplify long argument lists.

- Image Based Argument Object Factories
- MultiArrayView Based Argument Object Factories
- Iterator Based Argument Object Factories

Long argument lists provide for greater flexibility of functions, but they are also tedious and error prone, when we don't need the flexibility. Thus, we define argument objects which automatically provide reasonable defaults for those arguments that we didn't specify explicitly.

The argument objects are created via a number of factory functions. Since these functions have descriptive names, they also serve to improve readability: the name of each factory tells the purpose of its argument object.

Consider the following example. Without argument objects we had to write something like this (cf. copyImageIf()):

vigra::BImage img1, img2, img3;
// fill img1 and img2 ...
vigra::copyImageIf(img1.upperLeft(), img1.lowerRight(), img1.accessor(),
img2.upperLeft(), img2.accessor(),
img3.upperLeft(), img3.accessor());

Using the argument object factories, this becomes much shorter and more readable:

vigra::copyImageIf(srcImageRange(img1),
maskImage(img2),
destImage(img3));

The names of the factories clearly tell which image is source, mask, and destination. In addition, the suffix `Range` must be used for those argument objects that need to specify the lower right corner of the region of interest. Typically, this is only the first source argument, but sometimes the first destiniation argument must also contain a range.

The factory functions come in two flavours: Iterator based and image based factories. Above we have seen the image based variant. The iterator based variant would look like this:

vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
maskIter(img2.upperLeft()),
destIter(img3.upperLeft()));

These factory functions contain the word `Iter` instead of the word `Image`, They would normally be used if we couldn't access the images (for example, within a function which got passed iterators) or if we didn't want to operate on the entire image. The default accessor is obtained via vigra::IteratorTraits.

All factory functions also allow to specify accessors explicitly. This is useful if we can't use the default accessor. This variant looks like this:

vigra::copyImageIf(srcImageRange(img1),
maskImage(img2, MaskPredicateAccessor()),
destImage(img3));

or

vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
maskIter(img2.upperLeft(), MaskPredicateAccessor()),
destIter(img3.upperLeft()));

All versions can be mixed freely within one expression. Technically, the argument objects are simply defined as pairs and triples of iterators and accessor so that all algorithms should declare a call interface version based on pairs and triples (see for example copyImageIf()).

# Image Based Argument Object Factories

Include: automatically included with the image classes
Namespace: vigra

These factories can be used to create argument objects when we are given instances or subclasses of vigra::BasicImage (see Standard Image Types for instances defined per default). These factory functions access `img.upperLeft()`, `img.lowerRight()`, and `img.accessor()` to obtain the iterators and accessor for the given image (unless the accessor is given explicitly). The following factory functions are provided:

`vigra::BasicImage<SomeType> img;` or `vigra::BasicImageView<SomeType> img;`
`srcImageRange(img)` | create argument object containing upper left, lower right, and default accessor of source image
`srcImageRange(img, Rect2D(...))` | create argument object containing the ROI specified by `vigra::Rect2D` and default accessor of source image
`srcImageRange(img, SomeAccessor())` | create argument object containing upper left, lower right of source image, and given accessor
`srcImageRange(img, Rect2D(...), SomeAccessor())` | create argument object containing the ROI specified by `vigra::Rect2D` and of source image, and given accessor
`srcImage(img)` | create argument object containing upper left, and default accessor of source image
`srcImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of source image
`srcImage(img, SomeAccessor())` | create argument object containing upper left of source image, and given accessor
`srcImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of source image, and given accessor
`maskImage(img)` | create argument object containing upper left, and default accessor of mask image
`maskImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of mask image
`maskImage(img, SomeAccessor())` | create argument object containing upper left of mask image, and given accessor
`maskImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of mask image, and given accessor
`destImageRange(img)` | create argument object containing upper left, lower right, and default accessor of destination image
`destImageRange(img, Rect2D(...))` | create argument object containing the ROI specified by `vigra::Rect2D` and default accessor of destination image
`destImageRange(img, SomeAccessor())` | create argument object containing upper left, lower right of destination image, and given accessor
`destImageRange(img, Rect2D(...), SomeAccessor())` | create argument object containing the ROI specified by `vigra::Rect2D` of destination image, and given accessor
`destImage(img)` | create argument object containing upper left, and default accessor of destination image
`destImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of destination image
`destImage(img, SomeAccessor())` | create argument object containing upper left of destination image, and given accessor
`destImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of destination image, and given accessor

# MultiArrayView Based Argument Object Factories

Include: automatically included with <vigra/multi_array.hxx>
Namespace: vigra

These factories can be used to create argument objects when we are given instances or subclasses of vigra::MultiArrayView. These factory functions access `array.traverser_begin()`, `array.traverser_end()` to obtain the iterators. If no accessor is given, they use the `AccessorTraits<T>` to determine the default accessor associated with the array's value type `T`. The following factory functions are provided:

`vigra::MultiArrayView<N, SomeType> img;`
`srcMultiArrayRange(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the default const accessor for `SomeType`
`srcMultiArrayRange(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the given accessor
`srcMultiArray(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, and the default const accessor for `SomeType`
`srcMultiArray(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator marking the begin of the array and the given accessor
`destMultiArrayRange(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the default accessor for `SomeType`
`destMultiArrayRange(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator's marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the given accessor
`destMultiArray(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array and the default accessor for `SomeType`
`destMultiArray(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator's marking the begin of the array and the given accessor

# Iterator Based Argument Object Factories

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

These factories can be used to create argument objects when we are given Image Iterators. These factory functions use vigra::IteratorTraits to get the default accessor for the given iterator unless the accessor is given explicitly. The following factory functions are provided:

`vigra::BasicImage<SomeType>::Iterator i1, i2;`
`srcIterRange(i1, i2)` | create argument object containing the given iterators and corresponding default accessor (for source image)
`srcIterRange(i1, i2, SomeAccessor())` | create argument object containing given iterators and accessor (for source image)
`srcIter(i1)` | create argument object containing the given iterator and corresponding default accessor (for source image)
`srcIter(i1, SomeAccessor())` | create argument object containing given iterator and accessor (for source image)
`maskIter(i1)` | create argument object containing the given iterator and corresponding default accessor (for mask image)
`maskIter(i1, SomeAccessor())` | create argument object containing given iterator and accessor (for mask image)
`destIterRange(i1, i2)` | create argument object containing the given iterators and corresponding default accessor (for destination image)
`destIterRange(i1, i2, SomeAccessor())` | create argument object containing given iterators and accessor (for destination image)
`destIter(i1)` | create argument object containing the given iterator and corresponding default accessor (for destination image)
`destIter(i1, SomeAccessor())` | create argument object containing given iterator and accessor (for destination image)

© 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.0 (Thu Mar 17 2016)