Unit Quaternion

Definition

A unit quaternion $(\mathbf{ϵ},\eta )$, with vector part $\mathbf{ϵ}\in {\mathbb{R}}^3$
and scalar part $\eta \in \mathbb{R}$ subject to ${\mathbf{ϵ}}^T\mathbf{ϵ}+{\eta }^2=1$,
is a global four-parameter representation of a rotation $\mathbf{R}\in \mathrm{SO}(3)$. In this
project it is the canonical attitude-error description (notation.md): the
relative quaternion between an actual frame and its desired frame encodes orientation error through
its vector part alone, so the error vanishes iff $\mathbf{ϵ}=0$. Because the
attitude controller and CLIK enter only via $\mathbf{ϵ}$ through the geometric (not
analytical) Jacobian, the orientation error dynamics carry no representation singularity — the
defect that afflicts minimal (Euler-angle) parameterizations.

Key Equations

Attitude-error coordinates. For the base and end-effector, the tracked error uses twice the
quaternion vector part (the small-error gain that makes $\tilde{\mathbf{x}}$ a faithful
linearization of the rotation-vector error near identity):

$${\tilde{\mathbf{x}}}_b=2{\mathbf{ϵ}}_{b{b}_d},{\tilde{\mathbf{x}}}_e=\left[\begin{array}{c}{\mathbf{p}}_{e{e}_d}\\ 2{\mathbf{ϵ}}_{e{e}_d}\end{array}\right],$$

with desired frames denoted by the ${}_d$ subscript. (Giordano §IV / current_sota §4.1) — only the
vector part $\mathbf{ϵ}$ appears, hence no representation singularity in the error.

Error-rate map. The rate of a quaternion attitude error maps the body angular velocity through
a configuration-dependent block built from the current error quaternion:

$${\mathbf{J}}_{{\tilde{x}}_b}=-{\eta }_{b{b}_d}\mathbf{E}+[{\mathbf{ϵ}}_{b{b}_d}{]}^{\wedge },{\dot{\tilde{\mathbf{x}}}}_b={\mathbf{J}}_{{\tilde{x}}_b}{\mathbf{\omega }}_b,$$

and identically for the EE rotational block
$-{\eta }_{e{e}_d}\mathbf{E}+[{\mathbf{ϵ}}_{e{e}_d}{]}^{\wedge }$ acting on ${\mathbf{\nu }}_e$.
(Giordano eqs 24, 25 / current_sota eqs 4.1–4.2) — $[\cdot {]}^{\wedge }$ is the skew/cross-product
matrix and $\mathbf{E}$ the identity. This block is the standard quaternion-propagation map; it
loses rank only at error angle $\pi$ ($\eta =0$, $\Vert \mathbf{ϵ}\Vert =1$). The full
stacked error-rate Jacobian ${\mathbf{J}}_{\tilde{x}}=\mathrm{blkdiag}({\mathbf{J}}_{{\tilde{x}}_b},{\mathbf{J}}_{{\tilde{x}}_e})$
and its role in the impedance law and Lyapunov function are developed in
task_space_error_dynamics.

Pointing-error convention (versine). Camera/EE pointing error is reported as an angle via the
versine $1-\cos \theta$ between the look axis $\hat{\mathbf{z}}$ and its desired direction
${\hat{\mathbf{z}}}_{\mathrm{des}}$, never as a raw vector difference
$\Vert \mathbf{z}-{\mathbf{z}}_{\mathrm{des}}\Vert$:

$$\text{pointing error}=1-\cos \theta =1-\hat{\mathbf{z}}\cdot {\hat{\mathbf{z}}}_{\mathrm{des}}.$$

(current_sota eq 7.3) — a roll-free scalar that depends only on the camera aim axis; it is the
metric counterpart of the quaternion attitude error, decoupled from any roll about the look axis.

Source Support

• caccavale2001kinematic — canonical demonstration that
  the unit quaternion removes orientation-representation singularities from CLIK: the geometric
  Jacobian appears in lieu of the analytical Jacobian, and only the vector part of the relative
  quaternion enters the error (their Eqs. 18–20). Free-floating regime (generalized Jacobian),
  but the quaternion error and its rate map are the same operator used here.
• giordano2019coordinated — origin of the
  $-\eta \mathbf{E}+[\mathbf{ϵ}{]}^{\wedge }$ error-rate block and the $2\mathbf{ϵ}$
  error coordinates (eqs 24–25); free-flying circumcentroidal coordinated control (the project’s
  primary control source).

Related Topics

• task_space_error_dynamics — assembles the per-task quaternion
  error-rate blocks into the stacked ${\mathbf{J}}_{\tilde{x}}$ that drives the outer loop.
• closed_loop_inverse_kinematics — the CLIK family where the
  quaternion error first replaces the Euler-angle error to kill representation singularities.
• coordinated_control — consumes the quaternion error $\tilde{\mathbf{x}}$
  and its Jacobian transpose ${\mathbf{J}}_{\tilde{x}}^T$ in the impedance control law.
• exponential_coordinates — the rotation-vector / $\mathfrak{so}(3)$
  parameterization that $2\mathbf{ϵ}$ linearizes near identity; an alternative global chart.
• trajectory_tracking — the broader task served; the versine pointing
  metric (eq 7.3) is its attitude-tracking figure of merit.

Open Questions

• The error-rate block $-\eta \mathbf{E}+[\mathbf{ϵ}{]}^{\wedge }$ is singular at error
  angle $\pi$; confirm the operating envelope never approaches $\eta =0$ so ${\mathbf{J}}_{\tilde{x}}$
  retains full rank throughout a maneuver.
• Sign/handedness convention for the relative quaternion ($\mathbf{ϵ}$ vs. $-\mathbf{ϵ}$,
  the double-cover) is not pinned in the master; verify the implementation’s shortest-arc selection
  matches the $2\mathbf{ϵ}$ error gain used in the control law.