JeVoisBase  1.22
JeVois Smart Embedded Machine Vision Toolkit Base Modules
Share this page:
Loading...
Searching...
No Matches
Kalman4D.H
Go to the documentation of this file.
1// ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2//
3// JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4// California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5//
6// This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7// redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8// Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9// without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10// License for more details. You should have received a copy of the GNU General Public License along with this program;
11// if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12//
13// Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14// Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15// ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16/*! \file */
17
19#include <opencv2/video/tracking.hpp> // for kalman filter
20
21#pragma once
22
23namespace kalman4d
24{
25 static jevois::ParameterCategory const ParamCateg("Kalman4D Options");
26
27 //! Parameter \relates Kalman4D
28 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(usevel, bool, "Use velocity tracking, in addition to position",
29 false, ParamCateg);
30
31 //! Parameter \relates Kalman4D
32 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(procnoise, float, "Process noise standard deviation",
33 0.003F, ParamCateg);
34
35 //! Parameter \relates Kalman4D
36 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(measnoise, float, "Measurement noise standard deviation",
37 0.05F, ParamCateg);
38
39 //! Parameter \relates Kalman4D
40 JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(postnoise, float, "A posteriori error estimate standard deviation",
41 0.3F, ParamCateg);
42}
43
44//! Simple component to track a moving 2D box (position and size) over time using a Kalman filter
45/*! A Kalman filter allows one to filter noisy data over time. Here, it is used to filter the possibly noisy results of
46 some machine vision algorith that is trying to detect a particular item in the camera's video stream. On occasion,
47 the detection might abruptly jump to an erroneous location. Such jumps are filtered out by the Kalman filter.
48
49 See for example DemoSaliency to see the Kalman4d filtering over time the location of the most salient object in the
50 video stream. The 4D version is to track a box which is assumed to be moving but of roughly constant size.
51
52 To allow using this component in many different modules and to support various image resolutions, we here internally
53 normalize all measurements and filtered outputs to between [-1000.0 ... 1000.0] horizontally and [-750 ... 750
54 vertically, where (-1000.0, -750.0) is the top-left of the image, (0.0, 0.0) the center, and (1000.0, 750.0) the
55 bottom-right corner.
56
57 Helper functions are used to do this conversion, see \ref coordhelpers.
58
59 The range [-1000.0 ... 1000.0] is fixed and is not exposed as a parameter so that users of the Kalman4D class will
60 not be tempted to use various ranges, in an effort to standardize the interface between vision modules (which may
61 track object locations using Kalman4D) and motor control (e.g., an Arduino controlling servos on a pan/tilt camera
62 head). The writers of motor control code can reliably assume that object coordinates sent to them will be in the
63 [-1000.0 ... 1000.0] horizontal and [-750 ... 750] vertical range with 0,0 at dead center, and control their motors
64 accordingly.
65
66 This code loosely inspired by https://github.com/abreheret/kalman-mouse/blob/master/src/main.cpp
67
68 \ingroup components */
70 public jevois::Parameter<kalman4d::usevel, kalman4d::procnoise,
71 kalman4d::measnoise, kalman4d::postnoise>
72{
73 public:
74 //! Constructor
75 Kalman4D(std::string const & instance);
76
77 //! Destructor
78 virtual ~Kalman4D();
79
80 //! Function to call each time you have a new measurement (output from a vision algorithm)
81 /*! This variant does not normalize the coordinates, they should typically be in [-1000.0 .. 1000.0] */
82 void set(float x, float y, float w, float h);
83
84 //! Function to call each time you have a new measurement (output from a vision algorithm)
85 /*! This variant normalizes the image coordinates to the range [-1000.0 .. 1000.0] horizontal and [-750 ... 750]
86 vertical. */
87 void set(float x, float y, float w, float h, unsigned int imgwidth, unsigned int imgheight);
88
89 //! Function to call each time you want to get the Kalman-filtered coordinates
90 /*! It is ok to call get() multiple times with no intervening set(), if you have no new measurements but still want
91 to use the filter output. This variant does not normalize the coordinates, they should typically be in [-1000.0
92 .. 1000.0] range.
93
94 eps is used for rounding of returned coordinates, which is convenient to avoid sending very long floating point
95 values over serial port. */
96 void get(float & x, float & y, float & w, float & h, float const eps = 0.01F);
97
98 //! Function to call each time you want to get the Kalman-filtered coordinates
99 /*! It is ok to call get() multiple times with no intervening set(), if you have no new measurements but still want
100 to use the filter output. This variant normalizes the coordinates back to image coordinates in [0 .. imgwidth[ x
101 [0 .. imgheight[ */
102 void get(float & x, float & y, float & w, float & h, unsigned int imgwidth, unsigned int imgheight,
103 float const eps = 0.01F);
104
105 //! Function to call each time you want to get the Kalman-filtered coordinates
106 /*! It is ok to call get() multiple times with no intervening set(), if you have no new measurements but still want
107 to use the filter output. This variant returns both the coordinates in [0 .. 1000] range (typically, so send to
108 an Arduino for servo control, or other motor plant), and the image coordinates in [0 .. imgwidth[ x [0
109 .. imgheight[ (typically, to draw on a debug/demo image). */
110 void get(float & rawx, float & rawy, float & raww, float & rawh, float & imgx, float & imgy,
111 float & imgw, float & imgh, unsigned int imgwidth, unsigned int imgheight,
112 float const raweps = 0.01F, float const imgeps = 0.01F);
113
114 //! Get the latest error covariance matrix (errorCovPost). It is updated after each get() or set()
115 cv::Mat const & getErrorCov() const;
116
117 protected:
118 void postInit() override;
119 void onParamChange(kalman4d::usevel const & param, bool const & newval) override;
120 void onParamChange(kalman4d::procnoise const & param, float const & newval) override;
121 void onParamChange(kalman4d::measnoise const & param, float const & newval) override;
122 void onParamChange(kalman4d::postnoise const & param, float const & newval) override;
123
124 // state is (x, y, width, height, xdot, ydot)
125 cv::KalmanFilter itsKF;
128 cv::Mat itsLatest;
130
131}; // class Kalman4D
132
int h
Simple component to track a moving 2D box (position and size) over time using a Kalman filter.
Definition Kalman4D.H:72
void postInit() override
Definition Kalman4D.C:35
void onParamChange(kalman4d::measnoise const &param, float const &newval) override
virtual ~Kalman4D()
Destructor.
Definition Kalman4D.C:31
void onParamChange(kalman4d::postnoise const &param, float const &newval) override
void get(float &x, float &y, float &w, float &h, float const eps=0.01F)
Function to call each time you want to get the Kalman-filtered coordinates.
Definition Kalman4D.C:115
void onParamChange(kalman4d::usevel const &param, bool const &newval) override
JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(usevel, bool, "Use velocity tracking, in addition to position", false, ParamCateg)
Parameter.
cv::Mat itsProcessNoise
Definition Kalman4D.H:126
JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(procnoise, float, "Process noise standard deviation", 0.003F, ParamCateg)
Parameter.
cv::Mat itsLatest
Definition Kalman4D.H:128
void onParamChange(kalman4d::procnoise const &param, float const &newval) override
cv::KalmanFilter itsKF
Definition Kalman4D.H:125
bool itsFresh
Definition Kalman4D.H:129
JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(measnoise, float, "Measurement noise standard deviation", 0.05F, ParamCateg)
Parameter.
void set(float x, float y, float w, float h)
Function to call each time you have a new measurement (output from a vision algorithm)
Definition Kalman4D.C:98
cv::Mat const & getErrorCov() const
Get the latest error covariance matrix (errorCovPost). It is updated after each get() or set()
Definition Kalman4D.C:185
JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(postnoise, float, "A posteriori error estimate standard deviation", 0.3F, ParamCateg)
Parameter.
cv::Mat itsMeasurement
Definition Kalman4D.H:127