JeVois  1.21
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Loading...
Searching...
No Matches
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
21#include <jevois/Types/Enum.H>
22
23#include <iosfwd>
24#include <vector>
25#include <string>
26#include <linux/videodev2.h> // for v4l2_fract
27
28namespace jevois
29{
30 struct VideoMapping; // defined below; declared here to help doxygen
31
32 //! Enum for VideoMapping wide-dynamic-range (WDR) type
33 /*! If nothing is specified in a VideoMapping, use Linear by default. \relates VideoMapping */
34 JEVOIS_DEFINE_ENUM_CLASS(WDRtype, (Linear) (DOL) );
35
36 //! Enum for VideoMapping crop or rescale
37 /*! On JeVois-Pro Platform (only), the camera ISP can stream up to two images: 1) the raw frame from the sensor
38 (possibly cropped), 2) a scaled frame generated by the ISP (scaling is always applied to the native sensor
39 resolution, irrespective of crop settings), or both. The images can have different pixel types but same
40 frames/s. Getting both cropped and scaled images is useful to use a full-frame raw YUYV capture for GUI display,
41 plus a scaled down RGB24 capture as input to a neural network. When a camera frame size is specified which does
42 not match the sensor's size, either do a centered crop, or a uniform rescaling. Note that rescaling can affect the
43 image aspect ratio, and thus it is recommended that camera frame sizes with same aspect ratio at the native sensor
44 size be used. If nothing is specified in a VideoMapping, use Scale as default. \relates VideoMapping */
45 JEVOIS_DEFINE_ENUM_CLASS(CropType, (Scale) (Crop) (CropScale) );
46
47 //! Simple struct to hold video mapping definitions for the processing Engine
48 /*! This struct specifies an output video format, resolution, and frame rate (to be send to the end user over USB),
49 the corresponding camera capture video format, resolution and frame rate, and the Module to use to process the
50 camera frames and generate the corresponding output frames. This class also provides conversion functions between
51 frame rate and frame interval periods for both USB and V4L2, which use different units.
52
53 Operation of JeVois is based on a list of available VideoMapping definitions, which is configured in a file called
54 JEVOIS:config/videomappings.cfg on the microSD card. The video mappings indicate which output formats are exposed
55 to the host computer connected over USB, and which corresponding camera format and vision processing module should
56 be used when a given output format is selected by video capture software running on the host computer.
57
58 See \ref UserModes for explanations about how to organize videomappings.cfg
59
60 \ingroup core */
62 {
63 unsigned int ofmt = 0; //!< output pixel format, or 0 for no output over USB
64 unsigned int ow = 0; //!< output width
65 unsigned int oh = 0; //!< output height
66 float ofps = 0.0F; //!< output frame rate in frames/sec
67
68 unsigned int cfmt = 0; //!< camera pixel format
69 unsigned int cw = 0; //!< camera width
70 unsigned int ch = 0; //!< camera height
71 float cfps = 0.0F; //!< camera frame rate in frames/sec
72
73 unsigned int uvcformat; //!< USB-UVC format number (1-based)
74 unsigned int uvcframe; //!< USB UVC frame number (1-based)
75
76 std::string vendor; //!< Module creator name, used as a directory to organize the modules
77
78 std::string modulename; //!< Name of the Module that will process this mapping
79
80 WDRtype wdr = WDRtype::Linear; //!< Type of wide-dynamic-range (WDR) to use, if sensor supports it
81 CropType crop = CropType::Scale; //!< Type of crop/scale to apply if camera size does not match sensor native
82 bool ispython = false; //!< True if the module is written in Python; affects behavior of sopath() only
83
84 unsigned int c2fmt = 0; //!< When crop is CropScale, pixel format of the scaled images, otherwise 0
85 unsigned int c2w = 0; //!< When crop is CropScale, width of the scaled images, otherwise 0
86 unsigned int c2h = 0; //!< When crop is CropScale, height of the scaled images, otherwise 0
87
88 //! Return the full absolute path the module's directory
89 std::string path() const;
90
91 //! Return the full absolute path and file name of the module's .so or .py file
92 std::string sopath(bool delete_old_versions = false) const;
93
94 //! Return the full absolute path and file name of the module's .C or .py file
95 std::string srcpath() const;
96
97 //! Return the full absolute path and file name of the module's CMakeLists.txt file
98 std::string cmakepath() const;
99
100 //! Return the full absolute path and file name of the module's modinfo.html file
101 std::string modinfopath() const;
102
103 //! Return the size in bytes of an output image
104 unsigned int osize() const;
105
106 //! Return the size in bytes of a camera image
107 unsigned int csize() const;
108
109 //! Return the size in bytes of a scaled camera image, if stream==RawAndScaled, otherwise 0
110 unsigned int c2size() const;
111
112 //! Convert from USB/UVC interval to fps
113 /*! This function rounds to the nearest 1/100 fps. */
114 static float uvcToFps(unsigned int interval);
115
116 //! Convert from fps to USB/UVC interval
117 static unsigned int fpsToUvc(float fps);
118
119 //! Convert from V4L2 interval to fps
120 /*! This function rounds to the nearest 1/100 fps. */
121 static float v4l2ToFps(struct v4l2_fract const & interval);
122
123 //! Convert from fps to V4L2 interval
124 static struct v4l2_fract fpsToV4l2(float fps);
125
126 //! Return true if this VideoMapping's output format is a match to the given output parameters
127 bool match(unsigned int oformat, unsigned int owidth, unsigned int oheight, float oframespersec) const;
128
129 //! Convenience function to print out FCC WxH @ fps, for the output (UVC) format
130 std::string ostr() const;
131
132 //! Convenience function to print out FCC WxH @ fps, for the input (camera) format
133 std::string cstr() const;
134
135 //! Convenience function to print out FCC WxH @ fps, for the scaled camera input format, if stream==RawAndScaled
136 std::string c2str() const;
137
138 //! Convenience function to print out FCC WxH @ fps plus possibly second stream, for the input (camera) format
139 std::string cstrall() const;
140
141 //! Convenience function to print out the whole mapping in a human-friendly way
142 std::string str() const;
143
144 //! Convenience function to print out the whole mapping in a human-friendly way to be used in a menu
145 std::string menustr() const;
146
147 //! Convenience function to print out the whole mapping in a human-friendly way to be used in a menu
148 std::string menustr2() const;
149
150 //! Equality operator for specs but not vendor or module name
151 /*! Note that two mappings will be declared to match if their fps values are within 0.01fps, to avoid mismatches
152 due to floating point representation and rounding. */
153 bool hasSameSpecsAs(VideoMapping const & other) const;
154
155 //! Equality operator for specs and also vendor or module name
156 /*! Note that two mappings will be declared to match if their fps values are within 0.01fps, to avoid mismatches
157 due to floating point representation and rounding. */
158 bool isSameAs(VideoMapping const & other) const;
159
160 //! Determine whether module is C++ or python and set ispython flag accordingly
161 /*! The other fields should have been initialized already. operator>> and loadVideoMappings use this function
162 insternally, so no need to call it after making a VideoMapping from sream. This function throws if neither a
163 .so nor .py file is found in the appropriate place given module vendor and name. */
164 void setModuleType();
165 };
166
167 //! Stream a VideoMapping out, intended for machines
168 /*! Note that no std::endl is issued at the end. \relates jevois::VideoMapping */
169 std::ostream & operator<<(std::ostream & out, VideoMapping const & m);
170
171 //! Stream a VideoMapping in, intended for machines
172 /*! Note that the assumption is that the mapping is clean (no extra garbage). \relates jevois::VideoMapping */
173 std::istream & operator>>(std::istream & in, VideoMapping & m);
174
175 //! Load all the video mappings from the default config file
176 /*! \relates jevois::VideoMapping */
177 std::vector<VideoMapping> loadVideoMappings(CameraSensor s, size_t & defidx, bool checkso = true,
178 bool hasgui = false);
179
180 //! Parse all the mappings in a config file and also indicate which one is the default
181 /*! The contents of the file are sorted so that the resulting vector is ordered by increasing 1) format fcc, then 2)
182 resolution (from large to small, looking at x first), and 3) framerate (from high to low).
183
184 The camera format field can have colon-separated prefixes for qualifiers that specify WDR (wide-dynamic-range)
185 camera capture mode and/or crop vs. rescale behavior when camera input dims do not match sensor native dims (only
186 effective on JeVois-Pro).
187
188 The output width and height can be wither absolute, or relative to camera width and height if prefixed with a + or
189 - symbol.
190
191 In case of duplicate output formats, frame rates will be decreased by 1fps for each additional duplicate. This is
192 because we need to present the host computer with distinct video formats so that users can select the one they
193 want. For example:
194 \verbatim
195 YUYV 320 240 60.0 YUYV 320 240 60.0 JeVois SaveVideo
196 YUYV 320 240 60.0 YUYV 320 240 60.0 VendorX MyModule
197 YUYV 320 240 60.0 YUYV 320 240 60.0 VendorY MyModule
198 YUYV 320 240 60.0 YUYV 320 240 60.0 VendorZ MyModule
199 \endverbatim
200
201 will be disambiguated into:
202
203 \verbatim
204 YUYV 320 240 60.0 YUYV 320 240 60.0 JeVois SaveVideo
205 YUYV 320 240 59.0 YUYV 320 240 60.0 VendorX MyModule
206 YUYV 320 240 58.0 YUYV 320 240 60.0 VendorY MyModule
207 YUYV 320 240 57.0 YUYV 320 240 60.0 VendorZ MyModule
208 \endverbatim
209
210 and in \b guvcview or similar program running on a host computer, these 4 mappings will be available since they
211 correspond to 4 different framerates. It is recommended that you issue a \b listmapping command in the JeVois
212 command-line interface to confirm the final mappings that are used at runtime after any adjustments; see \ref
213 UserCli for details.
214
215 defidx is the index of the default format in the resulting vector of mappings. If several default formats are
216 specified, the first one prevails.
217
218 See \ref UserModes for explanations about how to organize \b videomappings.cfg
219 \relates jevois::VideoMapping */
220 std::vector<VideoMapping> videoMappingsFromStream(CameraSensor s, std::istream & is, size_t & defidx,
221 bool checkso, bool hasgui);
222}
223
Main namespace for all JeVois classes and functions.
Definition Concepts.dox:2
Simple struct to hold video mapping definitions for the processing Engine.
WDRtype wdr
Type of wide-dynamic-range (WDR) to use, if sensor supports it.
static struct v4l2_fract fpsToV4l2(float fps)
Convert from fps to V4L2 interval.
unsigned int cfmt
camera pixel format
unsigned int ow
output width
unsigned int csize() const
Return the size in bytes of a camera image.
unsigned int c2fmt
When crop is CropScale, pixel format of the scaled images, otherwise 0.
static float v4l2ToFps(struct v4l2_fract const &interval)
Convert from V4L2 interval to fps.
static unsigned int fpsToUvc(float fps)
Convert from fps to USB/UVC interval.
std::string modinfopath() const
Return the full absolute path and file name of the module's modinfo.html file.
bool hasSameSpecsAs(VideoMapping const &other) const
Equality operator for specs but not vendor or module name.
JEVOIS_DEFINE_ENUM_CLASS(CropType,(Scale)(Crop)(CropScale))
Enum for VideoMapping crop or rescale.
unsigned int c2w
When crop is CropScale, width of the scaled images, otherwise 0.
CropType crop
Type of crop/scale to apply if camera size does not match sensor native.
std::string modulename
Name of the Module that will process this mapping.
unsigned int osize() const
Return the size in bytes of an output image.
std::string ostr() const
Convenience function to print out FCC WxH @ fps, for the output (UVC) format.
std::string cstr() const
Convenience function to print out FCC WxH @ fps, for the input (camera) format.
std::string str() const
Convenience function to print out the whole mapping in a human-friendly way.
std::string c2str() const
Convenience function to print out FCC WxH @ fps, for the scaled camera input format,...
std::string cstrall() const
Convenience function to print out FCC WxH @ fps plus possibly second stream, for the input (camera) f...
float cfps
camera frame rate in frames/sec
JEVOIS_DEFINE_ENUM_CLASS(WDRtype,(Linear)(DOL))
Enum for VideoMapping wide-dynamic-range (WDR) type.
bool ispython
True if the module is written in Python; affects behavior of sopath() only.
std::string menustr2() const
Convenience function to print out the whole mapping in a human-friendly way to be used in a menu.
void setModuleType()
Determine whether module is C++ or python and set ispython flag accordingly.
unsigned int c2size() const
Return the size in bytes of a scaled camera image, if stream==RawAndScaled, otherwise 0.
std::vector< VideoMapping > loadVideoMappings(CameraSensor s, size_t &defidx, bool checkso=true, bool hasgui=false)
Load all the video mappings from the default config file.
std::string path() const
Return the full absolute path the module's directory.
unsigned int cw
camera width
float ofps
output frame rate in frames/sec
unsigned int c2h
When crop is CropScale, height of the scaled images, otherwise 0.
unsigned int ch
camera height
bool isSameAs(VideoMapping const &other) const
Equality operator for specs and also vendor or module name.
unsigned int oh
output height
unsigned int uvcformat
USB-UVC format number (1-based)
static float uvcToFps(unsigned int interval)
Convert from USB/UVC interval to fps.
unsigned int uvcframe
USB UVC frame number (1-based)
std::string srcpath() const
Return the full absolute path and file name of the module's .C or .py file.
std::string menustr() const
Convenience function to print out the whole mapping in a human-friendly way to be used in a menu.
std::ostream & operator<<(std::ostream &out, VideoMapping const &m)
Stream a VideoMapping out, intended for machines.
std::string vendor
Module creator name, used as a directory to organize the modules.
std::string sopath(bool delete_old_versions=false) const
Return the full absolute path and file name of the module's .so or .py file.
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.
std::vector< VideoMapping > videoMappingsFromStream(CameraSensor s, std::istream &is, size_t &defidx, bool checkso, bool hasgui)
Parse all the mappings in a config file and also indicate which one is the default.
std::string cmakepath() const
Return the full absolute path and file name of the module's CMakeLists.txt file.
unsigned int ofmt
output pixel format, or 0 for no output over USB
std::istream & operator>>(std::istream &in, VideoMapping &m)
Stream a VideoMapping in, intended for machines.