Jetson Inference
DNN Vision Library

Camera capture and streaming for MIPI CSI and V4L2 devices (deprecated). More...

Classes

class  gstCamera
 MIPI CSI and V4L2 camera capture using GStreamer and nvarguscamerasrc or v4l2src elements. More...
 
class  v4l2Camera
 Video4Linux2 (V4L2) camera capture streaming. More...
 

Detailed Description

Camera capture and streaming for MIPI CSI and V4L2 devices (deprecated).

Deprecated:
See the updated Video Streaming APIs.

Class Documentation

◆ gstCamera

class gstCamera

MIPI CSI and V4L2 camera capture using GStreamer and nvarguscamerasrc or v4l2src elements.

gstCamera supports both MIPI CSI cameras and V4L2-compliant devices like USB webcams.

Examples of MIPI CSI cameras that work out of the box are the OV5693 module from the Jetson TX1/TX2 devkits, and the IMX219 sensor from the Raspberry Pi Camera Module v2.

For MIPI CSI cameras, the GStreamer element nvarguscamerasrc will be used for capture. For V4L2 devices, the GStreamer element v4l2src will be used for camera capture.

gstCamera uses CUDA underneath for any necessary colorspace conversion, and provides the captured image frames in CUDA device memory, or zero-copy shared CPU/GPU memory.

Note
gstCamera now implements the videoSource interface and is intended to be used through that as opposed to directly. videoSource implements additional command-line parsing of videoOptions to construct instances. Some legacy APIs of gstCamera are now marked deprecated.
See also
videoSource
Inheritance diagram for gstCamera:
videoSource

Public Member Functions

 ~gstCamera ()
 Release the camera interface and resources. More...
 
virtual bool Open ()
 Begin streaming the camera. More...
 
virtual void Close ()
 Stop streaming the camera. More...
 
virtual bool Capture (void **image, imageFormat format, uint64_t timeout=DEFAULT_TIMEOUT, int *status=NULL)
 Capture the next image frame from the camera. More...
 
bool CaptureRGBA (float **image, uint64_t timeout=DEFAULT_TIMEOUT, bool zeroCopy=false)
 Capture the next image frame from the camera and convert it to float4 RGBA format, with pixel intensities ranging between 0.0 and 255.0. More...
 
void SetZeroCopy (bool zeroCopy)
 Set whether converted RGB(A) images should use ZeroCopy buffer allocation. More...
 
virtual uint32_t GetType () const
 Return the interface type (gstCamera::Type) More...
 
- Public Member Functions inherited from videoSource
virtual ~videoSource ()
 Destroy interface and release all resources. More...
 
template<typename T >
bool Capture (T **image, int *status)
 Capture the next image from the video stream, using the default timeout of 1000ms. More...
 
template<typename T >
bool Capture (T **image, uint64_t timeout=DEFAULT_TIMEOUT, int *status=NULL)
 Capture the next image from the video stream. More...
 
bool IsStreaming () const
 Check if the device is actively streaming or not. More...
 
uint32_t GetWidth () const
 Return the width of the stream, in pixels. More...
 
uint32_t GetHeight () const
 Return the height of the stream, in pixels. More...
 
uint32_t GetFrameRate () const
 Return the framerate, in Hz or FPS. More...
 
uint64_t GetFrameCount () const
 Return the number of frames captured. More...
 
uint64_t GetLastTimestamp () const
 Get timestamp of the last captured frame, in nanoseconds. More...
 
imageFormat GetRawFormat () const
 Get raw image format. More...
 
const URIGetResource () const
 Return the resource URI of the stream. More...
 
const videoOptionsGetOptions () const
 Return the videoOptions of the stream. More...
 
bool IsType (uint32_t type) const
 Check if this stream is of a particular type. More...
 
template<typename T >
bool IsType () const
 Check if a this stream is of a particular type. More...
 
const char * TypeToStr () const
 Convert this stream's class type to string. More...
 

Static Public Member Functions

static gstCameraCreate (const videoOptions &options)
 Create a MIPI CSI or V4L2 camera device. More...
 
static gstCameraCreate (const char *camera=NULL)
 Create a MIPI CSI or V4L2 camera device. More...
 
static gstCameraCreate (uint32_t width, uint32_t height, const char *camera=NULL)
 Create a MIPI CSI or V4L2 camera device. More...
 
- Static Public Member Functions inherited from videoSource
static videoSourceCreate (const videoOptions &options)
 Create videoSource interface from a videoOptions struct that's already been filled out. More...
 
static videoSourceCreate (const char *URI, const videoOptions &options=videoOptions())
 Create videoSource interface from a resource URI string and optional videoOptions. More...
 
static videoSourceCreate (const char *URI, const commandLine &cmdLine)
 Create videoSource interface from a resource URI string and parsing command line arguments. More...
 
static videoSourceCreate (const char *URI, const int argc, char **argv)
 Create videoSource interface from a resource URI string and parsing command line arguments. More...
 
static videoSourceCreate (const int argc, char **argv, int positionArg=-1)
 Create videoSource interface by parsing command line arguments, including the resource URI. More...
 
static videoSourceCreate (const commandLine &cmdLine, int positionArg=-1)
 Create videoSource interface by parsing command line arguments, including the resource URI. More...
 
static const char * Usage ()
 Usage string for command line arguments to Create() More...
 
static const char * TypeToStr (uint32_t type)
 Convert a class type to a string. More...
 

Static Public Attributes

static const uint32_t Type = (1 << 0)
 Unique type identifier of gstCamera class. More...
 
static const uint32_t DefaultWidth = 1280
 Default camera width, unless otherwise specified during Create() More...
 
static const uint32_t DefaultHeight = 720
 Default camera height, unless otherwise specified during Create() More...
 
- Static Public Attributes inherited from videoSource
static const uint64_t DEFAULT_TIMEOUT =1000
 The default Capture timeout (1000ms) More...
 

Additional Inherited Members

- Public Types inherited from videoSource
enum  Status { ERROR = -2, EOS = -1, TIMEOUT = 0, OK = 1 }
 Stream status codes that are optionally returned from Capture() More...
 
- Protected Member Functions inherited from videoSource
 videoSource (const videoOptions &options)
 
- Protected Attributes inherited from videoSource
bool mStreaming
 
videoOptions mOptions
 
uint64_t mLastTimestamp
 
imageFormat mRawFormat
 

Constructor & Destructor Documentation

◆ ~gstCamera()

gstCamera::~gstCamera ( )

Release the camera interface and resources.

Destroying the camera will also Close() the stream if it is still open.

Member Function Documentation

◆ Capture()

virtual bool gstCamera::Capture ( void **  image,
imageFormat  format,
uint64_t  timeout = DEFAULT_TIMEOUT,
int *  status = NULL 
)
virtual

Capture the next image frame from the camera.

See also
videoSource::Capture

Implements videoSource.

◆ CaptureRGBA()

bool gstCamera::CaptureRGBA ( float **  image,
uint64_t  timeout = DEFAULT_TIMEOUT,
bool  zeroCopy = false 
)

Capture the next image frame from the camera and convert it to float4 RGBA format, with pixel intensities ranging between 0.0 and 255.0.

Deprecated:
CaptureRGBA() has been deprecated and is only provided for legacy compatibility. Please use the updated Capture() function instead.

Internally, CaptureRGBA() first calls Capture() and then ConvertRGBA(). The ConvertRGBA() function uses CUDA, so if you want to capture from a different thread than your CUDA device, use the Capture() and ConvertRGBA() functions.

Parameters
[out]imagePointer that gets returned to the image in GPU address space, or if the zeroCopy parameter is true, then the pointer is valid in both CPU and GPU address spaces. Do not manually free the image memory, it is managed internally. The image is in float4 RGBA format. The size of the image is: GetWidth() * GetHeight() * sizeof(float) * 4
[in]timeoutThe time in milliseconds for the calling thread to wait to return if a new camera frame isn't recieved by that time. If timeout is 0, the calling thread will return immediately if a new frame isn't already available. If timeout is UINT64_MAX, the calling thread will wait indefinetly for a new frame to arrive.
[in]zeroCopyIf true, the image will reside in shared CPU/GPU memory. If false, the image will only be accessible from the GPU. You would need to set zeroCopy to true if you wanted to access the image pixels from the CPU. Since this isn't generally the case, the default is false (GPU only).
Returns
true if a frame was successfully captured, otherwise false if a timeout or error occurred, or if timeout was 0 and a frame wasn't ready.

◆ Close()

virtual void gstCamera::Close ( )
virtual

Stop streaming the camera.

Note
Close() is automatically called by the camera's destructor when it gets deleted, so you do not explicitly need to call Close() before exiting the program if you delete your camera object.

Reimplemented from videoSource.

◆ Create() [1/3]

static gstCamera* gstCamera::Create ( const char *  camera = NULL)
static

Create a MIPI CSI or V4L2 camera device.

gstCamera will use the nvarguscamerasrc GStreamer element for MIPI CSI cameras, and the v4l2src GStreamer element for capturing V4L2 cameras, like USB webcams.

The camera will be created with a resolution indicated by gstCamera::DefaultWidth and gstCamera::DefaultHeight (1280x720 by default).

Parameters
cameraCamera device to use. If using MIPI CSI, this string can be NULL to default to CSI camera 0, otherwise the string should contain the device index of the CSI camera (e.g. "0" for CSI camera 0 or "1" for CSI camera 1, ect). If using V4L2, the string should contain the /dev/video node to use (e.g. "/dev/video0" for V4L2 camera 0). By default, camera parameter is NULL and MIPI CSI camera 0 is used.
Returns
A pointer to the created gstCamera device, or NULL if there was an error.

◆ Create() [2/3]

static gstCamera* gstCamera::Create ( const videoOptions options)
static

Create a MIPI CSI or V4L2 camera device.

◆ Create() [3/3]

static gstCamera* gstCamera::Create ( uint32_t  width,
uint32_t  height,
const char *  camera = NULL 
)
static

Create a MIPI CSI or V4L2 camera device.

gstCamera will use the nvarguscamerasrc GStreamer element for MIPI CSI cameras, and the v4l2src GStreamer element for capturing V4L2 cameras, like USB webcams.

Parameters
widthdesired width (in pixels) of the camera resolution.
This should be from a format that the camera supports.
heightdesired height (in pixels) of the camera resolution.
This should be from a format that the camera supports.
cameraCamera device to use. If using MIPI CSI, this string can be NULL to default to CSI camera 0, otherwise the string should contain the device index of the CSI camera (e.g. "0" for CSI camera 0 or "1" for CSI camera 1, ect). If using V4L2, the string should contain the /dev/video node to use (e.g. "/dev/video0" for V4L2 camera 0). By default, camera parameter is NULL and MIPI CSI camera 0 is used.
Returns
A pointer to the created gstCamera device, or NULL if there was an error.

◆ GetType()

virtual uint32_t gstCamera::GetType ( ) const
inlinevirtual

Return the interface type (gstCamera::Type)

Reimplemented from videoSource.

◆ Open()

virtual bool gstCamera::Open ( )
virtual

Begin streaming the camera.

After Open() is called, frames from the camera will begin to be captured.

Open() is not stricly necessary to call, if you call one of the Capture() functions they will first check to make sure that the stream is opened, and if not they will open it automatically for you.

Returns
true on success, false if an error occurred opening the stream.

Reimplemented from videoSource.

◆ SetZeroCopy()

void gstCamera::SetZeroCopy ( bool  zeroCopy)
inline

Set whether converted RGB(A) images should use ZeroCopy buffer allocation.

Has no effect after the first image (in RGB(A) format) was captured.

Member Data Documentation

◆ DefaultHeight

const uint32_t gstCamera::DefaultHeight = 720
static

Default camera height, unless otherwise specified during Create()

◆ DefaultWidth

const uint32_t gstCamera::DefaultWidth = 1280
static

Default camera width, unless otherwise specified during Create()

◆ Type

const uint32_t gstCamera::Type = (1 << 0)
static

Unique type identifier of gstCamera class.

◆ v4l2Camera

class v4l2Camera

Video4Linux2 (V4L2) camera capture streaming.

Note
gstCamera, which convieniently handles both V4L2 and MIPI CSI cameras, is used mostly in lieu of v4l2Camera. v4l2Camera is provided in the event that you would rather interface with V4L2 directly, rather than go through GStreamer.

Public Member Functions

 ~v4l2Camera ()
 Destructor. More...
 
bool Open ()
 Start streaming. More...
 
bool Close ()
 Stop streaming. More...
 
void * Capture (size_t timeout=0)
 Return the next image. More...
 
uint32_t GetWidth () const
 Get width, in pixels, of camera image. More...
 
uint32_t GetHeight () const
 Retrieve height, in pixels, of camera image. More...
 
uint32_t GetPitch () const
 Return the size in bytes of one line of the image. More...
 
uint32_t GetPixelDepth () const
 Return the bit depth per pixel. More...
 

Static Public Member Functions

static v4l2CameraCreate (const char *device_path)
 Create V4L2 interface. More...
 

Constructor & Destructor Documentation

◆ ~v4l2Camera()

v4l2Camera::~v4l2Camera ( )

Destructor.

Member Function Documentation

◆ Capture()

void* v4l2Camera::Capture ( size_t  timeout = 0)

Return the next image.

◆ Close()

bool v4l2Camera::Close ( )

Stop streaming.

◆ Create()

static v4l2Camera* v4l2Camera::Create ( const char *  device_path)
static

Create V4L2 interface.

Parameters
pathFilename of the video device (e.g. /dev/video0)

◆ GetHeight()

uint32_t v4l2Camera::GetHeight ( ) const
inline

Retrieve height, in pixels, of camera image.

◆ GetPitch()

uint32_t v4l2Camera::GetPitch ( ) const
inline

Return the size in bytes of one line of the image.

◆ GetPixelDepth()

uint32_t v4l2Camera::GetPixelDepth ( ) const
inline

Return the bit depth per pixel.

◆ GetWidth()

uint32_t v4l2Camera::GetWidth ( ) const
inline

Get width, in pixels, of camera image.

◆ Open()

bool v4l2Camera::Open ( )

Start streaming.