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

Argument Object Factories VIGRA

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

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