iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Macros.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_TYPING_MACROS_H
37 #define INCLUDE_NRT_CORE_TYPING_MACROS_H
38 
39 //! General NRT Macros. These should all use the NRT_MACRO_ prefix
40 
41 //! Get a string from a raw constant like __LINE__
42 #define NRT_MACRO_STRINGIFY(x) #x
43 
44 //! Get a string, level 2 indirection
45 #define NRT_MACRO_TOSTRING(x) NRT_MACRO_STRINGIFY(x)
46 
47 //! Macro to indicate the file and location as an std::string
48 #define NRT_MACRO_WHERE (std::string(__FILE__ ":" NRT_MACRO_TOSTRING(__LINE__) "::")+std::string(__PRETTY_FUNCTION__))
49 
50 
51 /*! \defgroup imagepromo Image macros to facilitate promotion of pixel types
52 
53  To understand the important discussion below, first be sure to understand Promotions.H
54 
55  Often, when performing an Image processing operation we want to return an result image that has the pixel type most
56  appropriate to contain the result of the operation. For example, we may have some function called "process" that
57  takes in a single Image, does some work on it, and returns the result. The most naive approach is to just use the
58  same pixel type for the result as for the input:
59 
60  @code
61  template <class PixType>
62  nrt::Image<PixType> process(nrt::Image<PixType> input);
63  @endcode
64 
65  However, potentially this will lose data (because of limited range of PixType, for example if PixType is byte). For
66  example, consider the case where process simply multiplies all pixels in the image by some fixed constant. Ideally,
67  the return image should have pixels of type which is the correct type to hold the result of a source pixel
68  multiplied by that constant. For example, if PixType is nrt::PixRBG<nrt::byte> and the constant is a float, then the
69  result pixel type should be nrt::PixRGB<float>. One laborious solution to this is to just tell users that they
70  should carefully choose their result pixel type, and to make it a template parameter:
71 
72  @code
73  template <class DestinationPixType, SourcePixType>
74  nrt::Image<DestinationPixType> process(nrt::Image<SourcePixType> input);
75  @endcode
76 
77  A much better and more elegant solution is the following template pattern:
78 
79  @code
80  template<typename promo, class PixType, typename DestType = typename nrt::promote<PixType, promo>::type>
81  nrt::Image<DestType> process(nrt::Image<PixType> input);
82  @endcode
83 
84  The user can then call the function process like so:
85 
86  @code
87  nrt::Image<nrt::PixGray<nrt::byte> > input;
88  nrt::Image<nrt::PixGray<float> > output = process<float>(input);
89  @endcode
90 
91  This fancy mechanism will ensure that the returned 'DestType' is never less restrictive than 'promo' or 'PixType',
92  thus ensuring that we will never lose bits in the computations through a conversion to 'DestType'.
93 
94  Now, one can also specify promo=void, which will always resolve to DestType = PixType, causing no conversion at all.
95 
96  As a matter of standardization, programmers of NRT image processing functions should use one of the following macros
97  to embody this pattern:
98 
99  @code
100  Image<PixGray<byte> > input; // some image
101 
102  // Using the macro NRT_PROMOTE_PIX(default_promo) will specify a default promotion type so that users don't
103  // have to. Note that the parameter to this macro (void, in this case) could be replaced with any type you want -
104  // void, int, float, whatever...
105  template <NRT_PROMOTE_PIX(void)>
106  nrt::Image<DestType> process1(nrt::Image<PixType> input) { ... }
107 
108  // Example usage:
109  nrt::Image<PixGray<byte> > output1 = process1(input); // ok, default promo is void
110  nrt::Image<PixGray<float> > output2 = process1<float>(input); // ok, explicit promo to float
111 
112  // Using the macro NRT_PROMOTE_PIX_NO_DEFAULT will not specify a default promotion type, so users will be
113  // forced to specify one when they call the method. This is also the macro to use in function definitions.
114  template <NRT_PROMOTE_PIX_NO_DEFAULT>
115  nrt::Image<DestType> process2(nrt::Image<PixType> input) { ... }
116 
117  // Example usage:
118  nrt::Image<PixGray<double> > output3 = process2<double>(input); // ok, promo specification is required
119  @endcode
120 
121  \ingroup image
122  \see image */
123 
124 /*! @{ */ // **********************************************************************
125 
126 /*! \def NRT_PROMOTE_PIX(default_promo)
127  \hideinitializer
128 
129  A shortcut mechanism for performing type promotions on pixel types. The source pixel type must be named \c PixType,
130  and the destination (promoted) pixel type must be named \c DestType
131 
132  \see #NRT_PROMOTE_PIX_NO_DEFAULT */
133 #define NRT_PROMOTE_PIX(default_promo) \
134  typename promo = default_promo, class PixType, typename DestType = typename nrt::promote<PixType, promo>::type
135 
136 /*! \def NRT_PROMOTE_PIX_NO_DEFAULT_PROMO
137  \hideinitializer
138 
139  A shortcut mechanism for performing type promotions on pixel types with no default promotion. The source pixel type
140  must be named \c PixType, and the destination (promoted) pixel type must be named \c DestType
141 
142  \see #NRT_PROMOTE_PIX_NO_DEFAULT(default_promo) */
143 #define NRT_PROMOTE_PIX_NO_DEFAULT_PROMO \
144  typename promo, class PixType, typename DestType = typename nrt::promote<PixType, promo>::type
145 
146 /*! \def NRT_PROMOTE_PIX_NO_DEFAULT
147  \hideinitializer
148 
149  A shortcut mechanism for performing type promotions on pixel types with no default promotion. The source pixel type
150  must be named \c PixType, and the destination (promoted) pixel type must be named \c DestType
151 
152  \see #NRT_PROMOTE_PIX(default_promo) */
153 #define NRT_PROMOTE_PIX_NO_DEFAULT \
154  typename promo, class PixType, typename DestType
155 
156 /*! @} */ // **********************************************************************
157 
158 #endif // INCLUDE_NRT_CORE_TYPING_MACROS_H
159