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

#include <gstCamera.h>

Public Member Functions
	~gstCamera ()
	Release the camera interface and resources. More...

bool	Open ()
	Begin streaming the camera. More...

void	Close ()
	Stop streaming the camera. More...

bool	IsStreaming () const
	Check if the camera is streaming or not. More...

bool	Capture (void cpu, void cuda, uint64_t timeout=UINT64_MAX)
	Capture the next image frame from the camera. More...

bool	CaptureRGBA (float **image, uint64_t timeout=UINT64_MAX, 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...

bool	ConvertRGBA (void input, float *output, bool zeroCopy=false)
	Convert an image to float4 RGBA that was previously aquired with Capture(). More...

uint32_t	GetWidth () const
	Return the width of the camera. More...

uint32_t	GetHeight () const
	Return the height of the camera. More...

uint32_t	GetPixelDepth () const
	Return the pixel bit depth of the camera (measured in bits). More...

uint32_t	GetSize () const
	Return the size (in bytes) of a camera frame from Capture(). More...

Static Public Member Functions
static gstCamera *	Create (const char *camera=NULL)
	Create a MIPI CSI or V4L2 camera device. More...

static gstCamera *	Create (uint32_t width, uint32_t height, const char *camera=NULL)
	Create a MIPI CSI or V4L2 camera device. More...

Static Public Attributes
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...

Detailed Description

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.

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()

bool gstCamera::Capture	(	void **	cpu,
		void **	cuda,
		uint64_t	timeout = `UINT64_MAX`
	)

Capture the next image frame from the camera.

For MIPI CSI cameras, Capture() will provide an image in YUV (NV12) format. For V4L2 devices, Capture() will provide an image in RGB (24-bit) format.

The captured images reside in shared CPU/GPU memory, also known as CUDA mapped memory or zero-copy memory. Hence it is unnessary to copy them to GPU. This memory is managed internally by gstCamera, so don't attempt to free it.

Parameters

[out]	cpu	Pointer that gets returned to the image in CPU address space.
[out]	cuda	Pointer that gets returned to the image in GPU address space.
[in]	timeout	The 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 (this is the default behavior).

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.

◆ CaptureRGBA()

bool gstCamera::CaptureRGBA	(	float **	image,
		uint64_t	timeout = `UINT64_MAX`,
		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.

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]	image	Pointer 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]	timeout	The 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 (this is the default behavior).
[in]	zeroCopy	If `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()

void gstCamera::Close ( )

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.

◆ ConvertRGBA()

bool gstCamera::ConvertRGBA	(	void *	input,
		float **	output,
		bool	zeroCopy = `false`
	)

Convert an image to float4 RGBA that was previously aquired with Capture().

This function uses CUDA to perform the colorspace conversion to float4 RGBA, with pixel intensities ranging from 0.0 to 255.0.

Parameters

[in]	input	Pointer to the input image, typically the pointer from Capture(). If this is a MIPI CSI camera, it's expected to be in YUV (NV12) format. If this is a V4L2 device, it's expected to be in RGB (24-bit) format. In both cases, these are the formats that Capture() provides the image in.
[out]	output	Pointer 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]	zeroCopy	If `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 on success, false if an error occurred.

◆ Create() [1/2]

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

camera Camera 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/2]

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

width	desired width (in pixels) of the camera resolution. This should be from a format that the camera supports.
height	desired height (in pixels) of the camera resolution. This should be from a format that the camera supports.
camera	Camera 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.

◆ GetHeight()

uint32_t gstCamera::GetHeight ( ) const

inline

Return the height of the camera.

◆ GetPixelDepth()

uint32_t gstCamera::GetPixelDepth ( ) const

inline

Return the pixel bit depth of the camera (measured in bits).

This will be 12 for MIPI CSI cameras (YUV NV12 format) or 24 for VL42 cameras (RGB 24-bit).

◆ GetSize()

uint32_t gstCamera::GetSize ( ) const

inline

Return the size (in bytes) of a camera frame from Capture().

Note: this is not the size of the converted float4 RGBA image from Convert(), but rather the YUV (NV12) or RGB (24-bit) image that gets aquired by the Capture() function. To calculate the size of the converted float4 RGBA image, take: GetWidth() * GetHeight() * sizeof(float) * 4

◆ GetWidth()

uint32_t gstCamera::GetWidth ( ) const

inline

Return the width of the camera.

◆ IsStreaming()

bool gstCamera::IsStreaming ( ) const

inline

Check if the camera is streaming or not.

Returns: true if the camera is streaming (open), or false if it's closed.

◆ Open()

bool gstCamera::Open ( )

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.

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()

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

jetson-utils/gstCamera.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~gstCamera()

Member Function Documentation

◆ Capture()

◆ CaptureRGBA()

◆ Close()

◆ ConvertRGBA()

◆ Create() [1/2]

◆ Create() [2/2]

◆ GetHeight()

◆ GetPixelDepth()

◆ GetSize()

◆ GetWidth()

◆ IsStreaming()

◆ Open()

Member Data Documentation

◆ DefaultHeight

◆ DefaultWidth