ADCS.helpers.plotting.plot_estimator module

ADCS.helpers.plotting.plot_estimator.plot_bias_comparison(time, real_bias, est_bias, title, units)[source]

Plot true versus estimated bias components over time.

This function provides a generic visualization for comparing real and estimated bias states, such as gyro bias, accelerometer bias, or sensor offsets.

Mathematical Context

Let the bias vector be

\[\mathbf{b}(t) = \begin{bmatrix} b_1(t) & b_2(t) & \dots & b_M(t) \end{bmatrix}^T\]

with corresponding estimates \(\hat{\mathbf{b}}(t)\). The function plots each component:

\[b_k(t_i), \quad \hat{b}_k(t_i)\]

Visualization Layout

  • One subplot per bias component

  • Shared time axis

  • Real bias shown as solid line

  • Estimated bias shown as dashed line

param time:

One-dimensional array of time stamps in seconds.

type time:

numpy.ndarray

param real_bias:

True bias history. Can be one- or two-dimensional.

type real_bias:

numpy.ndarray

param est_bias:

Estimated bias history. Must match real_bias in shape.

type est_bias:

numpy.ndarray

param title:

Title displayed at the top of the figure.

type title:

str

param units:

Units of the bias values shown on the y-axis.

type units:

str

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

  • time (ndarray)

  • real_bias (ndarray)

  • est_bias (ndarray)

  • title (str)

  • units (str)

Return type:

None

ADCS.helpers.plotting.plot_estimator.plot_error_and_sun(time, state_hist, est_state_hist, os_hist)[source]

Plot attitude error, angular velocity error, and sunlight state over time.

This function evaluates estimation performance by computing and plotting:

  • Quaternion attitude error magnitude

  • Angular velocity estimation error norm

  • Binary sunlight (sunlit / eclipse) state

All quantities are plotted against time in a shared x-axis layout.

Quaternion Error Metric

Let the true and estimated quaternions be \(\mathbf{q}\) and \(\hat{\mathbf{q}}\), respectively. The scalar quaternion alignment measure is computed via the dot product:

\[d = \hat{\mathbf{q}}^T \mathbf{q}\]

The equivalent rotation angle error is

\[\theta_q = \cos^{-1}\!\left(-1 + 2 d^2\right)\]

which represents the smallest angular rotation between the two attitudes. The result is reported in degrees.

Angular Velocity Error

The angular velocity error is computed as the Euclidean norm of the difference between estimated and true angular velocity vectors:

\[e_\omega = \left\| \hat{\boldsymbol{\omega}} - \boldsymbol{\omega} \right\|\]

and converted from rad/s to deg/s.

Sunlight State

The sunlight state is obtained from each orbital state object via is_sunlit() and plotted as a binary signal:

  • 1 — Sunlit

  • 0 — Eclipse

Visualization Layout

The figure consists of three stacked subplots:

  1. Quaternion attitude error

  2. Angular velocity error

  3. Sunlight state (step plot)

param time:

One-dimensional array of time stamps in seconds.

type time:

numpy.ndarray

param state_hist:

True spacecraft state history.

type state_hist:

numpy.ndarray

param est_state_hist:

Estimated spacecraft state history.

type est_state_hist:

numpy.ndarray

param os_hist:

List of orbital state objects providing sunlight information.

type os_hist:

list

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

  • time (ndarray)

  • state_hist (ndarray)

  • est_state_hist (ndarray)

  • os_hist (List)

Return type:

None

ADCS.helpers.plotting.plot_estimator.plot_sensor_data(time, sensor_hist, clean_sensor_hist)[source]

Plot measured versus clean sensor data for multiple sensor channels.

This function visualizes raw (measured) sensor outputs alongside their corresponding clean or noise-free values, enabling assessment of sensor noise, bias, and filtering performance.

Data Organization

Let the sensor measurement matrix be

\[\mathbf{Y}(t) \in \mathbb{R}^{N \times M}\]

where:

  • \(N\) is the number of time samples

  • \(M\) is the number of sensor channels

Each sensor channel \(j\) is plotted as:

\[y_j^{\text{meas}}(t_i), \quad y_j^{\text{clean}}(t_i)\]

Visualization Layout

  • Subplots are arranged in a near-square grid

  • Each subplot corresponds to one sensor channel

  • Unused subplot axes are hidden automatically

param time:

One-dimensional array of time stamps in seconds.

type time:

numpy.ndarray

param sensor_hist:

Measured sensor data history.

type sensor_hist:

numpy.ndarray

param clean_sensor_hist:

Clean or reference sensor data history.

type clean_sensor_hist:

numpy.ndarray

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

  • time (ndarray)

  • sensor_hist (ndarray)

  • clean_sensor_hist (ndarray)

Return type:

None

ADCS.helpers.plotting.plot_estimator.plot_state_comparison(time, state_hist, est_state_hist=None)[source]

Plot angular velocity and Euler angle time histories, with optional estimation overlay.

This function visualizes the rotational state of a spacecraft by plotting:

  • Body angular velocity components \(\boldsymbol{\omega} = [\omega_1, \omega_2, \omega_3]^T\)

  • Euler attitude angles (roll, pitch, yaw) derived from attitude quaternions

If an estimated state history is provided, estimated values are overlaid for direct comparison against the true (simulated) states.

Mathematical Background

The spacecraft attitude is represented by a quaternion

\[\mathbf{q} = \begin{bmatrix} q_0 & q_1 & q_2 & q_3 \end{bmatrix}^T\]

which is converted to Euler angles

\[(\phi, \theta, \psi)\]

using quat_to_euler(). The angular velocity components are assumed to be stored directly in the state vector as

\[\boldsymbol{\omega}(t_i) = [\omega_1, \omega_2, \omega_3]^T\]

Visualization Layout

The figure consists of six subplots arranged in a 3×2 grid:

  • Top three: angular velocity components

  • Bottom three: Euler angles (roll, pitch, yaw)

Usage Notes

  • Euler angles are plotted in degrees

  • Angular velocities are plotted in their native units (typically rad/s)

  • Legends are shown only when estimated states are provided

param time:

One-dimensional array of time stamps in seconds.

type time:

numpy.ndarray

param state_hist:

True spacecraft state history. Columns [0:3] contain angular velocity and columns [3:7] contain attitude quaternions.

type state_hist:

numpy.ndarray

param est_state_hist:

Optional estimated spacecraft state history with the same layout as state_hist.

type est_state_hist:

numpy.ndarray or None

return:

None. The function generates a Matplotlib figure.

rtype:

None

Parameters:

  • time (ndarray)

  • state_hist (ndarray)

  • est_state_hist (ndarray | None)

Return type:

None