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