JeVois  1.17
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
jevois::InputFrame Class Reference

#include <jevois/Core/InputFrame.H>

Exception-safe wrapper around a raw camera input frame.

This wrapper operates much like std:future in standard C++11. Users can get the next image captured by the camera by calling get(), which may block if the capture is not complete yet, or may throw if the capture fails for some reason (e.g., the camera is not streaming). The image size and pixel type are as defined by the current VideoMapping, camera section. In addition, a done() function is provided which users may use as soon as they are finished with the pixel data in the image obtained via get(), to allow the camera driver to setup the underlying memory buffer again for capture. If done() has not been called by the time the InputFrame is destroyed, it will be called automatically, if get() had been called. It may in some cases improve your frame rate to call done() manually as early as possible instead of letting the InputFrame destructor do it.

InputFrame implements a zero-copy, zero-wait access to input video frames, that is:

  1. the pixel data of the image you obtain via get() is directly the memory-mapped pixel buffer that the silicon hardware on the JeVois chip uses via direct-memory-access (DMA) to stream the pixel data from the camera chip to processor memory;
  2. as soon as an image is captured by the camera hardware, get() unblocks and returns it (as opposed to having a fixed, regular interval at which images may be available). Camera has several image buffers, allowing one to be captured while another is being handed over for processing via get(). These buffers are recycled, i.e., once done() is called, the underlying buffer is sent back to the camera hardware for future capture.

Definition at line 50 of file InputFrame.H.

Public Member Functions

 InputFrame (InputFrame &&other)=default
 Move constructor. More...
 
const RawImageget (bool casync=false) const
 Get the next captured camera image. More...
 
bool hasScaledImage () const
 Check whether a second input image scaled by the JeVoisPro Platform ISP is available. More...
 
const RawImageget2 (bool casync=false) const
 Get the next captured camera image, ISP-scaled second frame. More...
 
const RawImagegetp (bool casync=false) const
 Get the next captured camera image that is intended for processing. More...
 
int getDmaFd (bool casync=false) const
 Get the DMA-BUF file descriptor of the camera frame. More...
 
int getDmaFd2 (bool casync=false) const
 Get the DMA-BUF file descriptor of the ISP-scaled second camera frame. More...
 
void done () const
 Indicate that user processing is done with the image previously obtained via get() More...
 
void done2 () const
 Indicate that user processing is done with the ISP-scaled image previously obtained via get2() More...
 
cv::Mat getCvGRAY (bool casync=false) const
 Shorthand to get the input image as a GRAY cv::Mat and release the raw buffer. More...
 
cv::Mat getCvBGR (bool casync=false) const
 Shorthand to get the input image as a BGR cv::Mat and release the raw buffer. More...
 
cv::Mat getCvRGB (bool casync=false) const
 Shorthand to get the input image as a RGB cv::Mat and release the raw buffer. More...
 
cv::Mat getCvRGBA (bool casync=false) const
 Shorthand to get the input image as a RGBA cv::Mat and release the raw buffer. More...
 
cv::Mat getCvGRAYp (bool casync=false) const
 Shorthand to get the input image for processing as a GRAY cv::Mat and release the raw buffer. More...
 
cv::Mat getCvBGRp (bool casync=false) const
 Shorthand to get the input image for processing as a BGR cv::Mat and release the raw buffer. More...
 
cv::Mat getCvRGBp (bool casync=false) const
 Shorthand to get the input image for processing as a RGB cv::Mat and release the raw buffer. More...
 
cv::Mat getCvRGBAp (bool casync=false) const
 Shorthand to get the input image for processing as a RGBA cv::Mat and release the raw buffer. More...
 
 ~InputFrame ()
 Destructor, returns the buffers to the driver as needed. More...
 

Friends

class Engine
 

Constructor & Destructor Documentation

◆ InputFrame()

jevois::InputFrame::InputFrame ( InputFrame &&  other)
default

Move constructor.

◆ ~InputFrame()

jevois::InputFrame::~InputFrame ( )

Destructor, returns the buffers to the driver as needed.

Definition at line 31 of file InputFrame.C.

References jevois::imu::get().

Member Function Documentation

◆ done()

void jevois::InputFrame::done ( ) const

Indicate that user processing is done with the image previously obtained via get()

You should call this as soon after get() as possible, once you are finished with the RawImage data so that it can be recycled and sent back to the camera driver for video capture.

Definition at line 102 of file InputFrame.C.

◆ done2()

void jevois::InputFrame::done2 ( ) const

Indicate that user processing is done with the ISP-scaled image previously obtained via get2()

You should call this as soon after get() as possible, once you are finished with the RawImage data so that it can be recycled and sent back to the camera driver for video capture.

Definition at line 109 of file InputFrame.C.

◆ get()

const jevois::RawImage & jevois::InputFrame::get ( bool  casync = false) const

Get the next captured camera image.

Throws if we the camera is not streaming or blocks until an image is available (has been captured). It is ok to call get() several times, but the same image will always be returned. To obtain successive frames from the camera, you must be fed successive InputFrame wrappers by the JeVois Engine.

Definition at line 50 of file InputFrame.C.

References jevois::RawImage::buf.

Referenced by jevois::GUIhelper::drawInputFrame(), and jevois::GUIhelper::iinfo().

◆ get2()

const jevois::RawImage & jevois::InputFrame::get2 ( bool  casync = false) const

Get the next captured camera image, ISP-scaled second frame.

On JeVois-Pro Platform only, the camera ISP can output 2 frames: 1) raw from sensor, 2) scaled by ISP. This function is to access the ISP scaled frame. Throws if not JeVois-Pro Platform or the camera stream type is not jevois::StreamType::RawAndScaled. Throws if we the camera is not streaming or blocks until an image is available (has been captured). It is ok to call get2() several times, but the same image will always be returned. To obtain successive frames from the camera, you must be fed successive InputFrame wrappers by the JeVois Engine.

Definition at line 67 of file InputFrame.C.

References jevois::RawImage::buf.

Referenced by jevois::GUIhelper::drawInputFrame(), jevois::GUIhelper::drawInputFrame2(), jevois::GUIhelper::iinfo(), and jevois::GPUimage::set2().

◆ getCvBGR()

cv::Mat jevois::InputFrame::getCvBGR ( bool  casync = false) const

Shorthand to get the input image as a BGR cv::Mat and release the raw buffer.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 125 of file InputFrame.C.

References jevois::rawimage::convertToCvBGR(), and jevois::imu::get().

◆ getCvBGRp()

cv::Mat jevois::InputFrame::getCvBGRp ( bool  casync = false) const

Shorthand to get the input image for processing as a BGR cv::Mat and release the raw buffer.

Returns the frame intended for processing, i.e., either the single camera frame when using single-stream capture, or the second frame when using dual stream capture. This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 161 of file InputFrame.C.

References jevois::rawimage::convertToCvBGR().

◆ getCvGRAY()

cv::Mat jevois::InputFrame::getCvGRAY ( bool  casync = false) const

Shorthand to get the input image as a GRAY cv::Mat and release the raw buffer.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 116 of file InputFrame.C.

References jevois::rawimage::convertToCvGray(), and jevois::imu::get().

◆ getCvGRAYp()

cv::Mat jevois::InputFrame::getCvGRAYp ( bool  casync = false) const

Shorthand to get the input image for processing as a GRAY cv::Mat and release the raw buffer.

Returns the frame intended for processing, i.e., either the single camera frame when using single-stream capture, or the second frame when using dual stream capture. This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 152 of file InputFrame.C.

References jevois::rawimage::convertToCvGray().

◆ getCvRGB()

cv::Mat jevois::InputFrame::getCvRGB ( bool  casync = false) const

Shorthand to get the input image as a RGB cv::Mat and release the raw buffer.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 134 of file InputFrame.C.

References jevois::rawimage::convertToCvRGB(), and jevois::imu::get().

◆ getCvRGBA()

cv::Mat jevois::InputFrame::getCvRGBA ( bool  casync = false) const

Shorthand to get the input image as a RGBA cv::Mat and release the raw buffer.

This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 143 of file InputFrame.C.

References jevois::rawimage::convertToCvRGBA(), and jevois::imu::get().

◆ getCvRGBAp()

cv::Mat jevois::InputFrame::getCvRGBAp ( bool  casync = false) const

Shorthand to get the input image for processing as a RGBA cv::Mat and release the raw buffer.

Returns the frame intended for processing, i.e., either the single camera frame when using single-stream capture, or the second frame when using dual stream capture. This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 179 of file InputFrame.C.

References jevois::rawimage::convertToCvRGBA().

◆ getCvRGBp()

cv::Mat jevois::InputFrame::getCvRGBp ( bool  casync = false) const

Shorthand to get the input image for processing as a RGB cv::Mat and release the raw buffer.

Returns the frame intended for processing, i.e., either the single camera frame when using single-stream capture, or the second frame when using dual stream capture. This is mostly intended for Python module writers, as they will likely use OpenCV for all their image processing. C++ module writers should stick to the get()/done() pair as this provides better fine-grained control. Note that the raw image from the camera will always be copied or converted to cv::Mat and will then be released by calling done(), so users should not call done() after using this function. This function is basically equivalent to calling get(), converting to cv::Mat, and calling done().

Definition at line 170 of file InputFrame.C.

References jevois::rawimage::convertToCvRGB().

◆ getDmaFd()

int jevois::InputFrame::getDmaFd ( bool  casync = false) const

Get the DMA-BUF file descriptor of the camera frame.

This file descriptor can be used to share the pixel buffer across interfaces that support DMA-BUF. The JeVois core uses this to create a zero-copy pipeline from the camera sensor to the hardware-accelerated OpenGL display on JeVois-Pro. Returns -1 if DMA-BUF is not supported (on host, and on JeVois-A33 platform). If get() has not previously been called, it will be called, which blocks until the next camera frame is available. It is ok to call getDmaFd() several times but always the same fd is returned (see get()).

Definition at line 86 of file InputFrame.C.

References jevois::imu::get().

◆ getDmaFd2()

int jevois::InputFrame::getDmaFd2 ( bool  casync = false) const

Get the DMA-BUF file descriptor of the ISP-scaled second camera frame.

On JeVois-Pro Platform only, the camera ISP can output 2 frames: 1) raw from sensor, 2) scaled by ISP. This function is to access the ISP scaled frame. Throws if not JeVois-Pro Platform or the camera stream type is not jevois::StreamType::RawAndScaled. This file descriptor can be used to share the pixel buffer across interfaces that support DMA-BUF. The JeVois core uses this to create a zero-copy pipeline from the camera sensor to the hardware-accelerated OpenGL display on JeVois-Pro. Returns -1 if DMA-BUF is not supported (on host, and on JeVois-A33 platform). If get() has not previously been called, it will be called, which blocks until the next camera frame is available. It is ok to call getDmaFd() several times but always the same fd is returned (see get2()).

Definition at line 94 of file InputFrame.C.

◆ getp()

const jevois::RawImage & jevois::InputFrame::getp ( bool  casync = false) const

Get the next captured camera image that is intended for processing.

Same as get() if hasScaledImage() is false, or as get2() if hasScaledImage() is true.

Definition at line 79 of file InputFrame.C.

References jevois::imu::get().

◆ hasScaledImage()

bool jevois::InputFrame::hasScaledImage ( ) const

Check whether a second input image scaled by the JeVoisPro Platform ISP is available.

Returns false unless we are on JeVois-Pro Platform and the camera format modifier jevois::CropType::CropScale is currently in use.

Definition at line 61 of file InputFrame.C.

Referenced by jevois::GUIhelper::drawInputFrame(), and jevois::GUIhelper::iinfo().

Friends And Related Function Documentation

◆ Engine

friend class Engine
friend

Definition at line 189 of file InputFrame.H.


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