BackgroundSubtractor#

Functions#

NVCVStatus pvaBackgroundSubtractorCreate(NVCVOperatorHandle *handle, NVCVImageRequirements *imageRequirements, NVCVImageRequirements *maskRequirements, PVAGMMDataType gmmDataType)

Constructs an instance of the BackgroundSubtractor operator.

NVCVStatus pvaBackgroundSubtractorSubmit(NVCVOperatorHandle handle, cupvaStream_t stream, NVCVImageHandle in, NVCVImageHandle outMask, NVCVImageHandle outBackgroundImage, float learningRate, float varThreshold, bool enableShadowDetection, uint8_t shadowPixelValue)

Executes the background subtraction operation.

Functions#

NVCVStatus pvaBackgroundSubtractorCreate(
NVCVOperatorHandle *handle,
NVCVImageRequirements *imageRequirements,
NVCVImageRequirements *maskRequirements,
PVAGMMDataType gmmDataType,
)#

Constructs an instance of the BackgroundSubtractor operator.

Limitations: Input image and output background image should be of U8 type. This includes the following formats: NVCV_IMAGE_FORMAT_U8, NVCV_IMAGE_FORMAT_Y8 or NVCV_IMAGE_FORMAT_Y8_ER.

Input: Input is an image in U8 format.

Outputs: There are two outputs:

  • Output mask in U8 format. When shadow detection is disabled, output is binary with 0 indicating background and 255 indicating foreground. When shadow detection is enabled, output is a mask with 0 indicating background, shadowPixelValue indicating shadow, and 255 indicating foreground.

  • Optional output background image in the same format as the input image.

Input/Output Dependency:

Property

Input == Output

Data Layout

Yes

Data Type

Yes

Channels

Yes

Width

Yes

Height

Yes

Parameters

Parameters:

  • handle – [out] Where the operator instance handle will be written to.

    • Must not be NULL.

  • imageRequirements – [in] Pointer to the NVCVImageRequirements structure which contains image shape, and format information. This format will be applicable for both the input image and the output background image. This can be NVCV_IMAGE_FORMAT_U8, NVCV_IMAGE_FORMAT_Y8 or NVCV_IMAGE_FORMAT_Y8_ER.

  • maskRequirements – [in] Pointer to the background mask output NVCVImageRequirements structure.

  • gmmDataType – [in] The data type used for the GMM model parameters (mean, variance, weights).

    • GMM_DATA_TYPE_FP32: Use 32-bit floating point for GMM parameters

    • GMM_DATA_TYPE_FP16: Use 16-bit floating point for GMM parameters GMM_DATA_TYPE_FP32 yields higher background modeling accuracy but results in longer execution time.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Handle is null.

  • NVCV_ERROR_OUT_OF_MEMORY – Not enough memory to create the operator.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus pvaBackgroundSubtractorSubmit(
NVCVOperatorHandle handle,
cupvaStream_t stream,
NVCVImageHandle in,
NVCVImageHandle outMask,
NVCVImageHandle outBackgroundImage,
float learningRate,
float varThreshold,
bool enableShadowDetection,
uint8_t shadowPixelValue,
)#

Executes the background subtraction operation.

Determining if a pixel is background happens as follows. We go over each model in decreasing order of weight while checking the following 2 conditions:

  1. Pixel must be close to the current model using the following criterion: (pixel - model.mean)^2 < varThreshold * model.variance

  2. Total weight of all preceeding models should be lower than 0.9.

When enabled, the algorithm will attempt to identify pixels that are darker versions of the background (shadows) and mark them with shadowPixelValue instead of classifying them as foreground.

Only relevant when detectShadow is enabled (set to true). Setting this to 0 while detectShadow is enabled effectively disables shadow detection, as shadow pixels will be indistinguishable from background.

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

  • stream – [in] Handle to a valid CUPVA stream.

  • in – [in] Input image handle.

  • outMask – [out] Output mask handle. Every pixel is 0 or 255 or shadowPixelValue (if shadow detection is enabled). 0 indicates background, 255 indicates foreground, and shadowPixelValue indicates shadow.

  • outBackgroundImage – [out] Optional output background image handle. If background image is not required, pass NULL.

  • learningRate – [in] Learning rate that controls how fast the background model adapts to changes.

    • Range: [0.0, 1.0]

    • A value of 0.0 means the background model is static (no updates)

    • A value of 1.0 means the model is completely reinitialized from the current frame

    • Lower values result in a more stable background model that adapts slowly

    • Higher values allow the model to adapt quickly to changes but may be more sensitive to noise Setting the learning rate to 1.0 will reset the gaussian models.

  • varThreshold – [in] varThreshold determines how close a pixel must be to a model to be classified as belonging to that model, for the purpose of classifying a pixel as background. Higher values mean that pixels further from the mean will be classified as belonging to that model. Default value is 16. This parameter does not affect how the model is updated.

  • enableShadowDetection – [in] Controls whether the algorithm detects and marks shadow regions.

    • false: Shadow detection disabled

    • true: Shadow detection enabled

  • shadowPixelValue – [in] The pixel value used to mark detected shadow regions in the output mask.

    • Typically set to 127 (gray) to distinguish from:

      • Background (0, black)

      • Foreground (255, white)

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Some parameter is outside valid range.

  • NVCV_ERROR_INTERNAL – Internal error in the operator, invalid types passed in.

  • NVCV_SUCCESS – Operation executed successfully.