A class to create compressed video stream from images captured or loaded using the Impact Acquire API. More...

Inheritance diagram for VideoStream:

Public Member Functions
	__init__ (self, *args)
	Creates a new video stream file.

	getCodec (self)
	Returns the codec used by this video stream.

	getCodecAsString (self, *args)
	Returns the a string representation for a video codec.

	getFileName (self)
	Returns the file name of this video stream.

	isPaused (self)
	Checks is this video stream is currently paused.

	pause (self)
	Pauses this video stream.

	resume (self)
	Resumes this video stream.

	saveImage (self, *args)
	Stores an image into the video stream.

Static Public Member Functions
	isAPIAvailable ()
	Checks if the video stream API is available.

Properties
	thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")

Detailed Description

A class to create compressed video stream from images captured or loaded using the Impact Acquire API.

This class heavily depends on the FFmpeg project (see FFmpeg). Without the libraries belonging to this project being present on the target system video streams cannot be created.

Because of what is stated in the above section Impact Acquire is NOT shipped with the FFmpeg binaries required to use this class!

On Windows the FFmpeg-share package matching the platform the application shall run with (32- or 64-bit) is needed. This can either be extracted into the installation folder of Impact Acquire e.g. into $(MVIMPACT_ACQUIRE_DIR)/Toolkits/ffmpeg-4.2.2-win64-shared or $(MVIMPACT_ACQUIRE_DIR)/Toolkits/ffmpeg-4.2.2-win32-shared (Works only for this versions) OR at the location pointed to by MVIMPACT_ACQUIRE_FFMPEG_DIR (see below) OR anywhere into the systems search path.

On Linux the package ffmpeg must be installed and if e.g. H.264 support is needed the libavcodec-extra package as well.

Attention: Please carefully read and understand the legal implications coming with the use of FFmpeg in a commercial product: http://ffmpeg.org/legal.html

Impact Acquire is capable of communicating with FFmpeg 4.x right now. This means that the following libraries will be recognized:

libavcodec-58, libavformat-58 and libavutil-56 (FFmpeg 4.0 was released on 20.04.2018)

In order to load the FFmpeg libraries from a custom location the environment variable MVIMPACT_ACQUIRE_FFMPEG_DIR can be defined before creating the first mvIMPACT.acquire.labs.VideoStream instance after loading the mvDeviceManager library into the current processes address space. Without this environment variable only the systems default search path will be used to locate it and (Windows only) the Toolkits folder of the installation directory. This is how the search algorithm will operate:

if isEnvironmentVariableDefined( MVIMPACT_ACQUIRE_FFMPEG_DIR )
  if tryToLoadFFmpegVersion4Succeeded
    return
  if tryToLoadFFmpegVersion3Succeeded
    return
if isWindowsSystem
  if tryToLoadFFmpegVersionFromToolkits4Succeeded
    return
if tryToLoadFFmpegVersion4Succeeded
  return
if tryToLoadFFmpegVersion3Succeeded
  return
ReportError

Note: Currently video streams can only be created for a limited number of pixel formats. Which codec supports which input formats is described at the corresponding mvIMPACT.acquire.TVideoCodec value. Make sure to use one of these formats either by setting up your device accordingly or by using the mvIMPACT.acquire.ImageDestination.pixelFormat property of the Image Format Conversion Filter.

Attention

You have to feed one of the supported pixel formats depending on the video codecs requirements into the stream! The video stream API will NOT perform internal conversion. If you need to convert (most likely you will be!) use the Image Format Conversion Filter to achieve that. It will get the job done!
When not providing timestamps together with the images that are fed into the encoder the resulting video stream can still be used, but the playback speed will differ from the acquisition speed then. When providing the timestamps coming with the requests the playback speed will resemble exactly the acquisition speed. Most codecs even support variable playback speeds so dynamic changes in the frame rate will be reflected during playback.

Since: 2.39.0

Constructor & Destructor Documentation

◆ init()

__init__	(		self,
		*	args )

Creates a new video stream file.

OVERLOAD 1:

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented
pBuffer	[in] An image buffer containing the layout of the images that are about to get stored in the stream. This structure can be extracted from a real mvIMPACT.acquire.Request object captured previously but NOT by calling the mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout function after setting up the device completely.The latter one will not contain all the information needed for a successful stream creation. You could even create a stream from a list of files e.g. on a hard-disk using the mvIMPACT.acquire.ImageBufferDesc constructor accepting a file name. If you want to use the mvIMPACT.acquire.Request object obtained from a call to mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout use the constructor accepting a mvIMPACT.acquire.Request pointer!
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 2: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented
imageWidth	[in] The input image width in pixels
imageHeight	[in] The input image height in pixels
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 3: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented
imageWidth	[in] The input image width in pixels
imageHeight	[in] The input image height in pixels
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 4: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented
imageWidth	[in] The input image width in pixels
imageHeight	[in] The input image height in pixels
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 5: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented
imageWidth	[in] The input image width in pixels
imageHeight	[in] The input image height in pixels
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 6: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented.
pRequest	[in] A mvIMPACT.acquire.Request object carrying the image related information that are about to get stored in the stream. This can either be extracted from a real mvIMPACT.acquire.Request object captured previously or by calling the mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout function after setting up the device completely. To create a stream from a list of files e.g. on a hard-disk use the mvIMPACT.acquire.labs.VideoStream constructor accepting a mvIMPACT.acquire.ImageBufferDesc instead! Create instances of b mvIMPACT.acquire.ImageBufferDesc objects from files call the mvIMPACT.acquire.ImageBufferDesc constructor accepting a file name.
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 7: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented.
pRequest	[in] A mvIMPACT.acquire.Request object carrying the image related information that are about to get stored in the stream. This can either be extracted from a real mvIMPACT.acquire.Request object captured previously or by calling the mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout function after setting up the device completely. To create a stream from a list of files e.g. on a hard-disk use the mvIMPACT.acquire.labs.VideoStream constructor accepting a mvIMPACT.acquire.ImageBufferDesc instead! Create instances of b mvIMPACT.acquire.ImageBufferDesc objects from files call the mvIMPACT.acquire.ImageBufferDesc constructor accepting a file name.
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 8: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented.
pRequest	[in] A mvIMPACT.acquire.Request object carrying the image related information that are about to get stored in the stream. This can either be extracted from a real mvIMPACT.acquire.Request object captured previously or by calling the mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout function after setting up the device completely. To create a stream from a list of files e.g. on a hard-disk use the mvIMPACT.acquire.labs.VideoStream constructor accepting a mvIMPACT.acquire.ImageBufferDesc instead! Create instances of b mvIMPACT.acquire.ImageBufferDesc objects from files call the mvIMPACT.acquire.ImageBufferDesc constructor accepting a file name.
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

OVERLOAD 9: Creates a new video stream file.

Note: Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.

Parameters

fileName	[in] The name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT.acquire.TVideoCodec enumeration is documented.
pRequest	[in] A mvIMPACT.acquire.Request object carrying the image related information that are about to get stored in the stream. This can either be extracted from a real mvIMPACT.acquire.Request object captured previously or by calling the mvIMPACT.acquire.FunctionInterface.getCurrentCaptureBufferLayout function after setting up the device completely. To create a stream from a list of files e.g. on a hard-disk use the mvIMPACT.acquire.labs.VideoStream constructor accepting a mvIMPACT.acquire.ImageBufferDesc instead! Create instances of b mvIMPACT.acquire.ImageBufferDesc objects from files call the mvIMPACT.acquire.ImageBufferDesc constructor accepting a file name.
codec	[in] The codec that shall be used while encoding the images into the stream.
quality_pc	[in] The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcH264, mvIMPACT.acquire.vcH265.
bitrate	[in] The bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT.acquire.vcMPEG2.

Member Function Documentation

◆ getCodec()

getCodec ( self )

Returns the codec used by this video stream.

This function returns the codec used by this video stream.

Since: 2.39.0

Returns: The codec used by this video stream.

◆ getCodecAsString()

getCodecAsString	(		self,
		*	args )

Returns the a string representation for a video codec.

OVERLOAD 1:

This function returns a string representation for a video codec.

Since: 2.39.0

Returns: A string representation for a video codec.

OVERLOAD 2: Returns the codec used by this video stream as a string.

This function returns the codec used by this video stream as a string.

Since: 2.39.0

Returns: The codec used by this video stream as a string.

◆ getFileName()

getFileName ( self )

Returns the file name of this video stream.

This function returns the file name of this video stream.

Since: 2.39.0

Returns: The file name of this video stream.

◆ isAPIAvailable()

isAPIAvailable ( )

static

Checks if the video stream API is available.

This function checks if the video stream API is available.

Since: 2.39.0

Returns

true if the video stream API is available thus video streams can be created
false otherwise.

◆ isPaused()

isPaused ( self )

Checks is this video stream is currently paused.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT.acquire.labs.VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since: 2.41.0

See also: mvIMPACT.acquire.labs.VideoStream.pause,
mvIMPACT.acquire.labs.VideoStream.resume

Returns

true if this video stream is currently paused.
false otherwise.

◆ pause()

pause ( self )

Pauses this video stream.

This function pauses this video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT.acquire.labs.VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since: 2.41.0

See also: mvIMPACT.acquire.labs.VideoStream.resume,
mvIMPACT.acquire.labs.VideoStream.isPaused

Returns

mvIMPACT.acquire.DMR_NO_ERROR if successful.
mvIMPACT.acquire.DMR_BUSY if this stream has been paused already.
A negative error code of type .TDMR_ERROR otherwise.

◆ resume()

resume ( self )

Resumes this video stream.

This function resumes this previously paused video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT.acquire.labs.VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since: 2.41.0

See also: mvIMPACT.acquire.labs.VideoStream.pause,
mvIMPACT.acquire.labs.VideoStream.isPaused

Returns

mvIMPACT.acquire.DMR_NO_ERROR if successful.
mvIMPACT.acquire.DMR_EXECUTION_PROHIBITED if this stream has been paused already.
A negative error code of type .TDMR_ERROR otherwise.

◆ saveImage()

saveImage	(		self,
		*	args )

Stores an image into the video stream.

OVERLOAD 1:

This function stores an image into the video stream.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT.acquire.labs.VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since: 2.39.0

Returns

mvIMPACT.acquire.DMR_NO_ERROR if successful.
mvIMPACT.acquire.DMR_LIBRARY_NOT_FOUND if no compatible version of the FFmpeg libraries could be located on the host system.
mvIMPACT.acquire.DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
mvIMPACT.acquire.DEV_INPUT_PARAM_INVALID e.g. if a pixel format has been passed to the function that is not supported by the FFmpeg libraries.
A negative error code of type .TDMR_ERROR otherwise.

Parameters

pBuffer	[in] The image to encode and store.
timestamp_us	[in] A timestamp(in us) to associate this image with. This can be 0 if no timestamp is available.

OVERLOAD 2: Encodes and stores the image associated with the mvIMPACT.acquire.Request object into the stream.

This function stores the image associated with an mvIMPACT.acquire.Request object into the video stream.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT.acquire.labs.VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since: 2.39.0

See also: mvIMPACT.acquire.labs.VideoStream.pause,
mvIMPACT.acquire.labs.VideoStream.isPaused,
mvIMPACT.acquire.labs.VideoStream.resume

Returns

mvIMPACT.acquire.DMR_NO_ERROR if successful.
mvIMPACT.acquire.DMR_LIBRARY_NOT_FOUND if no compatible version of the FFmpeg libraries could be located on the host system.
mvIMPACT.acquire.DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
mvIMPACT.acquire.DEV_INPUT_PARAM_INVALID e.g. if a pixel format has been passed to the function that is not supported by the FFmpeg libraries.
A negative error code of type .TDMR_ERROR otherwise.

Parameters

pDev	[in] A pointer to a mvIMPACT.acquire.Device object obtained from a mvIMPACT.acquire.DeviceManager object.
pRequest	[in] A pointer to the mvIMPACT.acquire.Request object carrying the image to encode and store.

Property Documentation

◆ thisown

thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")

static

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ getCodec()

◆ getCodecAsString()

◆ getFileName()

◆ isAPIAvailable()

◆ isPaused()

◆ pause()

◆ resume()

◆ saveImage()

Property Documentation

◆ thisown

◆ init()