CV Kalman Filter Step
One predict (+ correct) step of cv2.KalmanFilter for a 2-D point: smooths a noisy track and, crucially, KEEPS PREDICTING while the measurement is missing. cv2.KalmanFilter is a stateful class the raw wrappers cannot expose, so this node packs the whole filter state (posterior state vector + error covariance) into one NPARRAY: chain one node per frame, this 'state' output -> the next frame's 'state' input, and leave the first frame's state unconnected to initialise from the first measurement. Leave 'measurement' unconnected (or feed an empty array) on frames where the detector lost the object - the node then predicts only and the track coasts through the occlusion instead of jumping. Pair with any detector output: 'CV Track Window' centers, a 'Select Component At Point' centroid, a YuNet face box...
- measurement
- state
- state
- filtered
- predicted
- velocity
- corrected
Inputs (7)
| Name | Type | Default | Description |
|---|---|---|---|
| model | COMBO | constant velocity (x, y + vx, vy) | Motion model. Constant position only smooths jitter; constant velocity is the standard tracker (it coasts in a straight line when the measurement drops out); constant acceleration also follows curved motion but needs a cleaner signal. |
| dt | FLOAT | 1.00.001–1000 | Time between this step and the previous one, in whatever unit the velocity should use. Leave at 1.0 to work in 'pixels per frame'. |
| process_noise | FLOAT | 0.011e-8–1000000 | How much the model is allowed to be wrong per step (process noise covariance). RAISE it to follow abrupt manoeuvres, LOWER it for a smoother, laggier track. |
| measurement_noise | FLOAT | 1.01e-8–1000000 | How noisy the detector is, in squared pixels. Raise it to trust the model more than the measurement (more smoothing); lower it to snap onto every detection. |
| measurementopt | NPARRAY | Measured position as 2 numbers (x, y) - a 1x2 array, a 'CV Scalar' literal or any Nx2 point set (the FIRST row is used). Leave unconnected or pass an empty array for a PREDICT-ONLY step (object occluded / detector failed). | |
| stateopt | NPARRAY | Packed filter state from the PREVIOUS frame's 'state' output. Leave unconnected on the first frame: the filter is then seeded at the measurement with zero velocity. | |
| initial_uncertaintyopt | FLOAT | 1.00.000001–1000000 | Error covariance the filter starts with when no 'state' is connected. Large = 'the seed position is a guess', so the first few measurements dominate. |
Outputs (5)
| Name | Type | Description |
|---|---|---|
| state | NPARRAY | Packed filter state, float32 (n, n+1): column 0 is the state vector, the rest is the error covariance. Wire it into the next frame - it is not meant to be read directly. |
| filtered | NPARRAY | 1x2 filtered position AFTER the correction (the smoothed track point). Equals 'predicted' on a predict-only step. Feed 'CV Draw Points'. |
| predicted | NPARRAY | 1x2 position the motion model expected BEFORE seeing the measurement - the extrapolation that carries the track through an occlusion. |
| velocity | NPARRAY | 1x2 estimated velocity (units per dt); zeros for the constant-position model. Draw it with 'CV Draw Rays' to show where the track is heading. |
| corrected | BOOLEAN | True when a measurement was supplied and applied, false on a predict-only (coasting) step. |