diff --git a/README.md b/README.md index f389fab..39ad65b 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,10 @@ This library implements following features: * Extended Kalman Filter (when using functions for dynamics and observation matrixes) * Correlation Matrix -## Demos +## Demos/Examples * [Browser interactive constant acceleration on bikes](http://piercus.github.io/kalman-filter) +* [Sinusoidale Extended Kalman-Filter](https://observablehq.com/d/a033acc0859cc0de) * [Code pen GPS Data smoothing with constant speed](https://codepen.io/piercus/pen/wvoqPww) * [Partial Observation](https://github.com/piercus/kalman-filter/issues/34) * [Smooth 3x3 rotation matrix](https://github.com/piercus/kalman-filter/issues/37) @@ -136,6 +137,7 @@ For advanced usage, here is the correspondance table with the matrix name of the | $H_k$, the observation model | `observation.stateProjection` | | $Q_k$, the covariance of the process noise | `dynamic.covariance` | | $R_k$, the covariance of the observation noise | `observation.covariance` | +| $B_k u_k$, the control-input model multiplied by the control vector | `dynamic.constant` | |$\mathbf{P}_{0\mid 0}$| `dynamic.init.covariance` | |$\mathbf{x}_{0\mid 0}$| `dynamic.init.mean` | @@ -151,11 +153,45 @@ Available default models as : This will automatically configure the `dynamic.transition` matrix. -| `dynamic.name` | State | Transition Equation | `dynamic.transition` | -|--|--|--|--| -| `constant-position` | $\begin{bmatrix} x_t \end{bmatrix}$ | $x_t \sim x_{t-1}$ | $\begin{bmatrix} 1 \end{bmatrix}$ | -| `constant-speed` | $\begin{bmatrix} x_t \\\\ speed_t \end{bmatrix}$ | $\begin{split}x_t \sim x_{t-1} + speed_{t-1},\\\\ speed_t \sim speed_{t-1}\end{split}$| $\begin{bmatrix} 1 & 1 \\\\ 0 & 1 \end{bmatrix}$ | -| `constant-acceleration` | $\begin{bmatrix} x \\\\ speed_t \\\\ acc_t \end{bmatrix}$ | $\begin{split}x_t \sim x_{t-1} + speed_{t-1} \\\\ speed_t \sim speed_{t-1} + acc_{t-1} \\\\ acc_t \sim acc_{t-1}\end{split}$ | $\begin{bmatrix} 1 & 1 & 0 \\\\ 0 & 1 & 1 \\\\ 0 & 0 & 1\end{bmatrix}$ | +##### constant-position + +```math +\begin{align} +State :& \begin{bmatrix} x_t \end{bmatrix}\\ +Transition Equation :& x_t \sim x_{t-1} \\ +dynamic.transition :& \begin{bmatrix} 1 \end{bmatrix} +\end{align} +``` + +##### constant-speed + +```math +\begin{align} +State :& \begin{bmatrix} x_t \\ speed_t \end{bmatrix} \\ +Transition Equation :& +\begin{split} +x_t &\sim x_{t-1} + speed_{t-1},\\ +speed_t &\sim speed_{t-1} +\end{split} \\ +dynamic.transition :& \begin{bmatrix} 1 & 1 \\ 0 & 1 \end{bmatrix} +\end{align} +``` + +##### constant-acceleration + +```math +\begin{align} +State :& \begin{bmatrix} x_t \\ speed_t \\ acc_t \end{bmatrix} \\ + +Transition Equation :& +\begin{split} +x_t &\sim x_{t-1} + speed_{t-1} \\ +speed_t &\sim speed_{t-1} + acc_{t-1} \\ +acc_t &\sim acc_{t-1} +\end{split} \\ +dynamic.transition :& \begin{bmatrix} 1 & 1 & 0 \\ 0 & 1 & 1 \\ 0 & 0 & 1\end{bmatrix} +\end{align} +``` #### 'constant-position' on 2D data @@ -337,6 +373,7 @@ In order to use the Kalman-Filter with a dynamic or observation model which is n * `observation.covariance` * `dynamic.transition` * `dynamic.covariance` +* `dynamic.constant` In this situation this `function` will return the value of the matrix at each step of the kalman-filter. @@ -421,7 +458,14 @@ You will need to put your non-linear functions in the following parameters * `observation.fn` * `dynamic.fn` -See an example in `test/issues/56.js` +See an example in [Sinusoidale Extended Kalman-Filter](https://observablehq.com/d/a033acc0859cc0de) + +### Using Control model + +If you want to add a constant parameter in the dynamic model (also called `control input`), you can use `dynamic.constant` function + +See an example code in `demo/bouncing-ball` or the result in [Bouncing Ball example](https://observablehq.com/d/a033acc0859cc0de) + ## Use your kalman filter @@ -456,7 +500,7 @@ If you want to use KalmanFilter in more advanced usage, you might want to dissoc let previousCorrected = null; const results = []; observations.forEach(observation => { - const predictedState = kFilter.predict({ + const predicted = kFilter.predict({ previousCorrected }); @@ -589,7 +633,7 @@ let previousCorrected = null; const results = []; observations.forEach(observation => { - const predictedState = kFilter.predict({ + const predicted = kFilter.predict({ previousCorrected }); @@ -620,7 +664,7 @@ let previousCorrected = null; const results = []; observations.forEach(observation => { - const predictedState = kFilter.predict({ + const predicted = kFilter.predict({ previousCorrected }); diff --git a/package-lock.json b/package-lock.json index 70be18a..89befdc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "kalman-filter", - "version": "1.10.1", + "version": "1.12.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "kalman-filter", - "version": "1.10.1", + "version": "1.12.0", "license": "MIT", "dependencies": { "@rayyamhk/matrix": "^1.0.5", diff --git a/package.json b/package.json index 052c690..a02c97f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "kalman-filter", - "version": "1.10.1", + "version": "1.12.0", "description": "Kalman filter (and Extended Kalman Filter) Multi-dimensional implementation in Javascript", "main": "index.js", "scripts": { @@ -14,6 +14,10 @@ "type": "git", "url": "git+https://github.com/piercus/kalman-filter.git" }, + "files": [ + "index.js", + "lib" + ], "release": { "branches": [ "master"