You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+53-43
Original file line number
Diff line number
Diff line change
@@ -2,42 +2,36 @@
2
2
3
3
A generic Kalman filter for C++23.
4
4
5
-
A Bayesian filter that uses multivariate Gaussians, a recursive state estimator, and a linear quadratic estimator (LQE). A control theory tool applicable to signal estimation, sensor fusion, or data assimilation problems.
5
+
The Kalman filter is a Bayesian filter that uses multivariate Gaussians, a recursive state estimator, a linear quadratic estimator (LQE), and an Infinite Impulse Response (IIR) filter. It is a control theory tool applicable to signal estimation, sensor fusion, or data assimilation problems. The filter is applicable for unimodal and uncorrelated uncertainties. The filter assumes white noise, propagation and measurement functions are differentiable, and that the uncertainty stays centered on the state estimate. The filter is the optimal linear filter under assumptions. The filter updates estimates by multiplying Gaussians and predicts estimates by adding Gaussians. Designing a filter is as much art as science. Design the state $X$, $P$, the process $F$, $Q$, the measurement $Z$, $R$, the measurement function $H$, and if the system has control inputs $U$, $G$.
6
6
7
-
Simple and extended filters are supported. The update equation uses the Joseph form. Control input is supported. Standard and type-erased Eigen3 linear algebra backends are supported.
8
-
9
-
The Kalman filter is applicable for unimodal and uncorrelated uncertainties. The filter assumes white noise, propagation and measurement functions are differentiable, and that the uncertainty stays centered on the state estimate. The filter is the optimal linear filter under assumptions. The filter updates estimates by multiplying Gaussians and predicts estimates by adding Gaussians.
10
-
11
-
Designing a filter is as much art as science. Design the state $X$, $P$, the process $F$, $Q$, the measurement $Z$, $R$, the measurement function $H$, and if the system has control inputs $U$, $G$.
12
-
13
-
Arbitrary parameters can be added to the prediction and update stages to participate in gain-scheduling or linear parameter varying (LPV) systems.
14
-
15
-
Filters with `state x output x input` dimensions as 1x1x1 and 1x1x0 (no input) are supported through the Standard Templated Library (STL). Higher dimension filters require Eigen 3 support.
16
-
17
-
Standard formatter specialization provided for representation of the filter states.
7
+
This library supports simple and extended filters. The implementation is independent from linear algebra backends. Arbitrary parameters can be added to the prediction and update stages to participate in gain-scheduling or linear parameter varying (LPV) systems. The default filter type is a generalized, customizable, and extended filter. The default type parameters represent a one-state, one-output double-precision floating-point type. The default update equation uses the Joseph form. Examples illustrate various usages and implementation tradeoffs. Standard formatter specialization provided for representation of the filter states. Filters with `state x output x input` dimensions as 1x1x1 and 1x1x0 (no input) are supported through vanilla C++. Higher dimension filters require a linear algebra backend. Customization points and type injections allow for implementation tradeoffs.
18
8
19
9
-[Kalman Filter for C++](#kalman-filter-for-c)
20
10
-[Examples](#examples)
21
11
-[1x1 Constant System Dynamic Model Filter](#1x1-constant-system-dynamic-model-filter)
22
12
-[6x2 Constant Acceleration Dynamic Model Filter](#6x2-constant-acceleration-dynamic-model-filter)
23
-
-[4x1 Non-Linear Dynamic Model Extended Filter](#4x1-non-linear-dynamic-model-extended-filter)
13
+
-[4x1 Nonlinear Dynamic Model Extended Filter](#4x1-nonlinear-dynamic-model-extended-filter)
Example from the [thermal, current of warm air, strength, radius, and location estimation](https://francoiscarouge.github.io/Kalman/ekf_4x1x0_soaring_8cpp-example.xhtml) sample. Four estimated states and one observed output extended filter with two additional prediction arguments and two additional update arguments.
- 2x1x1 constant acceleration dynamic model filter of the [1-dimension position and velocity of a rocket altitude](sample/kf_2x1x1_rocket_altitude.cpp).
157
151
- 8x4 constant velocity dynamic model filter of the [2-dimension position and velocity of the center, aspect ratio, and height of a bounding box](sample/kf_8x4x0_deep_sort_bounding_box.cpp).
[For more, see installation instructions](INSTALL.md).
163
+
164
+
# Reference
165
+
166
+
## Class kalman
160
167
161
168
Also documented in the [fcarouge/kalman.hpp](include/fcarouge/kalman.hpp) header.
162
169
163
-
## Declaration
170
+
###Declaration
164
171
165
172
```cpp
166
173
template <
@@ -173,7 +180,7 @@ template <
173
180
classkalman
174
181
```
175
182
176
-
## Template Parameters
183
+
### Template Parameters
177
184
178
185
| Template Parameter | Definition |
179
186
| --- | --- |
@@ -184,7 +191,7 @@ class kalman
184
191
| `UpdateTypes` | The additional update function parameter types passed in through a tuple-like parameter type, composing zero or more types. Parameters such as delta times, variances, or linearized values. The parameters are propagated to the function objects used to compute the state observation $H$ and the observation noise $R$ matrices. The parameters are also propagated to the state observation function object $H$. Defaults to no parameter types, the empty pack. |
185
192
| `PredictionTypes` | The additional prediction function parameter types passed in through a tuple-like parameter type, composing zero or more types. Parameters such as delta times, variances, or linearized values. The parameters are propagated to the function objects used to compute the process noise $Q$, the state transition $F$, and the control transition $G$ matrices. The parameters are also propagated to the state transition function object $F$. Defaults to no parameter types, the empty pack. |
186
193
187
-
## Member Types
194
+
### Member Types
188
195
189
196
| Member Type | Dimensions | Definition | Also Known As |
190
197
| --- | --- | --- | --- |
@@ -201,15 +208,15 @@ class kalman
201
208
| `state_transition` | x by x | Type of the state transition matrix `f`. | $F$, $Φ$, $A$ |
202
209
| `state` | x by 1 | Type of the state estimate column vector `x`. | $X$ |
203
210
204
-
## Member Functions
211
+
### Member Functions
205
212
206
213
| Member Function | Definition |
207
214
| --- | --- |
208
215
| `(constructor)` | Constructs the filter. |
209
216
| `(destructor)` | Destructs the filter. |
210
217
| `operator=` | Assigns values to the filter. |
211
218
212
-
### Characteristics
219
+
#### Characteristics
213
220
214
221
| Characteristic | Definition |
215
222
| --- | --- |
@@ -228,14 +235,14 @@ class kalman
228
235
| `transition` | Manages the state transition function object $f$. Configures the callable object of expression `state(const state &, const input &, const PredictionTypes &...)` to compute the transition state value. The default value is the equivalent to $f(x) = F * X$. The default function is suitable for linear systems. For extended filters `transition` is a linearization of the state transition while $F$ is the Jacobian of the transition function: $F = ∂f/∂X = ∂fj/∂xi$ that is each row $i$ contains the derivatives of the state transition function for every element $j$ in the state column vector $X$. |
229
236
| `observation` | Manages the state observation function object $h$. Configures the callable object of expression `output(const state &, const UpdateTypes &...arguments)` to compute the observation state value. The default value is the equivalent to $h(x) = H * X$. The default function is suitable for linear systems. For extended filters `observation` is a linearization of the state observation while $H$ is the Jacobian of the observation function: $H = ∂h/∂X = ∂hj/∂xi$ that is each row $i$ contains the derivatives of the state observation function for every element $j$ in the state vector $X$. |
230
237
231
-
### Modifiers
238
+
#### Modifiers
232
239
233
240
| Modifier | Definition |
234
241
| --- | --- |
235
242
| `predict` | Produces estimates of the state variables and uncertainties. |
236
243
| `update` | Updates the estimates with the outcome of a measurement. |
237
244
238
-
# Format
245
+
## Format
239
246
240
247
A specialization of the standard formatter is provided for the filter. Use `std::format` to store a formatted representation of all of the characteristics of the filter in a new string. Standard format parameters to be supported.
[For more, see installation instructions](INSTALL.md).
259
-
260
256
# Considerations
261
257
262
258
## Motivations
@@ -270,7 +266,7 @@ This package explores what could be a Kalman filter implementation a la standard
270
266
271
267
## Selected Tradeoffs
272
268
273
-
In theory there is no difference between theory and practice, while in practice there is. The following engineering tradeoffs have been selected forthe implementation:
269
+
In theory there is no difference between theory and practice, while in practice there is. The following engineering tradeoffs have been selected for this library implementation:
274
270
275
271
- Update and prediction additional arguments are stored in the filter at the costs of memory and performance for the benefits of consistent data access and records.
276
272
- The default floating point data type for the filter is `double` with about 16 significant digits to reduce loss of information compared to `float`.
@@ -293,6 +289,18 @@ The [benchmarks](benchmark) share some performance information. Custom specializ
293
289
294
290
# Resources
295
291
292
+
## Definitions
293
+
294
+
| Term | Definition |
295
+
| --- | --- |
296
+
| EKF | The Extended Kalman Filter is the nonlinear version of the Kalman filter. Useful for nonlinear dynamics systems. This filter linearizes the model about an estimate working point of the current mean and covariance. |
297
+
| ESKF | The Error State Kalman Filter is the error estimation version of the Kalman filter. Useful for linear error state dynamics systems. This filter estimates the errors rather than the states.
298
+
| UKF | The Unscented Kalman Filter is the sampled version of the Extended Kalman Filter. Useful for highly nonlinear dynamics systems. This filter samples sigma points about an estimate working point of the current mean using an Unscented Transformation technique. |
299
+
300
+
Further terms should be defined and demonstrated for completeness: CKF, EnKF, Euler-KF, Forward-Backward, FKF, IEKF, Joseph, KF, MEKF, MRP-EKF, MRP-UKF, MSCKF, SKF, Smoother, USQUE, UDU, UT.
301
+
302
+
## Articles
303
+
296
304
Resources to learn about Kalman filters:
297
305
298
306
-[A New Approach to Linear Filtering and Prediction Problems](https://www.cs.unc.edu/~welch/kalman/kalmanPaper.html) by Kalman, Rudolph Emil in Transactions of the ASME - Journal of Basic Engineering, Volume 82, Series D, pp 35-45, 1960 - Transcription by John Lukesh.
@@ -302,6 +310,8 @@ Resources to learn about Kalman filters:
302
310
-[Wikipedia Kalman filter](https://en.wikipedia.org/wiki/Kalman_filter) by Wikipedia, the free encyclopedia.
303
311
-[Applications of Kalman Filtering in Aerospace 1960 to the Present](https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=5466132) by Mohinder S. Grewal and Angus P. Andrews. IEEE 2010.
0 commit comments