JeVois  1.17
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Utils.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 <string>
21 #include <vector>
22 #include <type_traits> // for std::is_integral
23 #include <sstream>
24 
25 //! Metadata V4L2 format used by Amlogic A311D camera ISP
26 #define ISP_V4L2_PIX_FMT_META v4l2_fourcc( 'M', 'E', 'T', 'A' )
27 
28 //! JeVois-Pro zero-copy display of camera input frame (to be used as output mode in VideoMapping)
29 /*! Note that the underlying mode is RGBA as used by MALI OpenGL */
30 #define JEVOISPRO_FMT_GUI v4l2_fourcc( 'J', 'V', 'U', 'I' )
31 
32 namespace jevois
33 {
34  /*! \defgroup utils Misc utilities
35 
36  Miscellaneous utility and helper functions. */
37 
38  /*! @{ */ // **********************************************************************
39 
40  //! Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string
41  std::string fccstr(unsigned int fcc);
42 
43  //! Convert cv::Mat::type() code to to a string (e.g., CV_8UC1, CV_32SC3, etc)
44  std::string cvtypestr(unsigned int cvtype);
45 
46  //! Return the number of bytes per pixel for a given OpenCV pixel type
47  unsigned int cvBytesPerPix(unsigned int cvtype);
48 
49  //! Convert a JeVois video format string to V4L2 four-cc code (V4L2_PIX_FMT_...)
50  /*! Throws a runtime_error if str is not one of: BAYER, YUYV, GREY, GRAY, MJPG, RGB565, BGR24 or NONE. */
51  unsigned int strfcc(std::string const & str);
52 
53  //! Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
54  unsigned int v4l2BytesPerPix(unsigned int fcc);
55 
56  //! Return the image size in bytes for a given V4L2_PIX_FMT_..., width, height
57  unsigned int v4l2ImageSize(unsigned int fcc, unsigned int width, unsigned int height);
58 
59  //! Return a value that corresponds to black for the given video format
60  /*! The returned value is appropriate to use as the color value for the image drawing functions in \ref image and may
61  not always be zero. */
62  unsigned int blackColor(unsigned int fcc);
63 
64  //! Return a value that corresponds to white for the given video format
65  /*! The returned value is appropriate to use as the color value for the image drawing functions in \ref image. */
66  unsigned int whiteColor(unsigned int fcc);
67 
68  //! Apply a letterbox resizing to fit an image into a window
69  /*! Modify given image dims (imw,imh) so that the image fits inside window dims (winw,winh) while being as large as
70  possible but without modifying the image's aspect ratio. If noalias is specified, the scaling factor will be
71  rounded down to the nearest integer to prevent aliasing in the display. This may reduce the displayed image
72  size. For example, with a 1920x1080 window, a 640x480 image would be letterboxed to 1440x1080 when noalias is
73  false. But that is a scaling factor of 2.25 which may create rendering aliasing. When noalias is true, the
74  letterboxed image size will be 1280x960 (scale factor of 2.0). */
75  void applyLetterBox(unsigned int & imw, unsigned int & imh, unsigned int const winw, unsigned int const winh,
76  bool noalias);
77 
78  //! Split string into vector of tokens using a regex to specify what to split on; default regex splits by whitespace
79  std::vector<std::string> split(std::string const & input, std::string const & regex = "\\s+");
80 
81  //! Concatenate a vector of tokens into a string
82  std::string join(std::vector<std::string> const & strings, std::string const & delimiter);
83 
84  //! Return true if str starts with prefix (including if both strings are equal)
85  /*! Note that if str is shorter than prefix, return is false (like in strncmp()). */
86  bool stringStartsWith(std::string const & str, std::string const & prefix);
87 
88  //! Replace white space characters in a string with underscore (default) or another characters
89  std::string replaceWhitespace(std::string const & str, char rep = '_');
90 
91  //! Strip white space (including CR, LF, tabs, etc) from the end of a string
92  std::string strip(std::string const & str);
93 
94  //! Extract a portion of a string between two delimiters
95  /*! Returns an empty string if the delimiters were not found. */
96  std::string extractString(std::string const & str, std::string const & startsep, std::string const & endsep);
97 
98  //! Replace first instance of 'from' with 'to'
99  /*! Returns the number of replacements made (0 or 1). */
100  size_t replaceStringFirst(std::string & str, std::string const & from, std::string const & to);
101 
102  //! Replace all instances of 'from' with 'to'
103  /*! Returns the number of replacements made. */
104  size_t replaceStringAll(std::string & str, std::string const & from, std::string const & to);
105 
106  //! Compute an absolute path from two paths
107  /*! Parameter \p path contains a path that could be either absolute or relative; parameter \p root should contain a
108  root path. If path is absolute, it is returned; otherwise, root is prepended to it and the result is returned. */
109  std::string absolutePath(std::string const & root, std::string const & path);
110 
111  //! Create a string using printf style arguments
112  /*! Example:
113  @code
114  std::string s = jevois::sformat("MyString_%f_%d", 1.0, 2);
115  @endcode
116 
117  One should normally refrain from using sformat(), and instead use streaming operators of C++, one exception is
118  when issuing serial messages that have float numbers in them, the printf-like sytnax of sformat is useful to
119  quickly and easily specify a numerical precision. */
120  std::string sformat(char const * fmt, ...)
121  // NOTE: this __attribute__ tells gcc that it should issue printf-style warnings when compiling calls to sformat(),
122  // treating the 1st argument (fmt) as the format string, and the 2nd and subsequent arguments as the printf-style
123  // parameters
124  __attribute__((format(__printf__, 1, 2)));
125 
126  // Doxygen is not too good with enable_if, it only documents one version of the function. Here is a workaround:
127 #ifdef JEVOIS_DOXYGEN
128  //! Convert from string to a type
129  /*! For integral types, internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x
130  (hex). Beware of that octal convention and do not pass leading zeros unless you mean it. For non-integral types,
131  internally uses operator>> for that type, so it works with any type that supports it. */
132  template <typename T> T from_string(std::string const & str);
133 #else
134  //! Convert from string to a type, version for non-integral types
135  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
136  template <typename T>
137  typename std::enable_if< ! std::is_integral<T>::value, T>::type from_string(std::string const & str);
138 
139  //! Convert from string to a type, version for integral types
140  /*! This internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x (hex). */
141  template <typename T>
142  typename std::enable_if<std::is_integral<T>::value, T>::type from_string(std::string const & str);
143 #endif
144 
145  //! Convert from type to string
146  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
147  template <typename T>
148  std::string to_string(T const & val);
149 
150  //! Clamped numerical conversion
151  template <typename dest_type, typename source_type>
152  dest_type clamped_convert(source_type source);
153 
154  //! Flush the caches, may sometimes be useful when running the camera in turbo mode
155  void flushcache();
156 
157  //! Execute a command and grab stdout output to a string
158  /*! If errtoo is true, we also grab errors by appending a 2>&1 to the command. */
159  std::string system(std::string const & cmd, bool errtoo = true);
160 
161  //! Report a duration given in seconds with variable units (ns, us, ms, or s), with precision of 2 decimal points
162  std::string secs2str(double secs);
163 
164  //! Report a duration given in seconds with variable units (ns, us, ms, or s)
165  /*! You should decide on precision using std::setprecision(n) in your stream before calling this function. */
166  void secs2str(std::ostringstream & ss, double secs);
167 
168  //! Read one line from a file and return it as a string
169  /*! Useful to get info from virtual kernel filesystems, such as CPU temperature, etc. Parameter \p skip optionally
170  specifies a number of lines to skip before returning the one of interest. */
171  std::string getFileString(char const * fname, int skip = 0);
172 
173  /*! @} */ // **********************************************************************
174 
175 } // namespace jevois
176 
177 
178 // ####################################################################################################
179 //! Helper macro to execute an ioctl, ignore interruptions, and, if error, issue a fatal message and throw
180 /*! \def XIOCTL(dev, req, mem)
181  \hideinitializer
182 
183  This macro assumes that req is an identifier (\#define) for the corresponding ioctl number.
184  \ingroup utils */
185 
186 // ####################################################################################################
187 //! Helper macro to execute an ioctl, ignore interruptions, and, if error throw quietly
188 /*! \def XIOCTL_QUIET(dev, req, mem)
189  \hideinitializer
190 
191  This is useful, e.g., for V4L2 camera enumeration of formats, where one is supposed to call an ioctl
192  with increasing format number until it fails. When that happens we don't want to display any fatal error
193  message as XIOCTL() does. This macro assumes that req is an identifier for the corresponding ioctl number.
194  \ingroup utils */
195 
196 // ####################################################################################################
197 //! Helper macro to execute an ioctl, ignore interruptions, and, if error throw quietly
198 /*! \def XIOCTL_QUIET_ONCE(dev, req, mem)
199  \hideinitializer
200 
201  This is useful, e.g., for V4L2 camera enumeration of formats, where one is supposed to call an ioctl
202  with increasing format number until it fails. When that happens we don't want to display any fatal error
203  message as XIOCTL() does. This macro assumes that req is an identifier for the corresponding ioctl number.
204  Note that in this version we throw on any error.
205  \ingroup utils */
206 
207 // Include implementation details
208 #include <jevois/Util/details/UtilsImpl.H>
jevois::whiteColor
unsigned int whiteColor(unsigned int fcc)
Return a value that corresponds to white for the given video format.
Definition: Utils.C:187
jevois::sformat
std::string sformat(char const *fmt,...) __attribute__((format(__printf__
Create a string using printf style arguments.
Definition: Utils.C:401
jevois::split
std::vector< std::string > split(std::string const &input, std::string const &regex="\\s+")
Split string into vector of tokens using a regex to specify what to split on; default regex splits by...
Definition: Utils.C:257
jevois::cvBytesPerPix
unsigned int cvBytesPerPix(unsigned int cvtype)
Return the number of bytes per pixel for a given OpenCV pixel type.
Definition: Utils.C:88
jevois::flushcache
void flushcache()
Flush the caches, may sometimes be useful when running the camera in turbo mode.
Definition: Utils.C:411
jevois::cvtypestr
std::string cvtypestr(unsigned int cvtype)
Convert cv::Mat::type() code to to a string (e.g., CV_8UC1, CV_32SC3, etc)
Definition: Utils.C:57
jevois::clamped_convert
dest_type clamped_convert(source_type source)
Clamped numerical conversion.
jevois::replaceStringFirst
size_t replaceStringFirst(std::string &str, std::string const &from, std::string const &to)
Replace first instance of 'from' with 'to'.
Definition: Utils.C:318
jevois::blackColor
unsigned int blackColor(unsigned int fcc)
Return a value that corresponds to black for the given video format.
Definition: Utils.C:165
jevois::getFileString
std::string getFileString(char const *fname, int skip=0)
Read one line from a file and return it as a string.
Definition: Utils.C:453
jevois::dnn::postprocessor::format
Type of detection output format
Definition: PostProcessor.H:75
jevois::replaceWhitespace
std::string replaceWhitespace(std::string const &str, char rep='_')
Replace white space characters in a string with underscore (default) or another characters.
Definition: Utils.C:287
jevois
Definition: Concepts.dox:1
jevois::system
std::string system(std::string const &cmd, bool errtoo=true)
Execute a command and grab stdout output to a string.
Definition: Utils.C:423
jevois::v4l2BytesPerPix
unsigned int v4l2BytesPerPix(unsigned int fcc)
Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
Definition: Utils.C:137
jevois::replaceStringAll
size_t replaceStringAll(std::string &str, std::string const &from, std::string const &to)
Replace all instances of 'from' with 'to'.
Definition: Utils.C:331
jevois::join
std::string join(std::vector< std::string > const &strings, std::string const &delimiter)
Concatenate a vector of tokens into a string.
Definition: Utils.C:267
jevois::extractString
std::string extractString(std::string const &str, std::string const &startsep, std::string const &endsep)
Extract a portion of a string between two delimiters.
Definition: Utils.C:303
jevois::fccstr
std::string fccstr(unsigned int fcc)
Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string.
Definition: Utils.C:44
jevois::applyLetterBox
void applyLetterBox(unsigned int &imw, unsigned int &imh, unsigned int const winw, unsigned int const winh, bool noalias)
Apply a letterbox resizing to fit an image into a window.
Definition: Utils.C:209
jevois::absolutePath
std::string absolutePath(std::string const &root, std::string const &path)
Compute an absolute path from two paths.
Definition: Utils.C:347
jevois::stringStartsWith
bool stringStartsWith(std::string const &str, std::string const &prefix)
Return true if str starts with prefix (including if both strings are equal)
Definition: Utils.C:281
jevois::secs2str
std::string secs2str(double secs)
Report a duration given in seconds with variable units (ns, us, ms, or s), with precision of 2 decima...
Definition: Utils.C:435
jevois::to_string
std::string to_string(T const &val)
Convert from type to string.
jevois::v4l2ImageSize
unsigned int v4l2ImageSize(unsigned int fcc, unsigned int width, unsigned int height)
Return the image size in bytes for a given V4L2_PIX_FMT_..., width, height.
Definition: Utils.C:161
jevois::from_string
std::string T from_string(std::string const &str)
Convert from string to a type.
jevois::strfcc
unsigned int strfcc(std::string const &str)
Convert a JeVois video format string to V4L2 four-cc code (V4L2_PIX_FMT_...)
Definition: Utils.C:110
jevois::strip
std::string strip(std::string const &str)
Strip white space (including CR, LF, tabs, etc) from the end of a string.
Definition: Utils.C:295