JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
RawImage.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
20 #include <memory>
21 
22 // Although not strictly required here, we include videodev.h to bring in the V4L2_PIX_FMT_... definitions and make them
23 // available to all users of RawImage:
24 #include <linux/videodev2.h>
25 
26 namespace jevois
27 {
28  class Engine;
29  class VideoBuf;
30  /*! \defgroup image Minimalistic support for images in the core JeVois library
31 
32  The main purpose of the classes and functions that support images is to allow handling of image buffers whose
33  memory is mapped onto hardware (camera or USB drivers) without having to copy the data over. Many other libraries
34  and frameworks are available that define more complete image classes and associated image processing and machine
35  vision functions. Functions are here provided to allow you to reinterpret the raw image buffers as, e.g., OpenCV
36  cv::Mat images without copying the image pixel data. For the purposes of creating demo displays, simple image
37  copy, paste, drawing, text, etc into raw YUYV image buffers (which would typically be obtained from the USB driver
38  and need to be filled with some pixel data to send over the USB link) are also provided.
39 
40  The class that represents an image with a pixel buffer that the camera or USB hardware has direct memory access to
41  (see VideoBuf) is called RawImage. To avoid defining pixel types yet again, as most image-related libraries
42  already do, in RawImage we just use the definitions provided by Video4Linux2.
43 
44  The functions that operate on RawImage are thus mostly intented for two purposes: 1) get pixel data out of
45  RawImage and into another format like OpenCV, or from some other format into RawImage; 2) Allow simple drawings of
46  lines, circles, rectangles, etc to make simple demo displays directly in the RawImage buffer that will be sent
47  over the USB link. */
48 
49  //! Helper YUYV colors
50  /*! Here we assume little endian (so the chroma is the high byte, luminance is low byte) and we assume that we will
51  write the same value to the YU and the YV shorts. This means that all the colors are on the green to magenta
52  (purple) axis, with some limited opportunity for variations using the luminance value. \ingroup image */
53  namespace yuyv
54  {
55  static unsigned short const Black = 0x8000;
56  static unsigned short const DarkGrey = 0x8050;
57  static unsigned short const MedGrey = 0x8080;
58  static unsigned short const LightGrey = 0x80a0;
59  static unsigned short const White = 0x80ff;
60 
61  static unsigned short const DarkGreen = 0x0000;
62  static unsigned short const MedGreen = 0x0040;
63  static unsigned short const LightGreen = 0x00ff;
64 
65  static unsigned short const DarkTeal = 0x7070;
66  static unsigned short const MedTeal = 0x7090;
67  static unsigned short const LightTeal = 0x70b0;
68 
69  static unsigned short const DarkPurple = 0xa030;
70  static unsigned short const MedPurple = 0xa050;
71  static unsigned short const LightPurple = 0xa080;
72 
73  static unsigned short const DarkPink = 0xff00;
74  static unsigned short const MedPink = 0xff80;
75  static unsigned short const LightPink = 0xffff;
76  } // namespace yuyv
77 
78  //! Helper RGB565 colors
79  /*! We also assume little endian encoding here. These colors are from
80  http://stackoverflow.com/questions/13720937/c-defined-16bit-high-color \ingroup image */
81  namespace rgb565
82  {
83  static unsigned short const Black = 0x0000; // 0, 0, 0
84  static unsigned short const Navy = 0x000F; // 0, 0, 128
85  static unsigned short const DarkGreen = 0x03E0; // 0, 128, 0
86  static unsigned short const DarkCyan = 0x03EF; // 0, 128, 128
87  static unsigned short const Maroon = 0x7800; // 128, 0, 0
88  static unsigned short const Purple = 0x780F; // 128, 0, 128
89  static unsigned short const Olive = 0x7BE0; // 128, 128, 0
90  static unsigned short const LightGrey = 0xC618; // 192, 192, 192
91  static unsigned short const DarkGrey = 0x7BEF; // 128, 128, 128
92  static unsigned short const Blue = 0x001F; // 0, 0, 255
93  static unsigned short const Green = 0x07E0; // 0, 255, 0
94  static unsigned short const Cyan = 0x07FF; // 0, 255, 255
95  static unsigned short const Red = 0xF800; // 255, 0, 0
96  static unsigned short const Magenta = 0xF81F; // 255, 0, 255
97  static unsigned short const Yellow = 0xFFE0; // 255, 255, 0
98  static unsigned short const White = 0xFFFF; // 255, 255, 255
99  static unsigned short const Orange = 0xFD20; // 255, 165, 0
100  static unsigned short const GreenYellow = 0xAFE5; // 173, 255, 47
101  static unsigned short const Pink = 0xF81F;
102  } // namespace rgb565
103 
104  //! A raw image as coming from a V4L2 Camera and/or being sent out to a USB Gadget
105  /*! The pixel data is allocated and memory mapped by the respective camera or gadget drivers. Because the pixel buffer
106  is allocated and managed by the hardware driver, we cannot make deep copies of RawImage, and thus the copy
107  constructor and assignment operators will yield images that share the same pixel data. To copy pixels from one
108  RawImage to another (e.g., from camera image to USB image), see jevois::rawimage::paste() and other RawImage
109  functions. \ingroup image */
110  class RawImage
111  {
112  public:
113  //! Default constructor, uninitialized
114  RawImage();
115 
116  //! Default move constructor
117  RawImage(RawImage && other) = default;
118 
119  //! Default copy constructor
120  RawImage(RawImage const & other) = default;
121 
122  //! Default assignment
123  RawImage & operator=(RawImage const & other) = default;
124 
125  //! Construct from an existing VideoBuf and associated params
126  RawImage(unsigned int w, unsigned int h, unsigned int f, float fs, std::shared_ptr<VideoBuf> b, size_t bindex);
127 
128  //! Invalidate the image by zero'ing out the pointer to pixel buffer and the dims and format
129  void invalidate();
130 
131  //! Check whether the image has a valid pixel buffer
132  bool valid() const;
133 
134  //! Clear the pixels to all black
135  /*! Black value depends on format. Does not work with MJPEG. Throws if the raw image is not valid() and silently
136  does nothing if the raw image has MJPEG pixels (since the raw image buffer will be overwritten by the MJPEG
137  compressor anyway). */
138  void clear();
139 
140  //! Require a particular image size and format, issue a fatal error message and throw if no match
141  /*! The info string is included in the fatal error message to help identifying which image failed the
142  requirement. Typically, you would pass "input" or "output" as info. */
143  void require(char const * info, unsigned int w, unsigned int h, unsigned int f) const;
144 
145  unsigned int width; //!< Image width in pixels
146  unsigned int height; //!< Image height in pixels
147  unsigned int fmt; //!< Pixel format as a V4L2_PIX_FMT_XXX
148  float fps; //!< Programmed frames/s as given by current video mapping, may not be actual
149  std::shared_ptr<VideoBuf> buf; //!< The pixel data buffer
150  size_t bufindex; //!< The index of the data buffer in the kernel driver
151 
152  //! Helper function to get the number of bytes/pixel given the RawImage pixel format
153  unsigned int bytesperpix() const;
154 
155  //! Helper function to get the total number of bytes in the RawImage, i.e., width * height * bytesperpix()
156  unsigned int bytesize() const;
157 
158  //! Helper function to check that coords are within image bounds
159  bool coordsOk(int x, int y) const;
160 
161  //! Shortcut access to pixels, read-write
162  template <typename T>
163  T * pixelsw();
164 
165  //! Shortcut access to pixels, read-only
166  template <typename T>
167  T const * pixels() const;
168  };
169 } // namespace jevois
170 
171 // Include implementation details
unsigned int height
Image height in pixels.
Definition: RawImage.H:146
unsigned int fmt
Pixel format as a V4L2_PIX_FMT_XXX.
Definition: RawImage.H:147
std::shared_ptr< VideoBuf > buf
The pixel data buffer.
Definition: RawImage.H:149
A raw image as coming from a V4L2 Camera and/or being sent out to a USB Gadget.
Definition: RawImage.H:110
float fps
Programmed frames/s as given by current video mapping, may not be actual.
Definition: RawImage.H:148
size_t bufindex
The index of the data buffer in the kernel driver.
Definition: RawImage.H:150
unsigned int width
Image width in pixels.
Definition: RawImage.H:145