iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Image macros to facilitate promotion of pixel types

To understand the important discussion below, first be sure to understand Promotions.H

Often, when performing an Image processing operation we want to return an result image that has the pixel type most appropriate to contain the result of the operation. For example, we may have some function called "process" that takes in a single Image, does some work on it, and returns the result. The most naive approach is to just use the same pixel type for the result as for the input:

template <class PixType>

However, potentially this will lose data (because of limited range of PixType, for example if PixType is byte). For example, consider the case where process simply multiplies all pixels in the image by some fixed constant. Ideally, the return image should have pixels of type which is the correct type to hold the result of a source pixel multiplied by that constant. For example, if PixType is nrt::PixRBG<nrt::byte> and the constant is a float, then the result pixel type should be nrt::PixRGB<float>. One laborious solution to this is to just tell users that they should carefully choose their result pixel type, and to make it a template parameter:

template <class DestinationPixType, SourcePixType>

A much better and more elegant solution is the following template pattern:

template<typename promo, class PixType, typename DestType = typename nrt::promote<PixType, promo>::type>

The user can then call the function process like so:

nrt::Image<nrt::PixGray<float> > output = process<float>(input);

This fancy mechanism will ensure that the returned 'DestType' is never less restrictive than 'promo' or 'PixType', thus ensuring that we will never lose bits in the computations through a conversion to 'DestType'.

Now, one can also specify promo=void, which will always resolve to DestType = PixType, causing no conversion at all.

As a matter of standardization, programmers of NRT image processing functions should use one of the following macros to embody this pattern:

Image<PixGray<byte> > input; // some image
// Using the macro NRT_PROMOTE_PIX(default_promo) will specify a default promotion type so that users don't
// have to. Note that the parameter to this macro (void, in this case) could be replaced with any type you want -
// void, int, float, whatever...
template <NRT_PROMOTE_PIX(void)>
// Example usage:
nrt::Image<PixGray<byte> > output1 = process1(input); // ok, default promo is void
nrt::Image<PixGray<float> > output2 = process1<float>(input); // ok, explicit promo to float
// Using the macro NRT_PROMOTE_PIX_NO_DEFAULT will not specify a default promotion type, so users will be
// forced to specify one when they call the method. This is also the macro to use in function definitions.
template <NRT_PROMOTE_PIX_NO_DEFAULT>
// Example usage:
nrt::Image<PixGray<double> > output3 = process2<double>(input); // ok, promo specification is required
See Also
Image class template and related classes and functions

Macros

#define NRT_PROMOTE_PIX(default_promo)
 
#define NRT_PROMOTE_PIX_NO_DEFAULT_PROMO
 
#define NRT_PROMOTE_PIX_NO_DEFAULT
 

Macro Definition Documentation

#define NRT_PROMOTE_PIX (   default_promo)

A shortcut mechanism for performing type promotions on pixel types. The source pixel type must be named PixType, and the destination (promoted) pixel type must be named DestType

See Also
NRT_PROMOTE_PIX_NO_DEFAULT

Definition at line 133 of file Macros.H.

#define NRT_PROMOTE_PIX_NO_DEFAULT_PROMO

A shortcut mechanism for performing type promotions on pixel types with no default promotion. The source pixel type must be named PixType, and the destination (promoted) pixel type must be named DestType

See Also
NRT_PROMOTE_PIX_NO_DEFAULT(default_promo)

Definition at line 143 of file Macros.H.

#define NRT_PROMOTE_PIX_NO_DEFAULT

A shortcut mechanism for performing type promotions on pixel types with no default promotion. The source pixel type must be named PixType, and the destination (promoted) pixel type must be named DestType

See Also
NRT_PROMOTE_PIX(default_promo)

Definition at line 153 of file Macros.H.