iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GenericImageOperators.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_IMAGE_GENERICIMAGEOPERATORS_H
37 #define INCLUDE_NRT_CORE_IMAGE_GENERICIMAGEOPERATORS_H
38 
39 #include <nrt/Core/Image/GenericImage.H>
40 
41 namespace nrt
42 {
43  // ######################################################################
44  /*! \defgroup genericimageoperators GenericImage Operators
45 
46  Operator overloads for GenericImage. Note that in the philosophy of explicit constructors we here do not implement
47  operators that mix a GenericImage and an Image<T>; users should instead explicitly convert one of the two
48  operands, e.g.,
49 
50  \code
51  nrt::GenericImage im1; nrt::Image<nrt::PixRGB<float> > im2;
52  nrt::GenericImage result = im1 + nrt::GenericImage(im2);
53  \endcode
54 
55  We also do not define unary arithmetic operators, as those would be potentially confusing: for example, for
56  GenericImage operator+=(GenericImage), what if the lhs is an Image<PixGray<byte>> and the rhs is an
57  Image<PixRGB<byte>>? Should we return a GenericImage that contains the same type as the lhs (confusing to people
58  who may assume that GenericImage is like "any image"), or a GenericImage that contains a properly promoted
59  Image<PixRGB<int>> (confusing to people who believe unary operators should not change the lhs type). So to avoid
60  any possible confusion, unary arithmetic operators are not defined on GenericImage and one should instead use
61  binary operators (operator+(), operator-(), etc).
62 
63  Note that GenericImage operators are not fully symmetric and the following applies; note that LHS and RHS can here
64  be either a GenericImage with inside an Image of a certain Pixtype, or they can just be a constant of that
65  Pixtype:
66 
67  - If LHS and RHS Pixtype can be operated, i.e., nrt::nrt_traits<T,U>::has_arithmetic is true, then the
68  GenericImage result from the operation contains an Image of whichever type the pixel arithmetic operation
69  returns. This should cover most cases that make sense in practice. However, GenericImage must cover all cases,
70  so the other cases are as follows:
71 
72  - Otherwise, if LHS has same or more channels than RHS, result is of same Pixel type as LHS (possibly
73  promoted). Internally we first convert (expensive, pixel-by-pixel) RHS to the pixel type of LHS (possibly
74  promoted), and then we apply the operator;
75 
76  - Otherwise (LHS has strictly fewer channels than RHS), result is of same Pixel type as RHS (possibly
77  promoted). Internally we first convert (expensive, pixel-by-pixel) LHS to the pixel type of RHS (possibly
78  promoted), and then we apply the operator.
79 
80  The asymmetry comes from incompatible types with same number of channels, for example
81  GenericImage(PixRGB<byte>) + GenericImage(PixHSV<float>) is a GenericImage(PixRGB<float>) but
82  GenericImage(PixHSV<byte>) + GenericImage(PixRGB<float>) is a GenericImage(PixHSV<float>), i.e., LHS determines
83  the pixel type.
84 
85  \ingroup genericimage
86  \see image */
87 
88  /*! @{ */ // **********************************************************************
89 
90 #define NRT_ENABLE_IF_PIXEL(PixType) \
91  typename=typename std::enable_if<pixel_helper::is_pixel<PixType>::value>::type
92 
93  //! Pointwise addition of two GenericImage images: GenericImage + GenericImage
94  GenericImage operator+(GenericImage const & lhs, GenericImage const& rhs);
95 
96  //! Addition of a constant to every pixel in a GenericImage: GenericImage + T
97  template <class PixType2, NRT_ENABLE_IF_PIXEL(PixType2)>
98  GenericImage operator+(GenericImage const & lhs, PixType2 const & rhs);
99 
100  //! Addition of a constant to every pixel in a GenericImage: T + GenericImage
101  template <class PixType1, NRT_ENABLE_IF_PIXEL(PixType1)>
102  GenericImage operator+(PixType1 const & lhs, GenericImage const & rhs);
103 
104  //! Pointwise subtraction of two GenericImage objects: GenericImage - GenericImage
105  GenericImage operator-(GenericImage const & lhs, GenericImage const& rhs);
106 
107  //! Subtraction of a constant from every pixel in a GenericImage: GenericImage - T
108  template <class PixType2, NRT_ENABLE_IF_PIXEL(PixType2)>
109  GenericImage operator-(GenericImage const & lhs, PixType2 const & rhs);
110 
111  //! Subtraction of every pixel of a GenericImage from a constant: T - GenericImage
112  template <class PixType1, NRT_ENABLE_IF_PIXEL(PixType1)>
113  GenericImage operator-(PixType1 const & lhs, GenericImage const & rhs);
114 
115  //! Pointwise product of two GenericImage images: GenericImage * GenericImage
116  GenericImage operator*(GenericImage const & lhs, GenericImage const& rhs);
117 
118  //! Product of everypixel of a GenericImage by a constant: GenericImage * T
119  template <class PixType2, NRT_ENABLE_IF_PIXEL(PixType2)>
120  GenericImage operator*(GenericImage const & lhs, PixType2 const & rhs);
121 
122  //! Product of everypixel of a GenericImage by a constant: T * GenericImage
123  template <class PixType1, NRT_ENABLE_IF_PIXEL(PixType1)>
124  GenericImage operator*(PixType1 const & lhs, GenericImage const & rhs);
125 
126  //! Pointwise division of two GenericImage images: GenericImage / GenericImage
127  /*! \note Will throw if a division by zero is encountered. */
128  GenericImage operator/(GenericImage const & lhs, GenericImage const& rhs);
129 
130  //! Division of every pixel of a GenericImage by a constant: GenericImage / T
131  /*! \note Will throw if a division by zero is encountered. */
132  template <class PixType2, NRT_ENABLE_IF_PIXEL(PixType2)>
133  GenericImage operator/(GenericImage const & lhs, PixType2 const & rhs);
134 
135  //! Division of a constant by every pixel of a GenericImage: T / GenericImage
136  /*! \note Will throw if a division by zero is encountered. */
137  template <class PixType1, NRT_ENABLE_IF_PIXEL(PixType1)>
138  GenericImage operator/(PixType1 const & lhs, GenericImage const & rhs);
139 
140  /*! @} */ // **********************************************************************
141 
142 } // nrt
143 
144 #undef NRT_ENABLE_IF_PIXEL
145 
146 #include <nrt/Core/Image/details/GenericImageOperatorsImpl.H>
147 
148 #endif // INCLUDE_NRT_CORE_IMAGE_GENERICIMAGEOPERATORS_H
149