JeVois  1.16
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
jevois::Engine Class Reference

#include <jevois/Core/Engine.H>

JeVois processing engine - gets images from camera sensor, processes them, and sends results over USB.

The Engine is orchestrating the execution of vision processing software. It is a Manager, i.e., it is the root of a hierarchy of Component objects and it handles access to their Parameter settings and their construction, init(), unInit(), and destruction. The component hierarchy consists of Engine at the root, then one Module which is selected by the user at runtime, e.g., by selecting a given video format on video camera software running on a host computer connected to the JeVois hardware. The Module may then contain an arbitrarily complex hierarchy of Component objects with Parameter settings in them. Module derives from Component and thus may also have its own Parameter settings.

Engine contains the following basic elements:

  • A VideoInput, instantiated as either a Camera for live video streaming or a MovieInput for processing of pre-recorded video files or sequences of images (useful during algorithm development, to test and optimize on reproducible inputs);
  • A VideoOutput, instantiated either as a USB Gadget driver when running on the JeVois hardware platform, or as a VideoDisplay when running on a computer that has a graphics display, or as a MovieOutput to save output video frames to disk, or as a VideoOutputNone if desired for benchmarking of vision algorithms while discounting any work related to transmitting output frames.
  • A DynamicLoader which handles loading the chosen vision processing Module at runtime depending on user selections;
  • Any number of UserInterface objects, instantiated as either a hardware Serial port (for the 4-pin JST 1.0mm connector on the platform hardware), a serial-over-USB Serial port (visible on the host computer to which the JeVois hardware is connected by USB), or an StdioInterface (used to accept commands and print results directly in the terminal where the JeVois Engine was started, particularly useful when running on a generic computer as opposed to the platform hardware). When running on platform hardware, usually two UserInterface objects are created (one hardware Serial, one serial-over-USB Serial), while, when running on a generic computer, usually only one UserInterface is created (of type StdioInterface to accept commands directly in the terminal in which the jevois-daemon was started);
  • The list of VideoMapping definitions imported from your videomappings.cfg file. These definitions specify which video output modes are available over USB and their corresponding Camera settings and which Module to use, as well as which modes are available that do not have any sreaming video output over USB (e.g., when connecting the hardware platform to an Arduino only).

The main loop of Engine runs until the user decides to quit, and basically goes through the following steps:

  • Create an InputFrame object which is an exception-safe wrapper around the next available Camera frame. The frame may not have been captured yet. The InputFrame can be understood as a mechanism to gain access to that frame in the future, when it has become available (i.e., has been captured by the camera). This is very similar to the std::future framework of C++11.
  • When the current VideoMapping specifies that we will be streaming video frames out over USB, also create an OutputFrame object which is an exception-safe wrapper around the next available Gadget frame. This is also just a mechanism for gaining access to the next blank video buffer that is available from the USB driver and that we should fill with interesting pixel data before sending it over USB to a host computer.
  • Call the currently-loaded Module's process() function, either as process(InputFrame, OutputFrame) when the current VideoMapping specifies that some video output is to be sent over USB, or as process(InputFrame) when the current VideoMapping specifies no video output. Any exception thrown by the Module's process() function will be caught, reported, and ignored. The process() function would typically request the next available camera image through the InputFrame wrapper (this request may block until the frame has been captured by the camera sensor hardware), process that image, request the next available output image through the OutputFrame wrapper (when VideoMapping specifies that there is USB video output), and paint some results into that output image, which will then be sent to the host coputer over USB, for display by some webcam program or for further processing by some custom vision software running on that computer. In addition, the currently loaded Module may issue messages over the UserInterface ports (e.g., indicating the location at which an object was found, to let an Arduino know about it).
  • Read any new commands issued by users over the UserInterface ports and execute the appropriate commands.
  • Handle user requests to change VideoMapping, when they select a different video mode in their webcam software running on the host computer connected to the JeVois hardware. Such requests may trigger unloading of the current Module and loading a new one, and changing camera pixel format, image size, etc. These changes are guaranteed to occur when the Module's process() function is not running, i.e., Module programmers do not have to worry about possible changes in image dimensions or pixel formats during execution of their process() function.
  • Pass any user requests received over USB or UserInterface to adjust camera parameters to the actual Camera hardware driver (e.g., when users change contrast in their webcam program, that request is sent to the Engine over USB, and the Engine then forwards it to the Camera hardware driver).

Definition at line 381 of file Engine.H.

Inheritance diagram for jevois::Engine:
Collaboration diagram for jevois::Engine:

Public Member Functions

 Engine (std::string const &instance)
 Constructor. More...
 
 Engine (int argc, char const *argv[], std::string const &instance)
 Constructor with command-line parsing. More...
 
 ~Engine ()
 Destructor. More...
 
void reloadVideoMappings ()
 Re-load video mappings from videomappings.cfg. More...
 
const VideoMapping & findVideoMapping (unsigned int oformat, unsigned int owidth, unsigned int oheight, float oframespersec) const
 Find the VideoMapping that has the given output specs, or throw if not found. More...
 
const VideoMapping & getCurrentVideoMapping () const
 Get the current video mapping. More...
 
size_t numVideoMappings () const
 Return the number of video mappings. More...
 
const VideoMapping & getVideoMapping (size_t idx) const
 Allow access to our video mappings which are parsed from file at construction. More...
 
size_t getVideoMappingIdx (unsigned int iformat, unsigned int iframe, unsigned int interval) const
 Get the video mapping index for a given UVC iformat, iframe and interval. More...
 
const VideoMapping & getDefaultVideoMapping () const
 Allow access to the default video mapping. More...
 
size_t getDefaultVideoMappingIdx () const
 Allow access to the default video mapping index. More...
 
void foreachVideoMapping (std::function< void(VideoMapping const &m)> &&func)
 Run a function on every video mapping. More...
 
void requestSetFormat (int idx)
 Use this to request a format change from within process() More...
 
void quit ()
 Terminate the program. More...
 
void reboot ()
 Request a reboot. More...
 
void setFormat (size_t idx)
 Callback for when the user selects a new output video format. More...
 
void streamOn ()
 Start streaming on video from camera, processing, and USB. More...
 
void streamOff ()
 Stop streaming on video from camera, processing, and USB. More...
 
int mainLoop ()
 Main loop: grab, process, send over USB. Should be called by main application thread. More...
 
void sendSerial (std::string const &str, bool islog=false)
 Send a string to all serial ports. More...
 
size_t frameNum () const
 Get frame number. More...
 
std::shared_ptr< Modulemodule () const
 Get a pointer to our current module (may be null) More...
 
std::shared_ptr< IMUimu () const
 Get a pointer to our IMU (may be null) More...
 
std::shared_ptr< Cameracamera () const
 Get a pointer to our Camera (may be null, especially if not using a camera but, eg, movie input) More...
 
void drawCameraGUI ()
 Draw all camera controls into our GUI. More...
 
- Public Member Functions inherited from jevois::Manager
 Manager (std::string const &instance="TheManager")
 Constructor without command-line args. More...
 
 Manager (int argc, char const *argv[], std::string const &instance="TheManager")
 Constructor. More...
 
void setCommandLineArgs (int argc, char const *argv[])
 Set the command-line arguments, call this before start() if args were not passed at construction. More...
 
virtual ~Manager ()
 Destructor. More...
 
template<class Comp , typename... Args>
std::shared_ptr< Comp > addComponent (std::string const &instanceName, Args &&...args)
 Pseudo-constructor: construct a top-level Component. More...
 
template<class Comp , typename... Args>
std::shared_ptr< Comp > addSubComponent (std::string const &instanceName, Args &&...args)=delete
 Use addComponent() on the Manager as opposed to jevois::Component::addSubComponent() More...
 
template<class Comp >
void removeComponent (std::shared_ptr< Comp > &component)
 Remove a top-level Component from the Manager, by shared_ptr. More...
 
template<class Comp >
void removeSubComponent (std::shared_ptr< Comp > &component)=delete
 Use removeComponent() on the Manager as opposed to jevois::Component::removeSubComponent() More...
 
void removeComponent (std::string const &instanceName, bool warnIfNotFound=true)
 Remove a top-level Component from the Manager, by instance name. More...
 
void removeSubComponent (std::string const &instanceName, bool warnIfNotFound)=delete
 Use removeComponent() on the Manager as opposed to jevois::Component::removeSubComponent() More...
 
template<class Comp = jevois::Component>
std::shared_ptr< Comp > getComponent (std::string const &instanceName) const
 Get a top-level component by instance name. More...
 
template<class Comp >
std::shared_ptr< Comp > getSubComponent (std::string const &instanceName) const =delete
 Use getComponent() on the Manager as opposed to jevois::Component::getSubComponent() More...
 
const std::vector< std::string > & remainingArgs () const
 Get the remaining arguments that were not parsed by the command line. More...
 
- Public Member Functions inherited from jevois::Component
 Component (std::string const &instance)
 Constructor. More...
 
virtual ~Component ()
 Virtual destructor for safe inheritance. More...
 
template<class Comp , typename... Args>
std::shared_ptr< Comp > addSubComponent (std::string const &instance, Args &&...args)
 Pseudo-constructor: construct and add another component as a subcomponent of this one. More...
 
template<class Comp >
void removeSubComponent (std::shared_ptr< Comp > &component)
 Remove a sub-Component from this Component, by shared_ptr. More...
 
void removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
 Remove a sub-Component from this Component, by instance name. More...
 
template<class Comp = jevois::Component>
std::shared_ptr< Comp > getSubComponent (std::string const &instance) const
 Get a sub-component by instance name. More...
 
bool isTopLevel () const
 Returns true if this component is top-level, i.e., its parent is jevois::Manager. More...
 
Engineengine () const
 Get a handle to our Engine, or throw if we do not have an Engine as root ancestor. More...
 
bool initialized () const
 Has this component been initialized yet? More...
 
const std::string & className () const
 The class name of this component. More...
 
const std::string & instanceName () const
 The instance name of this component. More...
 
template<typename T >
std::vector< std::string > setParamVal (std::string const &paramdescriptor, T const &val)
 Set a parameter value. More...
 
template<typename T >
void setParamValUnique (std::string const &paramdescriptor, T const &val)
 Set a parameter value, simple version assuming only one parameter match. More...
 
template<typename T >
std::vector< std::pair< std::string, T > > getParamVal (std::string const &paramdescriptor) const
 Get parameter(s) value(s) by descriptor. More...
 
template<typename T >
getParamValUnique (std::string const &paramdescriptor) const
 Get a parameter value, simple version assuming only one parameter match. More...
 
std::vector< std::string > setParamString (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value, by string. More...
 
void setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value by string, simple version assuming only one parameter match. More...
 
std::vector< std::pair< std::string, std::string > > getParamString (std::string const &paramdescriptor) const
 Get a parameter value, by string. More...
 
std::string getParamStringUnique (std::string const &paramdescriptor) const
 Get a parameter value by string, simple version assuming only one parameter match. More...
 
void freezeParam (std::string const &paramdescriptor)
 Freeze a parameter, by name, see ParameterBase::freeze() More...
 
void unFreezeParam (std::string const &paramdescriptor)
 Unfreeze a parameter, by name, see ParameterBase::unFreeze() More...
 
void freezeAllParams ()
 Freeze all parameters. More...
 
void unFreezeAllParams ()
 Unfreeze all parameters. More...
 
std::string descriptor () const
 Get our full descriptor (including all parents) as [Instancename]:[...]:[...]. More...
 
void setParamsFromFile (std::string const &filename)
 Set some parameters from a file. More...
 
std::istream & setParamsFromStream (std::istream &is, std::string const &absfile)
 Set some parameters from an open stream. More...
 
virtual void paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
 Get machine-oriented descriptions of all parameters. More...
 
void foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
 Run a function on every param we hold. More...
 
void setPath (std::string const &path)
 Assign a filesystem path to this component. More...
 
std::string absolutePath (std::string const &path="")
 If given path is relative (not starting with /), prepend the Component path to it. More...
 
- Public Member Functions inherited from jevois::ParameterRegistry
virtual ~ParameterRegistry ()
 Virtual destructor for safe inheritance. More...
 

Protected Member Functions

void runScriptFromFile (std::string const &filename, std::shared_ptr< UserInterface > ser, bool throw_no_file)
 Run a script from file. More...
 
void onParamChange (engine::serialdev const &param, std::string const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::usbserialdev const &param, std::string const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::cpumode const &param, engine::CPUmode const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::cpumax const &param, unsigned int const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::videoerrors const &param, bool const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::gui const &param, bool const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::cpumaxl const &param, unsigned int const &newval) override
 Parameter callback. More...
 
void onParamChange (engine::cpumodel const &param, engine::CPUmode const &newval) override
 Parameter callback. More...
 
void preInit () override
 Override of Manager::preInit() More...
 
void postInit () override
 Override of Manager::postInit() More...
 
bool parseCommand (std::string const &str, std::shared_ptr< UserInterface > s, std::string const &pfx="")
 Parse a user command received over serial port. More...
 
- Protected Member Functions inherited from jevois::Manager
void onParamChange (manager::loglevel const &param, manager::LogLevel const &newval) override
 Parameter callback. More...
 
void onParamChange (manager::tracelevel const &param, unsigned int const &newval) override
 Parameter callback. More...
 
void constructHelpMessage (std::ostream &out) const
 Constructs a help message from all parameters in the model, and outputs it to 'out'. More...
 
void printHelpMessage () const
 Constructs a help message and tries to send it to /usr/bin/less. More...
 
- Protected Member Functions inherited from jevois::Component
virtual void preUninit ()
 Called before all sub-Components are uninit()ed. More...
 
virtual void postUninit ()
 Called after all sub-Components are uninit()ed. More...
 
- Protected Member Functions inherited from jevois::ParameterRegistry
void addParameter (ParameterBase *const param)
 The Parameter class uses this method to register itself on construction with its owning Component. More...
 
void removeParameter (ParameterBase *const param)
 The Parameter class uses this method to un-register itself on destruction with its owning Component. More...
 
void callbackInitCall ()
 For all parameters that have a callback which has never been called, call it with the default param value. More...
 

Protected Attributes

size_t itsDefaultMappingIdx
 Index of default mapping. More...
 
std::vector< VideoMapping > itsMappings
 All our mappings from videomappings.cfg. More...
 
VideoMapping itsCurrentMapping { }
 Current mapping, may not match any in itsMappings if setmapping2 used. More...
 
std::shared_ptr< VideoInputitsCamera
 Our camera. More...
 
std::shared_ptr< IMUitsIMU
 
std::shared_ptr< VideoOutputitsGadget
 Our IMU. More...
 
std::unique_ptr< DynamicLoaderitsLoader
 Our module loader. More...
 
std::shared_ptr< ModuleitsModule
 Our current module. More...
 
std::atomic< bool > itsRunning
 True when we are running. More...
 
std::atomic< bool > itsStreaming
 True when we are streaming video. More...
 
std::atomic< bool > itsStopMainLoop
 Flag used to stop the main loop. More...
 
std::timed_mutex itsMtx
 Mutex to protect our internals. More...
 

Related Functions

(Note that these are not member functions.)

 JEVOIS_DECLARE_PARAMETER (cameradev, std::string, "Camera device name (if starting with /dev/v...), or movie " "file name (e.g., movie.mpg) or image sequence (e.g., im%02d.jpg, to read frames " "im00.jpg, im01.jpg, etc).", JEVOIS_CAMERA_DEFAULT, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (camerasens, CameraSensor, "Camera sensor. Users would usually not set this parameter " "manually, it is set through boot-time configuration.", JEVOIS_CAMERASENS_DEFAULT, CameraSensor_Values, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (cameranbuf, unsigned int, "Number of video input (camera) buffers, or 0 for automatic.", 0, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (gadgetdev, std::string, "Gadget device name. This is used on platform hardware only. " "On host hardware, a display window will be used unless gadgetdev is None (useful " "for benchmarking) or is a file stem for a movie file that does not start with /dev/ " "(and which should contain a printf-style directive for a single int argument, " "the movie number).", JEVOIS_GADGET_DEFAULT, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (gadgetnbuf, unsigned int, "Number of video output (USB video) buffers, or 0 for auto", 0, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (videomapping, int, "Index of Video Mapping to use, or -1 to use the default mapping. " "Note that this parameter is only available when parsing command-line arguments. " "At runtime, the setmapping command should be used instead.", -1, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (serialdev, std::string, "Hardware (4-pin connector) serial device name, " "or 'stdio' to use the console, or empty for no hardware serial port", JEVOIS_SERIAL_DEFAULT, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (usbserialdev, std::string, "Over-the-USB serial device name, or empty", JEVOIS_USBSERIAL_DEFAULT, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (camreg, bool, "Enable raw access to camera registers through setcamreg and getcamreg", false, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (imureg, bool, "Enable raw access to IMU registers through setimureg and getimureg", false, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (camturbo, bool, "Enable camera turbo mode by relaxing the need for DMA-coherent video " "buffer memory. This can accelerate severalfolds access to the captured image data, but " "it may also yield stripe artifacts with some modules, such as PassThrough. The stripes " "are pieces of incorrect data in the cache. You should experiment with each particular " "module. Turbo mode is not recommended for any production-grade application.", false, ParamCateg)
 Parameter. More...
 
 JEVOIS_DEFINE_ENUM_CLASS (SerPort,(None)(All)(Hard)(USB))
 Enum for Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (serlog, SerPort, "Show log and debug messages on selected serial port(s)", SerPort::None, SerPort_Values, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (videoerrors, bool, "Show any machine vision module errors (exceptions) " "in the video stream. Only takes effect if streaming video to USB.", true, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (serout, SerPort, "Send module serial messages to selected serial port(s)", SerPort::None, SerPort_Values, ParamCateg)
 Parameter. More...
 
 JEVOIS_DEFINE_ENUM_CLASS (CPUmode,(PowerSave)(Conservative)(OnDemand)(Interactive)(Performance))
 Enum for Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (cpumode, CPUmode, "CPU frequency modulation mode" " for A73 big cores", CPUmode::Performance, CPUmode_Values, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (cpumodel, CPUmode, "CPU frequency modulation mode for A53 little cores", CPUmode::Performance, CPUmode_Values, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (cpumax, unsigned int, "CPU maximum frequency in MHz" ". To enable overclock frequencies above 2208 MHz, you need to first edit " "/boot/env.txt and change max_freq_a73, then reboot. Use with caution!", 2208, { 500, 667, 1000, 1200, 1398, 1512, 1608, 1704, 1800, 1908, 2016, 2100, 2208, 2304, 2400 }, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (cpumaxl, unsigned int, "CPU maximum frequency in MHz, for A53 little cores. " "To enable overclock frequencies above 1800 MHz, you need to first edit " "/boot/env.txt and change max_freq_a53, then reboot. Use with caution!", 1800, { 500, 667, 1000, 1200, 1398, 1512, 1608, 1704, 1800, 1908, 2016, 2100, 2208 }, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (multicam, bool, "Allow up to 3 JeVois cameras on one USB bus. Enabling this " "reduces the amount of USB bandwidth used by each JeVois camera, from 3kb " "per USB isochronous microframe to 1kb. All 3 JeVois cameras must have this " "option enabled, and the JeVois linux kernel module should also have " "been loaded with multicam on.", false, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (quietcmd, bool, "When true, do not issue a message 'OK' after every correct command " "received at the command-line interface. Recommended for advanced users only.", false, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (python, bool, "When true, enable support for modules written in Python. Otherwise, " "attempting to load a python module will throw an exception. Disabling python saves " "a lot of memory and may be useful when using C++ modules that run large deep neural " "networks.", true, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (serlimit, size_t, "Maximum number of serial messages that can be sent by a module " "using sendSerial(), for each video frame, or 0 for no limit. Any message sent by " "the module beyond the first serlimit ones will be dropped. This is useful to avoid " "overloading the serial link, for example in case one is running a ArUco detector and " "a large number of ArUco tags are present in the field of view of JeVois.", 0, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (gui, bool, "Use a graphical user interface instead of plain display " "when true", true, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (conslock, bool, "Lock the console and capture the keyboard and mouse to avoid " "interference, only effective on JeVois-Pro Platform, otherwise ignored. Set conslock " "to false if you are experiencing hard crashes and want to run jevoispro-daemon in gdb.", true, ParamCateg)
 Parameter. More...
 
 JEVOIS_DECLARE_PARAMETER (watchdog, double, "Timeout in seconds after which we kill this process if the main loop " "is stuck somehow, or 0.0 for no watchdog", 10.0, ParamCateg)
 Parameter. More...
 

Constructor & Destructor Documentation

◆ Engine() [1/2]

jevois::Engine::Engine ( std::string const &  instance)

Constructor.

Definition at line 213 of file Engine.C.

References jevois::async_little(), and JEVOIS_TRACE.

◆ Engine() [2/2]

jevois::Engine::Engine ( int  argc,
char const *  argv[],
std::string const &  instance 
)

Constructor with command-line parsing.

Definition at line 229 of file Engine.C.

References jevois::async_little(), and JEVOIS_TRACE.

◆ ~Engine()

jevois::Engine::~Engine ( )

Destructor.

Definition at line 621 of file Engine.C.

References JEVOIS_TIMED_LOCK, JEVOIS_TRACE, jevois::logSetEngine(), and jevois::warnAndIgnoreException().

Member Function Documentation

◆ camera()

std::shared_ptr< jevois::Camera > jevois::Engine::camera ( ) const

Get a pointer to our Camera (may be null, especially if not using a camera but, eg, movie input)

Definition at line 1225 of file Engine.C.

◆ drawCameraGUI()

void jevois::Engine::drawCameraGUI ( )

Draw all camera controls into our GUI.

Definition at line 2547 of file Engine.C.

◆ findVideoMapping()

const jevois::VideoMapping & jevois::Engine::findVideoMapping ( unsigned int  oformat,
unsigned int  owidth,
unsigned int  oheight,
float  oframespersec 
) const

Find the VideoMapping that has the given output specs, or throw if not found.

Definition at line 1293 of file Engine.C.

References jevois::fccstr(), and LFATAL.

◆ foreachVideoMapping()

void jevois::Engine::foreachVideoMapping ( std::function< void(VideoMapping const &m)> &&  func)

Run a function on every video mapping.

The first mapping your function will be called on is for mapping with index 0, and so on until index numVideoMappings()-1. If your function throws, we report the exception and then ignore it, then we move on to the next mapping.

Definition at line 1285 of file Engine.C.

References jevois::warnAndIgnoreException().

◆ frameNum()

size_t jevois::Engine::frameNum ( ) const

Get frame number.

The Engine maintains a master frame counter that is incremented on each call to a Module's process(), whether or not the call succeeds. The counter is not incremented when a module has not been loaded (e.g., failed to load). The counter is reset to zero each time a new module is loaded.

Definition at line 1213 of file Engine.C.

◆ getCurrentVideoMapping()

const jevois::VideoMapping & jevois::Engine::getCurrentVideoMapping ( ) const

Get the current video mapping.

Note that the current mapping may not have an entry in our list of mappings obtained from videomappings.cfg, if the current one was set on the fly by the setmapping2 CLI command.

Definition at line 1229 of file Engine.C.

◆ getDefaultVideoMapping()

const jevois::VideoMapping & jevois::Engine::getDefaultVideoMapping ( ) const

Allow access to the default video mapping.

Definition at line 1277 of file Engine.C.

Referenced by jevois::Gadget::Gadget().

◆ getDefaultVideoMappingIdx()

size_t jevois::Engine::getDefaultVideoMappingIdx ( ) const

Allow access to the default video mapping index.

Definition at line 1281 of file Engine.C.

◆ getVideoMapping()

const jevois::VideoMapping & jevois::Engine::getVideoMapping ( size_t  idx) const

Allow access to our video mappings which are parsed from file at construction.

Definition at line 1237 of file Engine.C.

References LFATAL.

◆ getVideoMappingIdx()

size_t jevois::Engine::getVideoMappingIdx ( unsigned int  iformat,
unsigned int  iframe,
unsigned int  interval 
) const

Get the video mapping index for a given UVC iformat, iframe and interval.

Definition at line 1246 of file Engine.C.

References LFATAL.

◆ imu()

std::shared_ptr< jevois::IMU > jevois::Engine::imu ( ) const

Get a pointer to our IMU (may be null)

Definition at line 1221 of file Engine.C.

◆ mainLoop()

◆ module()

std::shared_ptr< jevois::Module > jevois::Engine::module ( ) const

Get a pointer to our current module (may be null)

Definition at line 1217 of file Engine.C.

Referenced by jevois::GUIhelper::drawConsole(), and jevois::GUIhelper::drawParameters().

◆ numVideoMappings()

size_t jevois::Engine::numVideoMappings ( ) const

Return the number of video mappings.

Definition at line 1233 of file Engine.C.

◆ onParamChange() [1/8]

void jevois::Engine::onParamChange ( engine::cpumax const &  param,
unsigned int const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [2/8]

void jevois::Engine::onParamChange ( engine::cpumaxl const &  param,
unsigned int const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [3/8]

void jevois::Engine::onParamChange ( engine::cpumode const &  param,
engine::CPUmode const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [4/8]

void jevois::Engine::onParamChange ( engine::cpumodel const &  param,
engine::CPUmode const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [5/8]

void jevois::Engine::onParamChange ( engine::gui const &  param,
bool const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [6/8]

void jevois::Engine::onParamChange ( engine::serialdev const &  param,
std::string const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [7/8]

void jevois::Engine::onParamChange ( engine::usbserialdev const &  param,
std::string const &  newval 
)
overrideprotected

Parameter callback.

◆ onParamChange() [8/8]

void jevois::Engine::onParamChange ( engine::videoerrors const &  param,
bool const &  newval 
)
overrideprotected

Parameter callback.

◆ parseCommand()

bool jevois::Engine::parseCommand ( std::string const &  str,
std::shared_ptr< UserInterface s,
std::string const &  pfx = "" 
)
protected

Parse a user command received over serial port.

Throw upon receiving an incorrect command (eg, bad parameter value), return true if success, return false if command was not recognized and should be tried by Module. pfx is an optional prefix which will be added to all produced messages or errors.

Definition at line 1677 of file Engine.C.

References jevois::Serial::fileGet(), jevois::Serial::filePut(), jevois::imu::get(), jevois::getSysInfoCPU(), jevois::getSysInfoMem(), jevois::getSysInfoVersion(), JEVOISPRO_FMT_GUI, LDEBUG, jevois::split(), jevois::system(), jevois::to_string(), and jevois::UserInterface::writeString().

◆ postInit()

◆ preInit()

void jevois::Engine::preInit ( )
overrideprotectedvirtual

Override of Manager::preInit()

Reimplemented from jevois::Manager.

Definition at line 426 of file Engine.C.

References jevois::Manager::preInit().

◆ quit()

void jevois::Engine::quit ( )

Terminate the program.

Definition at line 1576 of file Engine.C.

◆ reboot()

void jevois::Engine::reboot ( )

Request a reboot.

On JeVois-A33 Platform, trigger a hard reset. On JeVois-Pro Platform or JeVois-Host, just terminate the program.

Definition at line 1555 of file Engine.C.

References LERROR, and jevois::system().

◆ reloadVideoMappings()

void jevois::Engine::reloadVideoMappings ( )

Re-load video mappings from videomappings.cfg.

Mappings are automatically loaded on startup so this should only be used if the file has been modified and the mappings need to be refreshed. Note that this will not refresh the available resolutions for USB output, which requires a full reboot to re-initialize the kernel Gadget module. Also beware of possible state inconsistency (e.g., if external code is holding a reference previously returned by findVideoMapping(). So, use with caution. Basically, only GUIhelper should use this.

Definition at line 437 of file Engine.C.

References jevois::imu::get(), and LINFO.

◆ requestSetFormat()

void jevois::Engine::requestSetFormat ( int  idx)

Use this to request a format change from within process()

This should only be used on JeVois-Pro in GUI mode. The engine is locked up hence and setFormat() cannot be called from within a Module's process function, to avoid possible disasters of changing format while we process. Modules or the GUI can use requestSetFormat() to request a format change in between two calls to process(). Note special values: -1 to just reload the current format (e.g., after editing code), -2 does nothing.

Definition at line 723 of file Engine.C.

References JEVOIS_TRACE.

◆ runScriptFromFile()

void jevois::Engine::runScriptFromFile ( std::string const &  filename,
std::shared_ptr< UserInterface ser,
bool  throw_no_file 
)
protected

Run a script from file.

The filename should be absolute. The file should have any of the commands supported by Engine, one per line. Filename should be relative to the current module's path.

Definition at line 2469 of file Engine.C.

References jevois::imu::get(), jevois::UserInterface::GUI, jevois::UserInterface::Hard, LFATAL, jevois::strip(), jevois::to_string(), jevois::UserInterface::type(), jevois::UserInterface::USB, jevois::warnAndIgnoreException(), and jevois::UserInterface::writeString().

◆ sendSerial()

void jevois::Engine::sendSerial ( std::string const &  str,
bool  islog = false 
)

Send a string to all serial ports.

Note
When islog is true, this is assumes to be a log message, and it will be sent to the port(s) specified by parameter serlog. Otherwise, the message will be sent to the ports specified by parameter serout. Note how the number of messages that can be sent for each video frame may be limited by parameter serlimit; only up to serlimit messages will be sent for a given video frame. This is useful to avoid overloading the serial link, for example in cases one is running a ArUco detector and a large number of ArUco tags are present in the field of view of JeVois.

Definition at line 1120 of file Engine.C.

References jevois::imu::get(), jevois::UserInterface::GUI, jevois::UserInterface::Hard, jevois::UserInterface::type(), jevois::UserInterface::USB, jevois::warnAndIgnoreException(), and jevois::UserInterface::writeString().

Referenced by jevois::Module::sendSerial().

◆ setFormat()

void jevois::Engine::setFormat ( size_t  idx)

Callback for when the user selects a new output video format.

Here, we stop streaming, nuke any current processing module, set the camera format, set the gadget output format, load the new processing module, and start streaming again. The given VideoMapping will typically be obtained using findVideoMapping() from output specs received over the USB link.

Definition at line 730 of file Engine.C.

References JEVOIS_TIMED_LOCK, JEVOIS_TRACE, LDEBUG, and LFATAL.

◆ streamOff()

void jevois::Engine::streamOff ( )

Stop streaming on video from camera, processing, and USB.

Definition at line 702 of file Engine.C.

References JEVOIS_TIMED_LOCK, JEVOIS_TRACE, and LDEBUG.

◆ streamOn()

void jevois::Engine::streamOn ( )

Start streaming on video from camera, processing, and USB.

Definition at line 691 of file Engine.C.

References JEVOIS_TIMED_LOCK, and JEVOIS_TRACE.

Referenced by main().

Friends And Related Function Documentation

◆ JEVOIS_DECLARE_PARAMETER() [1/17]

JEVOIS_DECLARE_PARAMETER ( cameradev  ,
std::string  ,
"Camera device name   if starting with /dev/v...,
or movie " "file name(e.g., movie.mpg) or image sequence(e.g., im%02d.jpg, to read frames " "im00.jpg, im01.jpg, etc)."  ,
JEVOIS_CAMERA_DEFAULT  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [2/17]

JEVOIS_DECLARE_PARAMETER ( cameranbuf  ,
unsigned int  ,
"Number of video input (camera buffers,
or 0 for automatic."  ,
,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [3/17]

JEVOIS_DECLARE_PARAMETER ( camerasens  ,
CameraSensor  ,
"Camera sensor. Users would usually not set this parameter " "  manually,
it is set through boot-time configuration."  ,
JEVOIS_CAMERASENS_DEFAULT  ,
CameraSensor_Values  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [4/17]

JEVOIS_DECLARE_PARAMETER ( camreg  ,
bool  ,
"Enable raw access to camera registers through setcamreg and getcamreg"  ,
false  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [5/17]

JEVOIS_DECLARE_PARAMETER ( camturbo  ,
bool  ,
"Enable camera turbo mode by relaxing the need for DMA-coherent video " "buffer memory. This can accelerate severalfolds access to the captured image  data,
but " "it may also yield stripe artifacts with some  modules,
such as PassThrough. The stripes " "are pieces of incorrect data in the cache. You should experiment with each particular " "module. Turbo mode is not recommended for any production-grade application."  ,
false  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [6/17]

JEVOIS_DECLARE_PARAMETER ( conslock  ,
bool  ,
"Lock the console and capture the keyboard and mouse to avoid " "  interference,
only effective on JeVois-Pro  Platform,
otherwise ignored. Set conslock " "to false if you are experiencing hard crashes and want to run jevoispro-daemon in gdb."  ,
true  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [7/17]

JEVOIS_DECLARE_PARAMETER ( gadgetdev  ,
std::string  ,
"Gadget device name. This is used on platform hardware only. " "On host  hardware,
a display window will be used unless gadgetdev is None(useful " "for benchmarking) or is a file stem for a movie file that does not start with/dev/" "(and which should contain a printf-style directive for a single int argument, " "the movie number)."  ,
JEVOIS_GADGET_DEFAULT  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [8/17]

JEVOIS_DECLARE_PARAMETER ( gadgetnbuf  ,
unsigned int  ,
"Number of video output (USB video)  buffers,
or 0 for auto"  ,
,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [9/17]

JEVOIS_DECLARE_PARAMETER ( imureg  ,
bool  ,
"Enable raw access to IMU registers through setimureg and getimureg"  ,
false  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [10/17]

JEVOIS_DECLARE_PARAMETER ( multicam  ,
bool  ,
"Allow up to 3 JeVois cameras on one USB bus. Enabling this " "reduces the amount of USB bandwidth used by each JeVois  camera,
from 3kb " "per USB isochronous microframe to 1kb. All 3 JeVois cameras must have this " "option  enabled,
and the JeVois linux kernel module should also have " "been loaded with multicam on."  ,
false  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [11/17]

JEVOIS_DECLARE_PARAMETER ( python  ,
bool  ,
"When  true,
enable support for modules written in Python.  Otherwise,
" "attempting to load a python module will throw an exception. Disabling python saves " "a lot of memory and may be useful when using C++modules that run large deep neural " "networks."  ,
true  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [12/17]

JEVOIS_DECLARE_PARAMETER ( quietcmd  ,
bool  ,
"When  true,
do not issue a message 'OK' after every correct command " "received at the command-line interface. Recommended for advanced users only."  ,
false  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [13/17]

JEVOIS_DECLARE_PARAMETER ( serlimit  ,
size_t  ,
"Maximum number of serial messages that can be sent by a module " "using   sendSerial(),
for each video  frame,
or 0 for no limit. Any message sent by " "the module beyond the first serlimit ones will be dropped. This is useful to avoid " "overloading the serial  link,
for example in case one is running a ArUco detector and " "a large number of ArUco tags are present in the field of view of JeVois."  ,
,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [14/17]

JEVOIS_DECLARE_PARAMETER ( serlog  ,
SerPort  ,
"Show log and debug messages on selected serial port(s)"  ,
SerPort::None  ,
SerPort_Values  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [15/17]

JEVOIS_DECLARE_PARAMETER ( serout  ,
SerPort  ,
"Send module serial messages to selected serial port(s)"  ,
SerPort::None  ,
SerPort_Values  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [16/17]

JEVOIS_DECLARE_PARAMETER ( videomapping  ,
int  ,
"Index of Video Mapping to  use,
or -1 to use the default mapping. " "Note that this parameter is only available when parsing command-line arguments. " "At  runtime,
the setmapping command should be used instead."  ,
1,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER() [17/17]

JEVOIS_DECLARE_PARAMETER ( watchdog  ,
double  ,
"Timeout in seconds after which we kill this process if the main loop " "is stuck  somehow,
or 0.0 for no watchdog"  ,
10.  0,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [1/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( cpumax  ,
unsigned int  ,
"CPU maximum frequency in MHz" ". To enable overclock frequencies above 2208  MHz,
you need to first edit " "/boot/env.txt and change  max_freq_a73,
then reboot. Use with caution!"  ,
2208  ,
{ 500, 667, 1000, 1200, 1398, 1512, 1608, 1704, 1800, 1908, 2016, 2100, 2208, 2304, 2400 }  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [2/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( cpumaxl  ,
unsigned int  ,
"CPU maximum frequency in  MHz,
for A53 little cores. " "To enable overclock frequencies above 1800  MHz,
you need to first edit " "/boot/env.txt and change  max_freq_a53,
then reboot. Use with caution!"  ,
1800  ,
{ 500, 667, 1000, 1200, 1398, 1512, 1608, 1704, 1800, 1908, 2016, 2100, 2208 }  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [3/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( cpumode  ,
CPUmode  ,
"CPU frequency modulation mode" " for A73 big cores"  ,
CPUmode::Performance  ,
CPUmode_Values  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [4/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( cpumodel  ,
CPUmode  ,
"CPU frequency modulation mode for A53 little cores"  ,
CPUmode::Performance  ,
CPUmode_Values  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [5/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( gui  ,
bool  ,
"Use a graphical user interface instead of plain display " "when true"  ,
true  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [6/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( serialdev  ,
std::string  ,
"Hardware (4-pin connector) serial device  name,
" "or 'stdio' to use the  console,
or empty for no hardware serial port"  ,
JEVOIS_SERIAL_DEFAULT  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [7/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( usbserialdev  ,
std::string  ,
"Over-the-USB serial device  name,
or empty"  ,
JEVOIS_USBSERIAL_DEFAULT  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [8/8]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( videoerrors  ,
bool  ,
"Show any machine vision module errors (exceptions) " "in the video stream. Only takes effect if streaming video to USB."  ,
true  ,
ParamCateg   
)
related

Parameter.

◆ JEVOIS_DEFINE_ENUM_CLASS() [1/2]

JEVOIS_DEFINE_ENUM_CLASS ( CPUmode  ,
(PowerSave)(Conservative)(OnDemand)(Interactive)(Performance)   
)
related

Enum for Parameter.

◆ JEVOIS_DEFINE_ENUM_CLASS() [2/2]

JEVOIS_DEFINE_ENUM_CLASS ( SerPort  ,
(None)(All)(Hard)(USB)   
)
related

Enum for Parameter.

Member Data Documentation

◆ itsCamera

std::shared_ptr<VideoInput> jevois::Engine::itsCamera
protected

Our camera.

Definition at line 537 of file Engine.H.

◆ itsCurrentMapping

VideoMapping jevois::Engine::itsCurrentMapping { }
protected

Current mapping, may not match any in itsMappings if setmapping2 used.

Definition at line 535 of file Engine.H.

◆ itsDefaultMappingIdx

size_t jevois::Engine::itsDefaultMappingIdx
protected

Index of default mapping.

Definition at line 533 of file Engine.H.

◆ itsGadget

std::shared_ptr<VideoOutput> jevois::Engine::itsGadget
protected

Our IMU.

Our gadget

Definition at line 539 of file Engine.H.

◆ itsIMU

std::shared_ptr<IMU> jevois::Engine::itsIMU
protected

Definition at line 538 of file Engine.H.

◆ itsLoader

std::unique_ptr<DynamicLoader> jevois::Engine::itsLoader
protected

Our module loader.

Definition at line 541 of file Engine.H.

◆ itsMappings

std::vector<VideoMapping> jevois::Engine::itsMappings
protected

All our mappings from videomappings.cfg.

Definition at line 534 of file Engine.H.

◆ itsModule

std::shared_ptr<Module> jevois::Engine::itsModule
protected

Our current module.

Definition at line 542 of file Engine.H.

◆ itsMtx

std::timed_mutex jevois::Engine::itsMtx
mutableprotected

Mutex to protect our internals.

Definition at line 548 of file Engine.H.

◆ itsRunning

std::atomic<bool> jevois::Engine::itsRunning
protected

True when we are running.

Definition at line 544 of file Engine.H.

◆ itsStopMainLoop

std::atomic<bool> jevois::Engine::itsStopMainLoop
protected

Flag used to stop the main loop.

Definition at line 546 of file Engine.H.

◆ itsStreaming

std::atomic<bool> jevois::Engine::itsStreaming
protected

True when we are streaming video.

Definition at line 545 of file Engine.H.


The documentation for this class was generated from the following files: