create_bg_estiT_create_bg_estiCreateBgEstiCreateBgEsticreate_bg_esti (Operator)

Name

create_bg_estiT_create_bg_estiCreateBgEstiCreateBgEsticreate_bg_esti — Generate and initialize a data set for the background estimation.

Signature

create_bg_esti(InitializeImage : : Syspar1, Syspar2, GainMode, Gain1, Gain2, AdaptMode, MinDiff, StatNum, ConfidenceC, TimeC : BgEstiHandle)

Herror T_create_bg_esti(const Hobject InitializeImage, const Htuple Syspar1, const Htuple Syspar2, const Htuple GainMode, const Htuple Gain1, const Htuple Gain2, const Htuple AdaptMode, const Htuple MinDiff, const Htuple StatNum, const Htuple ConfidenceC, const Htuple TimeC, Htuple* BgEstiHandle)

void CreateBgEsti(const HObject& InitializeImage, const HTuple& Syspar1, const HTuple& Syspar2, const HTuple& GainMode, const HTuple& Gain1, const HTuple& Gain2, const HTuple& AdaptMode, const HTuple& MinDiff, const HTuple& StatNum, const HTuple& ConfidenceC, const HTuple& TimeC, HTuple* BgEstiHandle)

HBgEsti HImage::CreateBgEsti(double Syspar1, double Syspar2, const HString& GainMode, double Gain1, double Gain2, const HString& AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC) const

HBgEsti HImage::CreateBgEsti(double Syspar1, double Syspar2, const char* GainMode, double Gain1, double Gain2, const char* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC) const

HBgEsti HImage::CreateBgEsti(double Syspar1, double Syspar2, const wchar_t* GainMode, double Gain1, double Gain2, const wchar_t* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC) const   (Windows only)

void HBgEsti::HBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const HString& GainMode, double Gain1, double Gain2, const HString& AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)

void HBgEsti::HBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const char* GainMode, double Gain1, double Gain2, const char* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)

void HBgEsti::HBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const wchar_t* GainMode, double Gain1, double Gain2, const wchar_t* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)   (Windows only)

void HBgEsti::CreateBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const HString& GainMode, double Gain1, double Gain2, const HString& AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)

void HBgEsti::CreateBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const char* GainMode, double Gain1, double Gain2, const char* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)

void HBgEsti::CreateBgEsti(const HImage& InitializeImage, double Syspar1, double Syspar2, const wchar_t* GainMode, double Gain1, double Gain2, const wchar_t* AdaptMode, double MinDiff, Hlong StatNum, double ConfidenceC, double TimeC)   (Windows only)

static void HOperatorSet.CreateBgEsti(HObject initializeImage, HTuple syspar1, HTuple syspar2, HTuple gainMode, HTuple gain1, HTuple gain2, HTuple adaptMode, HTuple minDiff, HTuple statNum, HTuple confidenceC, HTuple timeC, out HTuple bgEstiHandle)

HBgEsti HImage.CreateBgEsti(double syspar1, double syspar2, string gainMode, double gain1, double gain2, string adaptMode, double minDiff, int statNum, double confidenceC, double timeC)

public HBgEsti(HImage initializeImage, double syspar1, double syspar2, string gainMode, double gain1, double gain2, string adaptMode, double minDiff, int statNum, double confidenceC, double timeC)

void HBgEsti.CreateBgEsti(HImage initializeImage, double syspar1, double syspar2, string gainMode, double gain1, double gain2, string adaptMode, double minDiff, int statNum, double confidenceC, double timeC)

def create_bg_esti(initialize_image: HObject, syspar_1: float, syspar_2: float, gain_mode: str, gain_1: float, gain_2: float, adapt_mode: str, min_diff: float, stat_num: int, confidence_c: float, time_c: float) -> HHandle

Description

create_bg_esticreate_bg_estiCreateBgEstiCreateBgEstiCreateBgEsticreate_bg_esti creates a new data set for the background estimation and initializes it with the appropriate parameters. The estimated background image is part of this data set. The newly created set automatically becomes the current set.

InitializeImageInitializeImageInitializeImageInitializeImageinitializeImageinitialize_image is used as an initial prediction for the background image. For a good prediction an image of the observed scene without moving objects should be passed in InitializeImageInitializeImageInitializeImageInitializeImageinitializeImageinitialize_image. That way the foreground adaptation rate can be held low. If there is no empty scene image available, a homogeneous gray image can be used instead. In that case the adaptation rate for the foreground image must be raised, because initially most of the image will be detected as foreground. The initialization image must to be of type 'byte'"byte""byte""byte""byte""byte" or 'real'"real""real""real""real""real". Because of processing single-channel images, data sets must be created for every channel. Size and region of InitializeImageInitializeImageInitializeImageInitializeImageinitializeImageinitialize_image determines size and region for all background estimations (run_bg_estirun_bg_estiRunBgEstiRunBgEstiRunBgEstirun_bg_esti) that are performed with this data set.

Syspar1Syspar1Syspar1Syspar1syspar1syspar_1 and Syspar2Syspar2Syspar2Syspar2syspar2syspar_2 are the parameters of the Kalman system matrix. The system matrix describes the system of the gray value changes according to Kalman filter theory. The background estimator implements a different system for each pixel.

GainModeGainModeGainModeGainModegainModegain_mode defines whether a fixed Kalman gain should be used for the estimation or whether the gain should adapt itself depending on the difference between estimation and actual value. If GainModeGainModeGainModeGainModegainModegain_mode is set to 'fixed'"fixed""fixed""fixed""fixed""fixed", then Gain1Gain1Gain1Gain1gain1gain_1 is used as Kalman gain for pixels predicted as foreground and Gain2Gain2Gain2Gain2gain2gain_2 as gain for pixels predicted as background. Gain1Gain1Gain1Gain1gain1gain_1 should be smaller than Gain2Gain2Gain2Gain2gain2gain_2, because adaptation of the foreground should be slower than adaptation of the background. Both Gain1Gain1Gain1Gain1gain1gain_1 and Gain2Gain2Gain2Gain2gain2gain_2 should be smaller than 1.0.

If GainModeGainModeGainModeGainModegainModegain_mode is set to 'frame'"frame""frame""frame""frame""frame", then tables for foreground and background estimation are computed containing Kalman gains for all the 256 possible gray value changes. Gain1Gain1Gain1Gain1gain1gain_1 and Gain2Gain2Gain2Gain2gain2gain_2 then denote the number of frames necessary to adapt the difference between estimated value and actual value. So with a fixed time for adaptation (i.e. number of frames) the needed Kalman gain grows with the gray value difference. Gain1Gain1Gain1Gain1gain1gain_1 should therefore be larger than Gain2Gain2Gain2Gain2gain2gain_2. Different gains for different gray value differences are useful if the background estimator is used for generating an 'empty' scene assuming that there are always moving objects in the observed area. In that case the adaptation time for foreground adaptation (Gain1Gain1Gain1Gain1gain1gain_1) must not be too big. Gain1Gain1Gain1Gain1gain1gain_1 and Gain2Gain2Gain2Gain2gain2gain_2 should be bigger than 1.0.

AdaptModeAdaptModeAdaptModeAdaptModeadaptModeadapt_mode denotes, whether the foreground/background decision threshold applied to the gray value difference between estimation and actual value is fixed or whether it adapts itself depending on the gray value deviation of the background pixels.

If AdaptModeAdaptModeAdaptModeAdaptModeadaptModeadapt_mode is set to 'off'"off""off""off""off""off", the parameter MinDiffMinDiffMinDiffMinDiffminDiffmin_diff denotes a fixed threshold. The parameters StatNumStatNumStatNumStatNumstatNumstat_num, ConfidenceCConfidenceCConfidenceCConfidenceCconfidenceCconfidence_c and TimeCTimeCTimeCTimeCtimeCtime_c are meaningless in this case.

If AdaptModeAdaptModeAdaptModeAdaptModeadaptModeadapt_mode is set to 'on'"on""on""on""on""on", then MinDiffMinDiffMinDiffMinDiffminDiffmin_diff is interpreted as a base threshold. For each pixel an offset is added to this threshold depending on the statistical evaluation of the pixel value over time. StatNumStatNumStatNumStatNumstatNumstat_num holds the number of data sets (past frames) that are used for computing the gray value variance (FIR-Filter). ConfidenceCConfidenceCConfidenceCConfidenceCconfidenceCconfidence_c is used to determine the confidence interval.

The confidence interval determines the values of the background statistics if background pixels are hidden by a foreground object and thus are detected as foreground. According to the student t-distribution the confidence constant is 4.30 (3.25, 2.82, 2.26) for a confidence interval of '99,8%'"99,8%""99,8%""99,8%""99,8%""99,8%" ('99,0%'"99,0%""99,0%""99,0%""99,0%""99,0%", '98,0%'"98,0%""98,0%""98,0%""98,0%""98,0%", '95,0%'"95,0%""95,0%""95,0%""95,0%""95,0%"). TimeCTimeCTimeCTimeCtimeCtime_c holds a time constant for the exp-function that raises the threshold in case of a foreground estimation of the pixel. That means, the threshold is raised in regions where movement is detected in the foreground. That way larger changes in illumination are tolerated if the background becomes visible again. The main reason for increasing this tolerance is the impossibility for a prediction of illumination changes while the background is hidden. Therefore no adaptation of the estimated background image is possible.

Attention

If GainModeGainModeGainModeGainModegainModegain_mode was set to 'frame'"frame""frame""frame""frame""frame", the run-time can be extremely long for large values of Gain1Gain1Gain1Gain1gain1gain_1 or Gain2Gain2Gain2Gain2gain2gain_2, because the values for the gains' table are determined by a simple binary search.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

InitializeImageInitializeImageInitializeImageInitializeImageinitializeImageinitialize_image (input_object)  singlechannelimage objectHImageHObjectHImageHobject (byte / real)

initialization image.

Syspar1Syspar1Syspar1Syspar1syspar1syspar_1 (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

1. system matrix parameter.

Default value: 0.7

Suggested values: 0.65, 0.7, 0.75

Typical range of values: 0.05 ≤ Syspar1 Syspar1 Syspar1 Syspar1 syspar1 syspar_1 ≤ 1.0

Recommended increment: 0.05

Syspar2Syspar2Syspar2Syspar2syspar2syspar_2 (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

2. system matrix parameter.

Default value: 0.7

Suggested values: 0.65, 0.7, 0.75

Typical range of values: 0.05 ≤ Syspar2 Syspar2 Syspar2 Syspar2 syspar2 syspar_2 ≤ 1.0

Recommended increment: 0.05

GainModeGainModeGainModeGainModegainModegain_mode (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Gain type.

Default value: 'fixed' "fixed" "fixed" "fixed" "fixed" "fixed"

List of values: 'fixed'"fixed""fixed""fixed""fixed""fixed", 'frame'"frame""frame""frame""frame""frame"

Gain1Gain1Gain1Gain1gain1gain_1 (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Kalman gain / foreground adaptation time.

Default value: 0.002

Suggested values: 10.0, 20.0, 50.0, 0.1, 0.05, 0.01, 0.005, 0.001

Restriction: 0.0 <= Gain1

Gain2Gain2Gain2Gain2gain2gain_2 (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Kalman gain / background adaptation time.

Default value: 0.02

Suggested values: 2.0, 4.0, 8.0, 0.5, 0.1, 0.05, 0.01

Restriction: 0.0 <= Gain2

AdaptModeAdaptModeAdaptModeAdaptModeadaptModeadapt_mode (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Threshold adaptation.

Default value: 'on' "on" "on" "on" "on" "on"

List of values: 'off'"off""off""off""off""off", 'on'"on""on""on""on""on"

MinDiffMinDiffMinDiffMinDiffminDiffmin_diff (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Foreground/background threshold.

Default value: 7.0

Suggested values: 3.0, 5.0, 7.0, 9.0, 11.0

Recommended increment: 0.2

StatNumStatNumStatNumStatNumstatNumstat_num (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of statistic data sets.

Default value: 10

Suggested values: 5, 10, 20, 30

Typical range of values: 1 ≤ StatNum StatNum StatNum StatNum statNum stat_num

Recommended increment: 5

ConfidenceCConfidenceCConfidenceCConfidenceCconfidenceCconfidence_c (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Confidence constant.

Default value: 3.25

Suggested values: 4.30, 3.25, 2.82, 2.62

Recommended increment: 0.01

Restriction: 0.0 < ConfidenceC

TimeCTimeCTimeCTimeCtimeCtime_c (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Constant for decay time.

Default value: 15.0

Suggested values: 10.0, 15.0, 20.0

Recommended increment: 5.0

Restriction: 0.0 < TimeC

BgEstiHandleBgEstiHandleBgEstiHandleBgEstiHandlebgEstiHandlebg_esti_handle (output_control)  bg_estimation HBgEsti, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

ID of the BgEsti data set.

Example (HDevelop)

* read Init-Image:
read_image (InitImage, 'xing/init')
* initialize 1. BgEsti-Dataset with
* fixed gains and threshold adaption:
create_bg_esti(InitImage,0.7,0.7,'fixed',0.002,0.02, \
               'on',7.0,10,3.25,15.0,BgEstiHandle1)
* initialize 2. BgEsti-Dataset with
* frame orientated gains and fixed threshold
create_bg_esti(InitImage,0.7,0.7,'frame',30.0,4.0, \
               'off',9.0,10,3.25,15.0,BgEstiHandle2)

Result

create_bg_esticreate_bg_estiCreateBgEstiCreateBgEstiCreateBgEsticreate_bg_esti returns TRUE if all parameters are correct.

Possible Successors

run_bg_estirun_bg_estiRunBgEstiRunBgEstiRunBgEstirun_bg_esti

See also

set_bg_esti_paramsset_bg_esti_paramsSetBgEstiParamsSetBgEstiParamsSetBgEstiParamsset_bg_esti_params, close_bg_esticlose_bg_estiCloseBgEstiCloseBgEstiCloseBgEsticlose_bg_esti

Module

Foundation