Jetson Inference
DNN Vision Library
videoSource Class Referenceabstract

The videoSource API is for capturing frames from video input devices such as MIPI CSI cameras, V4L2 cameras, video/images files from disk, directories containing a sequence of images, and from RTP/RTSP network video streams over UDP/IP. More...

#include <videoSource.h>

Inheritance diagram for videoSource:
gstCamera gstDecoder imageLoader

Public Types

enum  Status { ERROR = -2, EOS = -1, TIMEOUT = 0, OK = 1 }
 Stream status codes that are optionally returned from Capture() More...
 

Public Member Functions

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...
 
virtual bool Capture (void **image, imageFormat format, uint64_t timeout=DEFAULT_TIMEOUT, int *status=NULL)=0
 Capture the next image from the video stream. More...
 
virtual bool Open ()
 Begin streaming the device. More...
 
virtual void Close ()
 Stop streaming the device. 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...
 
virtual uint32_t GetType () const
 Return the interface type 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 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 uint64_t DEFAULT_TIMEOUT =1000
 The default Capture timeout (1000ms) More...
 

Protected Member Functions

 videoSource (const videoOptions &options)
 

Protected Attributes

bool mStreaming
 
videoOptions mOptions
 
uint64_t mLastTimestamp
 
imageFormat mRawFormat
 

Detailed Description

The videoSource API is for capturing frames from video input devices such as MIPI CSI cameras, V4L2 cameras, video/images files from disk, directories containing a sequence of images, and from RTP/RTSP network video streams over UDP/IP.

videoSource interfaces are implemented by gstCamera, gstDecoder, and imageLoader. The specific implementation is selected at runtime based on the type of resource URI.

videoSource supports the following protocols and resource URI's:

-  `csi://0` for MIPI CSI cameras, where `0` can be replaced with the camera port.
   It is also assumed that if a number with no protocol is specified (e.g. `"0"`),
   this means to use the MIPI CSI camera of that number (`"0"` -> `csi://0`).

- `v4l2:///dev/video0` for V4L2 cameras, where `/dev/video0` can be replaced with
   a different video device (e.g. `v4l2:///dev/video1` for V4L2 video device `1`).
   If no protocol is specified but the string begins with `/dev/video`, then it is
   assumed that the protocol is V4L2 (`/dev/video0` -> `v4l2:///dev/video0`)

- `rtp://@:1234` to recieve an RTP network stream, where `1234` is the port and `@` is shorthand
   for localhost.  `@` can also be substituted for the IP address of a multicast group.
   Note that it is important to manually specify the codec of the stream when using RTP,
   as the codec cannot be discovered from the RTP stream itself and need to be provided.
   @see videoOptions for more info about the `--input-codec` option.

- `rtsp://username:password@<remote-host>:1234` to subscribe to an RTSP network stream, where
   `<remote-host>` should be substituted for the remote host's IP address or hostname, and 
   `1234` is the port.  For example, `rtsp://192.168.1.2:5000`.  The `username` and `password` 
   are optional, and are only used for RTSP streams that require authentication.

- `file:///home/user/my_video.mp4` for disk-based videos, images, and directories of images.
   You can leave off the `file://` protocol identifier and it will be deduced from the path.
   It can be a relative or absolute path.  If a directory is specified that contains images,
   those images will be loaded in sequence (sorted alphanumerically).  The path can also
   contain wildcard characters, for example `"images/*.jpg"` - however when using wildcards
   from the command line, enclose the string in quotes otherwise the OS will pre-expand them.
   Supported video formats for loading include MKV, MP4, AVI, and FLV. Supported codecs for 
   decoding include H.264, H.265, VP8, VP9, MPEG-2, MPEG-4, and MJPEG. Supported image formats
   for loading include JPG, PNG, TGA, BMP, GIF, PSD, HDR, PIC, and PNM (PPM/PGM binary).
See also
URI for info about resource URI formats.
videoOptions for additional options and command-line arguments.

Member Enumeration Documentation

◆ Status

Stream status codes that are optionally returned from Capture()

Enumerator
ERROR 

an error occurred

EOS 

end-of-stream (EOS)

TIMEOUT 

a timeout occurred

OK 

frame capture successful

Constructor & Destructor Documentation

◆ ~videoSource()

virtual videoSource::~videoSource ( )
virtual

Destroy interface and release all resources.

◆ videoSource()

videoSource::videoSource ( const videoOptions options)
protected

Member Function Documentation

◆ Capture() [1/3]

template<typename T >
bool videoSource::Capture ( T **  image,
int *  status 
)
inline

Capture the next image from the video stream, using the default timeout of 1000ms.

The image formats supported by this templated version of Capture() include the following:

  • uchar3 (IMAGE_RGB8)
  • uchar4 (IMAGE_RGBA8)
  • float3 (IMAGE_RGB32F)
  • float4 (IMAGE_RGBA32F)

The image format will automatically be deduced from these types. If other types are used with this overload, a static compile-time error will be asserted.

Parameters
[out]imageoutput pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[out]statusoptional status code returned (
See also
videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.
Returns
true if a frame was captured, false if there was an error or a timeout occurred.

◆ Capture() [2/3]

template<typename T >
bool videoSource::Capture ( T **  image,
uint64_t  timeout = DEFAULT_TIMEOUT,
int *  status = NULL 
)
inline

Capture the next image from the video stream.

The image formats supported by this templated version of Capture() include the following:

  • uchar3 (IMAGE_RGB8)
  • uchar4 (IMAGE_RGBA8)
  • float3 (IMAGE_RGB32F)
  • float4 (IMAGE_RGBA32F)

The image format will automatically be deduced from these types. If other types are used with this overload, a static compile-time error will be asserted.

Parameters
[out]imageoutput pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[in]timeouttimeout in milliseconds to wait to capture the image before returning. The default is 1000ms. A timeout value of UINT64_MAX will wait forever. A timeout of 0 will return instantly if a frame wasn't immediately ready.
[out]statusoptional status code returned (
See also
videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.
Returns
true if a frame was captured, false if there was an error or a timeout occurred.

◆ Capture() [3/3]

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

Capture the next image from the video stream.

The image formats supported by Capture() are IMAGE_RGB8 (uchar3), IMAGE_RGBA8 (uchar4), IMAGE_RGB32F (float3), and IMAGE_RGBA32F (float4).

See also
imageFormat for more info.
Parameters
[out]imageoutput pointer that will be set to the memory containing the image. If this interface has it's videoOptions::zeroCopy flag set to true, the memory was allocated in mapped CPU/GPU memory and is be accessible from both CPU and CUDA. Otherwise, it's accessible only from CUDA.
[in]timeouttimeout in milliseconds to wait to capture the image before returning. The default is 1000ms. A timeout value of UINT64_MAX will wait forever. A timeout of 0 will return instantly if a frame wasn't immediately ready.
[out]statusoptional status code returned (
See also
videoSource::Status). -2 on ERROR, -1 on EOS, 0 on TIMEOUT, 1 on OK.
Returns
true if a frame was captured, false if there was an error or a timeout occurred.

Implemented in gstCamera, gstDecoder, and imageLoader.

◆ Close()

virtual void videoSource::Close ( )
virtual

Stop streaming the device.

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

Reimplemented in gstCamera, gstDecoder, and imageLoader.

◆ Create() [1/6]

static videoSource* videoSource::Create ( const char *  URI,
const commandLine cmdLine 
)
static

Create videoSource interface from a resource URI string and parsing command line arguments.

See also
videoOptions for valid command-line arguments to be parsed.
the documentation above and the URI struct for more info about resource URI's.

◆ Create() [2/6]

static videoSource* videoSource::Create ( const char *  URI,
const int  argc,
char **  argv 
)
static

Create videoSource interface from a resource URI string and parsing command line arguments.

See also
videoOptions for valid command-line arguments to be parsed.
the documentation above and the URI struct for more info about resource URI's.

◆ Create() [3/6]

static videoSource* videoSource::Create ( const char *  URI,
const videoOptions options = videoOptions() 
)
static

Create videoSource interface from a resource URI string and optional videoOptions.

See also
the documentation above and the URI struct for more info about resource URI's.

◆ Create() [4/6]

static videoSource* videoSource::Create ( const commandLine cmdLine,
int  positionArg = -1 
)
static

Create videoSource interface by parsing command line arguments, including the resource URI.

Parameters
positionArgindicates the positional argument number in the command line of the resource URI (or -1 if a positional argument isn't used, and should instead be parsed from the --input= option).
See also
videoOptions for valid command-line arguments to be parsed.
the documentation above and the URI struct for more info about resource URI's.

◆ Create() [5/6]

static videoSource* videoSource::Create ( const int  argc,
char **  argv,
int  positionArg = -1 
)
static

Create videoSource interface by parsing command line arguments, including the resource URI.

Parameters
positionArgindicates the positional argument number in the command line of the resource URI (or -1 if a positional argument isn't used, and should instead be parsed from the --input= option).
See also
videoOptions for valid command-line arguments to be parsed.
the documentation above and the URI struct for more info about resource URI's.

◆ Create() [6/6]

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

Create videoSource interface from a videoOptions struct that's already been filled out.

It's expected that the supplied videoOptions already contain a valid resource URI.

◆ GetFrameCount()

uint64_t videoSource::GetFrameCount ( ) const
inline

Return the number of frames captured.

◆ GetFrameRate()

uint32_t videoSource::GetFrameRate ( ) const
inline

Return the framerate, in Hz or FPS.

◆ GetHeight()

uint32_t videoSource::GetHeight ( ) const
inline

Return the height of the stream, in pixels.

◆ GetLastTimestamp()

uint64_t videoSource::GetLastTimestamp ( ) const
inline

Get timestamp of the last captured frame, in nanoseconds.

◆ GetOptions()

const videoOptions& videoSource::GetOptions ( ) const
inline

Return the videoOptions of the stream.

◆ GetRawFormat()

imageFormat videoSource::GetRawFormat ( ) const
inline

Get raw image format.

◆ GetResource()

const URI& videoSource::GetResource ( ) const
inline

Return the resource URI of the stream.

◆ GetType()

virtual uint32_t videoSource::GetType ( ) const
inlinevirtual

Return the interface type of the stream.

This could be one of the following values:

Reimplemented in gstCamera, gstDecoder, and imageLoader.

◆ GetWidth()

uint32_t videoSource::GetWidth ( ) const
inline

Return the width of the stream, in pixels.

◆ IsStreaming()

bool videoSource::IsStreaming ( ) const
inline

Check if the device is actively streaming or not.

Returns
true if the device is streaming (open), or false if it's closed or has reached EOS (End Of Stream).

◆ IsType() [1/2]

template<typename T >
bool videoSource::IsType ( ) const
inline

Check if a this stream is of a particular type.

Can be used with gstCamera, gstDecoder, and imageLoader. For example:

if( stream->IsType<gstCamera>() ) gstCamera* camera = (gstCamera*)stream; // safe to cast

◆ IsType() [2/2]

bool videoSource::IsType ( uint32_t  type) const
inline

Check if this stream is of a particular type.

See also
GetType() for possible values.

◆ Open()

virtual bool videoSource::Open ( )
virtual

Begin streaming the device.

After Open() is called, frames from the device 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 in gstCamera, gstDecoder, and imageLoader.

◆ TypeToStr() [1/2]

const char* videoSource::TypeToStr ( ) const
inline

Convert this stream's class type to string.

◆ TypeToStr() [2/2]

static const char* videoSource::TypeToStr ( uint32_t  type)
static

Convert a class type to a string.

◆ Usage()

static const char* videoSource::Usage ( )
inlinestatic

Usage string for command line arguments to Create()

Member Data Documentation

◆ DEFAULT_TIMEOUT

const uint64_t videoSource::DEFAULT_TIMEOUT =1000
static

The default Capture timeout (1000ms)

◆ mLastTimestamp

uint64_t videoSource::mLastTimestamp
protected

◆ mOptions

videoOptions videoSource::mOptions
protected

◆ mRawFormat

imageFormat videoSource::mRawFormat
protected

◆ mStreaming

bool videoSource::mStreaming
protected

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