VPI - Vision Programming Interface

2.0 Release - Developer Preview

Background Subtractor

Separate foreground and background from video. More...

Data Structures

struct  VPIBackgroundSubtractorParams
 Structure that defines the parameters for vpiCreateBackgroundSubtractor. More...
 

Functions

VPIStatus vpiInitBackgroundSubtractorParams (VPIBackgroundSubtractorParams *params)
 Initializes VPIBackgroundSubtractorParams with default values. More...
 
VPIStatus vpiCreateBackgroundSubtractor (uint64_t backends, int32_t imageWidth, int32_t imageHeight, VPIImageFormat inputFormat, VPIPayload *payload)
 Creates payload for vpiSubmitBackgroundSubtractor. More...
 
VPIStatus vpiSubmitBackgroundSubtractor (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage inFrame, VPIImage outFGMask, VPIImage outBGImage, const VPIBackgroundSubtractorParams *params)
 Submits a Background Subtractor operation to the stream. More...
 

Detailed Description

Separate foreground and background from video.

Refer to Background Subtractor for more details and usage examples.


Data Structure Documentation

◆ VPIBackgroundSubtractorParams

struct VPIBackgroundSubtractorParams

Structure that defines the parameters for vpiCreateBackgroundSubtractor.

Definition at line 82 of file BackgroundSubtractor.h.

+ Collaboration diagram for VPIBackgroundSubtractorParams:
Data Fields
uint8_t detectShadow The algorithm will detect shadows and mark them if this is set to non-zero value.
float learningRate Learning rate that indicates how fast the background model is learnt.
  • This value must be between 0 and 1.
    • Minimum of 0 means that the background model is not updated at all
    • Maximum of 1 means that the background model is completely reinitialized from the last frame.
uint8_t shadowPixelValue Pixel value representing shadow.
float varThreshold Threshold on the squared Mahalanobis distance between the pixel and the model to decide whether a pixel is well described by the background model.

This parameter does not affect the background update.

Function Documentation

◆ vpiCreateBackgroundSubtractor()

VPIStatus vpiCreateBackgroundSubtractor ( uint64_t  backends,
int32_t  imageWidth,
int32_t  imageHeight,
VPIImageFormat  inputFormat,
VPIPayload payload 
)

#include <vpi/algo/BackgroundSubtractor.h>

Creates payload for vpiSubmitBackgroundSubtractor.

Parameters
[in]backendsVPI backend that will execute the algorithm.
[in]imageWidth,imageHeightInput image dimensions.
  • Must be > 0.
[in]inputFormatInput image format.
[out]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENTimageWidth or imageHeight outside valid range.
VPI_ERROR_INVALID_ARGUMENTbackend refers to an invalid backend.
VPI_IMAGE_FORMAT_INVALIDinputFormat is not supported.
VPI_ERROR_NOT_IMPLEMENTEDBackground Subtractor algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context was destroyed.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_SUCCESSOperation executed successfully.

◆ vpiInitBackgroundSubtractorParams()

VPIStatus vpiInitBackgroundSubtractorParams ( VPIBackgroundSubtractorParams params)

#include <vpi/algo/BackgroundSubtractor.h>

Initializes VPIBackgroundSubtractorParams with default values.

Defaults:

  • varThreshold: 16
  • detectShadow: 1
  • shadowPixelValue: 127
  • learningRate: 0.001
Parameters
[out]paramsStructure to be filled with default values.
Return values
VPI_ERROR_INVALID_ARGUMENTparams is NULL
VPI_SUCCESSOperation executed successfully.

◆ vpiSubmitBackgroundSubtractor()

VPIStatus vpiSubmitBackgroundSubtractor ( VPIStream  stream,
uint64_t  backend,
VPIPayload  payload,
VPIImage  inFrame,
VPIImage  outFGMask,
VPIImage  outBGImage,
const VPIBackgroundSubtractorParams params 
)

#include <vpi/algo/BackgroundSubtractor.h>

Submits a Background Subtractor operation to the stream.

Runs background subtractor on the incoming image from the video and outputs an estimate of the foreground mask.

Parameters
[in]streamThe stream where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
  • Must be the backend specified during payload creation or 0 as a shorthand to use this backend.
[in]payloadPayload to be submitted along the other parameters.
[in]inFrameIncoming frame from the video.
  • Must not be NULL.
  • Must have same dimensions as the one specified during payload creation.
  • Image must have enabled the backends that will execute the algorithm.
[out]outFGMaskThe output foreground mask as an 8-bit binary image.
  • Must not be NULL.
  • Must have same dimensions as input image.
  • The only accepted format is VPI_IMAGE_FORMAT_U8.
  • Image must have enabled the backends that will execute the algorithm.
[out]outBGImageBackground image. Pass NULL if not needed.
  • Must have same format and dimensions as input image.
  • Image must have enabled the backends that will execute the algorithm.
[in]paramsAlgorithm control parameters. Pass NULL to use the defaults given by vpiInitBackgroundSubtractorParams.
Return values
VPI_ERROR_INVALID_ARGUMENTstream is NULL.
VPI_ERROR_INVALID_ARGUMENTparams is NULL.
VPI_ERROR_INVALID_ARGUMENTinFrame or outFGMask are NULL.
VPI_ERROR_INVALID_ARGUMENTpayload is not created by vpiCreateBackgroundSubtractor.
VPI_ERROR_INVALID_ARGUMENTinFrame image dimension does not match the one associated with payload.
VPI_ERROR_INVALID_ARGUMENToutFGMask dimension does not match the one associated with payload.
VPI_ERROR_INVALID_ARGUMENTLearning rate in params outside valid range.
VPI_ERROR_INVALID_IMAGE_FORMATinFrame image format does not match the one associated with payload.
VPI_ERROR_INVALID_IMAGE_FORMAToutFGMask format not supported.
VPI_ERROR_INVALID_IMAGE_FORMAToutBGImage format does not match the one associated with payload.
VPI_ERROR_INVALID_ARGUMENTpayload is invalid.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream, inFrame, outFGMask or outBGImage.
VPI_SUCCESSOperation executed successfully.