JeVois  1.8
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 
24 namespace jevois
25 {
26  /*! \defgroup utils Misc utilities
27 
28  Miscellaneous utility and helper functions. */
29 
30  /*! @{ */ // **********************************************************************
31 
32  //! Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string
33  std::string fccstr(unsigned int fcc);
34 
35  //! Convert cv::Mat::type() code to to a string (e.g., CV_8UC1, CV_32SC3, etc)
36  std::string cvtypestr(unsigned int cvtype);
37 
38  //! Convert a JeVois video format string to V4L2 four-cc code (V4L2_PIX_FMT_...)
39  /*! Throws a runtime_error if str is not one of: BAYER, YUYV, GREY, GRAY, MJPG, RGB565, BGR24 or NONE. */
40  unsigned int strfcc(std::string const & str);
41 
42  //! Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
43  unsigned int v4l2BytesPerPix(unsigned int fcc);
44 
45  //! Return the image size in bytes for a given V4L2_PIX_FMT_..., width, height
46  unsigned int v4l2ImageSize(unsigned int fcc, unsigned int width, unsigned int height);
47 
48  //! Return a value that corresponds to black for the given video format
49  /*! The returned value is appropriate to use as the color value for the image drawing functions in \ref image and may
50  not always be zero. */
51  unsigned int blackColor(unsigned int fcc);
52 
53  //! Return a value that corresponds to white for the given video format
54  /*! The returned value is appropriate to use as the color value for the image drawing functions in \ref image. */
55  unsigned int whiteColor(unsigned int fcc);
56 
57  //! Split string into vector of tokens using a regex to specify what to split on; default regex splits by whitespace
58  std::vector<std::string> split(std::string const & input, std::string const & regex = "\\s+");
59 
60  //! Concatenate a vector of tokens into a string
61  std::string join(std::vector<std::string> const & strings, std::string const & delimiter);
62 
63  //! Return true if str starts with prefix (including if both strings are equal)
64  /*! Note that if str is shorter than prefix, return is false (like in strncmp()). */
65  bool stringStartsWith(std::string const & str, std::string const & prefix);
66 
67  //! Replace white space characters in a string with underscore (default) or another characters
68  std::string replaceWhitespace(std::string const & str, char rep = '_');
69 
70  //! Strip white space (including CR, LF, tabs, etc) from the end of a string
71  std::string strip(std::string const & str);
72 
73  //! Create a string using printf style arguments
74  /*! Example:
75  @code
76  std::string s = nrt::sformat("MyString_%f_%d", 1.0, 2);
77  @endcode
78 
79  One should normally refrain from using sformat(), and instead use streaming operators of C++, one exception is
80  when issuing serial messages that have float numbers in them, the printf-like sytnax of sformat is useful to
81  quickly and easily specify a numerical precision. */
82  std::string sformat(char const * fmt, ...)
83  // NOTE: this __attribute__ tells gcc that it should issue printf-style warnings when compiling calls to sformat(),
84  // treating the 1st argument (fmt) as the format string, and the 2nd and subsequent arguments as the printf-style
85  // parameters
86  __attribute__((format(__printf__, 1, 2)));
87 
88  // Doxygen is not too good with enable_if, it only documents one version of the function. Here is a workaround:
89 #ifdef JEVOIS_DOXYGEN
90  //! Convert from string to a type
91  /*! For integral types, internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x
92  (hex). Beware of that octal convention and do not pass leading zeros unless you mean it. For non-integral types,
93  internally uses operator>> for that type, so it works with any type that supports it. */
94  template <typename T> T from_string(std::string const & str);
95 #else
96  //! Convert from string to a type, version for non-integral types
97  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
98  template <typename T>
99  typename std::enable_if< ! std::is_integral<T>::value, T>::type from_string(std::string const & str);
100 
101  //! Convert from string to a type, version for integral types
102  /*! This internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x (hex). */
103  template <typename T>
104  typename std::enable_if<std::is_integral<T>::value, T>::type from_string(std::string const & str);
105 #endif
106 
107  //! Convert from type to string
108  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
109  template <typename T>
110  std::string to_string(T const & val);
111 
112  //! Clamped numerical conversion
113  template <typename dest_type, typename source_type>
114  dest_type clamped_convert(source_type source);
115 
116  //! Flush the caches, may sometimes be useful when running the camera in turbo mode
117  void flushcache();
118 
119  //! Execute a command and grab stdout output to a string
120  /*! If errtoo is true, we also grab errors by appending a 2>&1 to the command. */
121  std::string system(std::string const & cmd, bool errtoo = true);
122 
123  /*! @} */ // **********************************************************************
124 
125 } // namespace jevois
126 
127 
128 // ####################################################################################################
129 //! Helper macro to execute an ioctl, ignore interruptions, and, if error, issue a fatal message and throw
130 /*! \def XIOCTL(dev, req, mem)
131  \hideinitializer
132 
133  This macro assumes that req is an identifier (\#define) for the corresponding ioctl number.
134  \ingroup utils */
135 
136 // ####################################################################################################
137 //! Helper macro to execute an ioctl, ignore interruptions, and, if error throw quietly
138 /*! \def XIOCTL_QUIET(dev, req, mem)
139  \hideinitializer
140 
141  This is useful, e.g., for V4L2 camera enumeration of formats, where one is supposed to call an ioctl
142  with increasing format number until it fails. When that happens we don't want to display any fatal error
143  message as XIOCTL() does. This macro assumes that req is an identifier for the corresponding ioctl number.
144  \ingroup utils */
145 
146 // Include implementation details
std::string strip(std::string const &str)
Strip white space (including CR, LF, tabs, etc) from the end of a string.
Definition: Utils.C:179
unsigned int whiteColor(unsigned int fcc)
Return a value that corresponds to white for the given video format.
Definition: Utils.C:126
dest_type clamped_convert(source_type source)
Clamped numerical conversion.
Definition: UtilsImpl.H:65
void flushcache()
Flush the caches, may sometimes be useful when running the camera in turbo mode.
Definition: Utils.C:235
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:52
unsigned int blackColor(unsigned int fcc)
Return a value that corresponds to black for the given video format.
Definition: Utils.C:111
std::string sformat(char const *fmt,...) __attribute__((format(__printf__
Create a string using printf style arguments.
Definition: Utils.C:225
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:171
unsigned int v4l2BytesPerPix(unsigned int fcc)
Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
Definition: Utils.C:91
std::string join(std::vector< std::string > const &strings, std::string const &delimiter)
Concatenate a vector of tokens into a string.
Definition: Utils.C:151
std::string system(std::string const &cmd, bool errtoo=true)
Execute a command and grab stdout output to a string.
Definition: Utils.C:247
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:165
std::string fccstr(unsigned int fcc)
Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string.
Definition: Utils.C:39
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:107
std::string to_string(T const &val)
Convert from type to string.
Definition: UtilsImpl.H:58
unsigned int strfcc(std::string const &str)
Convert a JeVois video format string to V4L2 four-cc code (V4L2_PIX_FMT_...)
Definition: Utils.C:78
std::string T from_string(std::string const &str)
Convert from string to a type.
std::vector< std::string > split(std::string const &input, std::string const &regex="\+")
Split string into vector of tokens using a regex to specify what to split on; default regex splits by...
Definition: Utils.C:141