JeVois  1.3
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
VideoMapping.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 <iosfwd>
21 #include <vector>
22 #include <string>
23 #include <linux/videodev2.h> // for v4l2_fract
24 
25 namespace jevois
26 {
27  //! Simple struct to hold video mapping definitions for the processing Engine
28  /*! This struct specifies an output video format, resolution, and frame rate (to be send to the end user over USB),
29  the corresponding camera capture video format, resolution and frame rate, and the Module to use to process the
30  camera frames and generate the corresponding output frames. This class also provides conversion functions between
31  frame rate and frame interval periods for both USB and V4L2, which use different units.
32 
33  Operation of JeVois is based on a list of available VideoMapping definitions, which is configured in a file called
34  JEVOIS:config/videomappings.cfg on the microSD card. The video mappings indicate which output formats are exposed
35  to the host computer connected over USB, and which corresponding camera format and vision processing module should
36  be used when a given output format is selected by video capture software running on the host computer.
37 
38  See \ref UserModes for explanations about how to organize videomappings.cfg
39 
40  \ingroup core */
41  struct VideoMapping
42  {
43  unsigned int ofmt; //!< output pixel format, or 0 for no output over USB
44  unsigned int ow; //!< output width
45  unsigned int oh; //!< output height
46  float ofps; //!< output frame rate in frames/sec
47 
48  unsigned int cfmt; //!< camera pixel format
49  unsigned int cw; //!< camera width
50  unsigned int ch; //!< camera height
51  float cfps; //!< camera frame rate in frames/sec
52 
53  unsigned int uvcformat; //!< USB-UVC format number (1-based)
54  unsigned int uvcframe; //!< USB UVC frame number (1-based)
55 
56  std::string vendor; //!< Module creator name, used as a directory to organize the modules
57 
58  std::string modulename; //!< Name of the Module that will process this mapping
59 
60  bool ispython; //!< True if the module is written in Python; affects behavior of sopath() only
61 
62  //! Return the full absolute path and file name of the module's .so or .py file
63  std::string sopath() const;
64 
65  //! Return the size in bytes of an output image
66  unsigned int osize() const;
67 
68  //! Return the size in bytes of a camera image
69  unsigned int csize() const;
70 
71  //! Convert from USB/UVC interval to fps
72  /*! This function rounds to the nearest 1/100 fps. */
73  static float uvcToFps(unsigned int interval);
74 
75  //! Convert from fps to USB/UVC interval
76  static unsigned int fpsToUvc(float fps);
77 
78  //! Convert from V4L2 interval to fps
79  /*! This function rounds to the nearest 1/100 fps. */
80  static float v4l2ToFps(struct v4l2_fract const & interval);
81 
82  //! Convert from fps to V4L2 interval
83  static struct v4l2_fract fpsToV4l2(float fps);
84 
85  //! Return true if this VideoMapping's output format is a match to the given output parameters
86  bool match(unsigned int oformat, unsigned int owidth, unsigned int oheight, float oframespersec) const;
87 
88  //! Convenience function to print out FCC WxH @ fps, for the output (UVC) format
89  std::string ostr() const;
90 
91  //! Convenience function to print out FCC WxH @ fps, for the input (camera) format
92  std::string cstr() const;
93 
94  //! Convenience function to print out the whole mapping in a human-friendly way
95  std::string str() const;
96 
97  //! Equality operator for specs but not vendor or module name
98  /*! Note that two mappings will be declared to match if their fps values are within 0.01fps, to avoid mismatches
99  due to floating point representation and rounding. */
100  bool hasSameSpecsAs(VideoMapping const & other) const;
101 
102  //! Equality operator for specs and also vendor or module name
103  /*! Note that two mappings will be declared to match if their fps values are within 0.01fps, to avoid mismatches
104  due to floating point representation and rounding. */
105  bool isSameAs(VideoMapping const & other) const;
106  };
107 
108  //! Stream a VideoMapping out, intended for machines
109  /*! Note that no std::endl is issued at the end.
110  \relates jevois::VideoMapping */
111  std::ostream & operator<<(std::ostream & out, VideoMapping const & m);
112 
113  //! Stream a VideoMapping in, intended for machines
114  /*! Note that the assumption is that the mapping is clean (no extra garbage).
115  \relates jevois::VideoMapping */
116  std::istream & operator>>(std::istream & in, VideoMapping & m);
117 
118  //! Load all the video mappings from the default config file
119  /*! \relates VideoMapping */
120  std::vector<VideoMapping> loadVideoMappings(size_t & defidx, bool checkso = true);
121 
122  //! Parse all the mappings in a config file and also indicate which one is the default
123  /*! The contents of the file are sorted so that the resulting vector is ordered by increasing 1) format fcc, then 2)
124  resolution (from large to small, looking at x first), and 3) framerate (from high to low).
125 
126  In case of duplicate output formats, frame rates will be decreased by 1fps for each additional duplicate. This is
127  because we need to present the host computer with distinct video formats so that users can select the one they
128  want. For example:
129  \verbatim
130  YUYV 320 240 60.0 YUYV 320 240 60.0 JeVois SaveVideo
131  YUYV 320 240 60.0 YUYV 320 240 60.0 VendorX MyModule
132  YUYV 320 240 60.0 YUYV 320 240 60.0 VendorY MyModule
133  YUYV 320 240 60.0 YUYV 320 240 60.0 VendorZ MyModule
134  \endverbatim
135 
136  will be disambiguated into:
137 
138  \verbatim
139  YUYV 320 240 60.0 YUYV 320 240 60.0 JeVois SaveVideo
140  YUYV 320 240 59.0 YUYV 320 240 60.0 VendorX MyModule
141  YUYV 320 240 58.0 YUYV 320 240 60.0 VendorY MyModule
142  YUYV 320 240 57.0 YUYV 320 240 60.0 VendorZ MyModule
143  \endverbatim
144 
145  and in \b guvcview or similar program running on a host computer, these 4 mappings will be available since they
146  correspond to 4 different framerates. It is recommended that you issue a \b listmapping command in the JeVois
147  command-line interface to confirm the final mappings that are used at runtime after any adjustments; see \ref
148  UserCli for details.
149 
150  defidx is the index of the default format in the resulting vector of mappings. If several default formats are
151  specified, the first one prevails.
152 
153  See \ref UserModes for explanations about how to organize \b videomappings.cfg
154  \relates VideoMapping */
155  std::vector<VideoMapping> videoMappingsFromStream(std::istream & is, size_t & defidx, bool checkso = true);
156 }
157 
float ofps
output frame rate in frames/sec
Definition: VideoMapping.H:46
unsigned int uvcformat
USB-UVC format number (1-based)
Definition: VideoMapping.H:53
unsigned int osize() const
Return the size in bytes of an output image.
Definition: VideoMapping.C:37
static struct v4l2_fract fpsToV4l2(float fps)
Convert from fps to V4L2 interval.
Definition: VideoMapping.C:65
unsigned int ofmt
output pixel format, or 0 for no output over USB
Definition: VideoMapping.H:43
std::string cstr() const
Convenience function to print out FCC WxH @ fps, for the input (camera) format.
Definition: VideoMapping.C:79
std::string modulename
Name of the Module that will process this mapping.
Definition: VideoMapping.H:58
unsigned int ch
camera height
Definition: VideoMapping.H:50
static float uvcToFps(unsigned int interval)
Convert from USB/UVC interval to fps.
Definition: VideoMapping.C:45
std::string ostr() const
Convenience function to print out FCC WxH @ fps, for the output (UVC) format.
Definition: VideoMapping.C:71
Simple struct to hold video mapping definitions for the processing Engine.
Definition: VideoMapping.H:41
std::string sopath() const
Return the full absolute path and file name of the module's .so or .py file.
Definition: VideoMapping.C:30
unsigned int uvcframe
USB UVC frame number (1-based)
Definition: VideoMapping.H:54
unsigned int oh
output height
Definition: VideoMapping.H:45
static float v4l2ToFps(struct v4l2_fract const &interval)
Convert from V4L2 interval to fps.
Definition: VideoMapping.C:58
bool isSameAs(VideoMapping const &other) const
Equality operator for specs and also vendor or module name.
Definition: VideoMapping.C:106
std::string str() const
Convenience function to print out the whole mapping in a human-friendly way.
Definition: VideoMapping.C:87
unsigned int cfmt
camera pixel format
Definition: VideoMapping.H:48
unsigned int cw
camera width
Definition: VideoMapping.H:49
bool hasSameSpecsAs(VideoMapping const &other) const
Equality operator for specs but not vendor or module name.
Definition: VideoMapping.C:99
bool ispython
True if the module is written in Python; affects behavior of sopath() only.
Definition: VideoMapping.H:60
bool match(unsigned int oformat, unsigned int owidth, unsigned int oheight, float oframespersec) const
Return true if this VideoMapping's output format is a match to the given output parameters.
Definition: VideoMapping.C:311
static unsigned int fpsToUvc(float fps)
Convert from fps to USB/UVC interval.
Definition: VideoMapping.C:52
unsigned int ow
output width
Definition: VideoMapping.H:44
std::string vendor
Module creator name, used as a directory to organize the modules.
Definition: VideoMapping.H:56
unsigned int csize() const
Return the size in bytes of a camera image.
Definition: VideoMapping.C:41
float cfps
camera frame rate in frames/sec
Definition: VideoMapping.H:51