State Estimators
================

In robotics, one thing that we are going to battle with is the
uncertainty in estimating states. That also applies to estimating the
robot's internal states such as joint positions, end effector poses,
etc. While empirically we found the raw data of robot states from
`libfranka` api is good enough for most purposes, we still allow state
estimator implementations in case you need it due to various resons.



Exponential Smoothing (Lowpass Filtering)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently we implemented one state estimator. We name it ``Exponential
Smoothing`` instead of ``lowpass filtering`` as we want to explicitly state
how the math is done in this filtering.

Overall, what exponential smoothing does is that given raw data
observation of robot states $o_{t}$, the current estimated robot state
$x_{t}$ is:

$$x_{t} = \alpha o_{t} + (1 - \alpha) x_{t-1}$$

When $\alpha=1$, the controller directly uses the raw state
observation. Notice that $+$ in this equation is a general addition,
and in the case of orientation, it is implemented using ``slerp``
function instead of direct numerical addition.

This state estimator provides estimation over the following three
states, which can be found in ``state_estimator_cfg`` in the configs such as `osc-pose-controller.yml`_:

* joint positions: ``alpha_q``
* joint velocities: ``alhpa_dq``
* end effector poses: ``alpha_eef``




.. _osc-pose-controller.yml: https://github.com/UT-Austin-RPL/deoxys_control/blob/main/deoxys/config/osc-pose-controller.yml