JeVois  1.0
JeVois Smart Embedded Machine Vision Toolkit
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, 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  //! Require a particular image size and format, issue a fatal error message and throw if no match
135  /*! The info string is included in the fatal error message to help identifying which image failed the
136  requirement. Typically, you would pass "input" or "output" as info. */
137  void require(char const * info, unsigned int w, unsigned int h, unsigned int f) const;
138 
139  unsigned int width; //!< Image width in pixels
140  unsigned int height; //!< Image height in pixels
141  unsigned int fmt; //!< Pixel format as a V4L2_PIX_FMT_XXX
142  std::shared_ptr<VideoBuf> buf; //!< The pixel data buffer
143  size_t bufindex; //!< The index of the data buffer in the kernel driver
144 
145  //! Helper function to get the number of bytes/pixel given the RawImage pixel format
146  unsigned int bytesperpix() const;
147 
148  //! Helper function to get the total number of bytes in the RawImage, i.e., width * height * bytesperpix()
149  unsigned int bytesize() const;
150 
151  //! Helper function to check that coords are within image bounds
152  bool coordsOk(int x, int y) const;
153 
154  //! Shortcut access to pixels, read-write
155  template <typename T>
156  T * pixelsw();
157 
158  //! Shortcut access to pixels, read-only
159  template <typename T>
160  T const * pixels() const;
161  };
162 } // namespace jevois
163 
164 // Include implementation details
void require(char const *info, unsigned int w, unsigned int h, unsigned int f) const
Require a particular image size and format, issue a fatal error message and throw if no match...
Definition: RawImage.C:47
unsigned int height
Image height in pixels.
Definition: RawImage.H:140
T * pixelsw()
Shortcut access to pixels, read-write.
Definition: RawImageImpl.H:24
unsigned int fmt
Pixel format as a V4L2_PIX_FMT_XXX.
Definition: RawImage.H:141
std::shared_ptr< VideoBuf > buf
The pixel data buffer.
Definition: RawImage.H:142
void invalidate()
Invalidate the image by zero'ing out the pointer to pixel buffer and the dims and format...
Definition: RawImage.C:39
RawImage & operator=(RawImage const &other)=default
Default assignment.
A raw image as coming from a V4L2 Camera and/or being sent out to a USB Gadget.
Definition: RawImage.H:110
bool valid() const
Check whether the image has a valid pixel buffer.
Definition: RawImage.C:43
unsigned int bytesize() const
Helper function to get the total number of bytes in the RawImage, i.e., width * height * bytesperpix(...
Definition: RawImage.C:35
T const * pixels() const
Shortcut access to pixels, read-only.
Definition: RawImageImpl.H:29
unsigned int bytesperpix() const
Helper function to get the number of bytes/pixel given the RawImage pixel format. ...
Definition: RawImage.C:31
size_t bufindex
The index of the data buffer in the kernel driver.
Definition: RawImage.H:143
bool coordsOk(int x, int y) const
Helper function to check that coords are within image bounds.
Definition: RawImage.C:55
unsigned int width
Image width in pixels.
Definition: RawImage.H:139
RawImage()
Default constructor, uninitialized.
Definition: RawImage.C:22