iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GenericImage.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 #ifndef INCLUDE_NRT_CORE_IMAGE_GENERICIMAGE_H
36 #define INCLUDE_NRT_CORE_IMAGE_GENERICIMAGE_H
37 
38 #include <nrt/config.h>
39 #include <nrt/Core/Image/Image.H>
41 
42 #include <boost/variant.hpp>
43 #include <boost/mpl/copy.hpp>
44 
45 #include <nrt/External/cereal/types/boost_variant.hpp>
46 
47 namespace nrt
48 {
49  /*! \defgroup genericimage GenericImage class and concepts
50 
51  GenericImage is a thin wrapper for an Image of any pixel type. Writing general algorithms that work with
52  GenericImage allows them to apply to any image type. Modules that perform image processing should very strongly
53  try to handle nrt::Message<nrt::GenericImage> as their input (subscriber) and output (poster) messages, to ensure
54  maximum inter-operatibility with other image processing modules.
55 
56  \ingroup imagerel */
57 
58  /*! @{ */ // **********************************************************************
59 
60  //! A container that acts as a smart "union" of a few popular Image types.
61  /*! The GenericImage class allows Image data to be passed around in a native format, thus deferring conversion. This
62  is particuarly useful in the nrt::ImageSource and nrt::ImageSink classes:
63 
64  - The nrt::ImageSource returns a GenericImage from its in() method allowing users to receive and then transfer
65  incoming images in their native format, thus incurring as few conversions as possible.
66 
67  - The nrt::ImageSink accepts a GenericImage in its out() method. This achieves the same effect as above, and also
68  makes up for C++'s lack of virtual template functions. */
70  {
71  public:
73 
74  //! Construct an empty generic image
75  explicit GenericImage();
76 
77  //! Construct a generic image from an nrt::Image
78  template <class PixType>
79  explicit GenericImage(Image<PixType> const & img);
80 
81  //! Construct from another GenericImage
82  GenericImage(GenericImage const & gimg);
83 
84  //! Assign from an nrt::Image
85  template <class PixType>
86  GenericImage & operator=(Image<PixType> const & img);
87 
88  //! Assign from another GenericImage
89  GenericImage & operator=(GenericImage const & gimg);
90 
91  //! Get the dimensions of the underlying Image
92  Dims<int32> const & dims() const;
93 
94  //! Get the dimensions of the underlying Image
95  Rectangle<int32> bounds() const;
96 
97  //! Get the width of the underlying Image
98  int32 width() const;
99 
100  //! Get the height of the underlying Image
101  int32 height() const;
102 
103  //! Is there any Image data stored in this GenericImage? If this is zero the image is empty / no image
104  int32 size() const;
105 
106  //! Is our underlying Image of type Ima?
107  /*! Ima should be an nrt::Image<sometype> */
108  template <class Ima>
109  bool isa() const;
110 
111  //! Has our underlying Image pixels of type PixType?
112  template <class PixType>
113  bool hasPixels() const;
114 
115  //! Get the underlying Image type as a string, mostly for debugging messages and testing
116  std::string typeStr() const;
117 
118  //! Get the underlying nrt::Image, non-const version
119  /*! @throws boost::bad_get exception if PixType is not our underlying type; use isa<Image<sometype>>() or
120  hasPixels<sometype> to find out the pixel type.
121  Note that get() is not the preferred way of using GenericImage for processing, see apply_visitor() or
122  convertTo() instead. */
123  template <class PixType>
124  Image<PixType> & get();
125 
126  //! Get the underlying nrt::Image, const version
127  /*! @throws boost::bad_get exception if PixType is not our underlying type; use isa<Image<sometype>>() or
128  hasPixels<sometype> to find out the pixel type.
129  Note that get() is not the preferred way of using GenericImage for processing, see apply_visitor() or
130  convertTo() instead. */
131  template <class PixType>
132  Image<PixType> const & get() const;
133 
134  //! Reset to zero the contents of the GenericImage without changing the size
135  void clear();
136 
137  //! Convert to a specified nrt::Image<PixType>
138  /*! If our underlying Image's pixel type is not the same as the desired one, an expensive pixel-by-pixel
139  conversion will occur, otherwise this operation is very fast due to the copy-on-write mechanism of Image. */
140  template <class PixType>
141  Image<PixType> convertTo() const;
142 
143  //! Apply a unary visitor to GenericImage
144  /*! Use this to apply some Image processing function to a GenericImage */
145  template <class Visitor>
146  typename Visitor::result_type apply_visitor(Visitor & v) const;
147 
148  //! Apply a unary visitor to GenericImage, const visitor version
149  /*! Use this to apply some Image processing function to a GenericImage */
150  template <class Visitor>
151  typename Visitor::result_type apply_visitor(Visitor const & v) const;
152 
153  //! Apply a unary visitor in-place, i.e., the visitor may change our GenericImage content
154  /*! Use this to apply some in-place Image processing function to a GenericImage */
155  template <class Visitor>
156  void apply_inplace_visitor(Visitor & v);
157 
158  //! Apply a unary visitor in-place, i.e., the visitor may change our GenericImage content, const visitor version
159  /*! Use this to apply some in-place Image processing function to a GenericImage */
160  template <class Visitor>
161  void apply_inplace_visitor(Visitor const & v);
162 
163  //! Apply a binary visitor to two GenericImage objects (this and gimg2)
164  /*! Use this to apply some Image processing function that combines the present GenericImage with another */
165  template <class BinaryVisitor>
166  typename BinaryVisitor::result_type apply_visitor(BinaryVisitor & v, GenericImage const & gim2) const;
167 
168  //! Apply a binary visitor to two GenericImage objects (this and gimg2), const visitor version
169  /*! Use this to apply some Image processing function that combines the present GenericImage with another */
170  template <class BinaryVisitor>
171  typename BinaryVisitor::result_type apply_visitor(BinaryVisitor const & v, GenericImage const & gim2) const;
172 
173  private:
174  // Programmer note: there is a limit of 20 types here by default in boost variant
175  // Programmer note: keep this list in sync with the explicit instantiations in GenerimImageInst.H / GenericImage.C
176  boost::variant< Image< PixGray<byte> >,
177  Image< PixGray<uint16_t> >, // ok since uint16_t + uint16_t is int, which we handle
180 
184 
188 
192 
193  > itsImage;
194  protected:
195  friend class cereal::access;
196 
197  //! Serialize the GenericImage into/out-of an archive
198  template <class Archive> void serialize(Archive & ar)
199  {
200  ar( itsImage );
201  }
202  };
203 
204  /*! @} */ // **********************************************************************
205 
206 
207 } // nrt
208 
211 
212 #endif // INCLUDE_NRT_CORE_IMAGE_GENERICIMAGE_H
213