Conventions
This page defines the cross-cutting frame, notation, and quaternion conventions used across IMU-GPS-ESKF.
File-specific schema, supported filenames, and runtime input handling are documented on Inputs.
Frames
Global frame G
G denotes the global frame. In this project it is treated as a map-local Cartesian frame in meters. [1], [2], [3], [4]
Body frame B
B denotes the body or ego-vehicle frame.
IMU frame I
I denotes the IMU frame.
Gravity-aligned frame A
A denotes a gravity-aligned frame with arbitrary yaw. [5]
Body and IMU identification in this project
In this project, the body and IMU frames are treated as collocated, so code usually uses I unless the distinction matters. [1], [2], [4], [6], [7]
Axis convention
For the nuScenes-shaped inputs used here, both the body and IMU frames use the Forward-Left-Up axis convention:
xforwardyleftzup
Reference point
The body reference is the vehicle reference near the midpoint of the rear axle. For this project, the IMU reference is treated the same way. [1], [2], [4], [6], [7]
Notation
Vector notation
A vector carries the frame of its coordinates as a left superscript.
Examples:
- \({}^{A}\mathbf{g}\)
- \({}^{I}\mathbf{g}\)
- \({}^{G}\mathbf{p}_0\)
- \({}^{G}\mathbf{v}_0\)
Transform notation
A transform carries the target frame as a left superscript and the source frame as a right subscript.
Examples:
- \({}^{A}q_{\fsub{I}}\)
- \({}^{G}q_{\fsub{I}}\)
- \({}^{I}q_{\fsub{A}}\)
- \({}^{G}R_I\)
A practical reading rule is: target frame on the left, source frame on the right.
Code names
In code, the same quantities appear in compact variable names.
Examples:
- \({}^{A}q_{\fsub{I}}\) ->
q_AI - \({}^{G}q_{\fsub{I}}\) ->
q_GI - \({}^{I}q_{\fsub{A}}\) ->
q_IA - \({}^{G}R_I\) ->
R_GI - \({}^{A}\mathbf{v}\) ->
v_A - \({}^{G}\mathbf{p}_0\) ->
p0_G - \({}^{G}\mathbf{v}_0\) ->
v0_G
In names like p0_G, the 0 is a time or index label. The trailing G is still the expression frame.
Passive coordinate transforms
The docs use passive coordinate-transform notation. A quaternion \({}^{A}q_{\fsub{I}}\) and a rotation matrix \({}^{A}R_I\) describe the same change of coordinates from frame I to frame A.
Re-expression example
If \({}^{I}\mathbf{v}\) is a vector expressed in frame I, then re-expressing it in frame A is written as
\[ (0, {}^{A}\mathbf{v}) = {}^{A}q_{\fsub{I}} \otimes (0, {}^{I}\mathbf{v}) \otimes {}^{I}q_{\fsub{A}} \quad \Longleftrightarrow \quad {}^{A}\mathbf{v} = {}^{A}R_I \, {}^{I}\mathbf{v} \]
and the corresponding code may look like:
const Eigen::Vector3d v_A = q_AI * v_I;In both cases, the same physical vector is being re-expressed; only its coordinates change.
Transform composition
Transforms compose by chained frames:
\[ {}^{X}q_{\fsub{Z}} = {}^{X}q_{\fsub{Y}} \otimes {}^{Y}q_{\fsub{Z}}, \qquad {}^{X}R_Z = {}^{X}R_Y \, {}^{Y}R_Z \]
Quaternion inverse
For a unit quaternion, the inverse is the conjugate:
\[ {}^{Y}q_{\fsub{X}} = ({}^{X}q_{\fsub{Y}})^{-1} = ({}^{X}q_{\fsub{Y}})^* \]
Geometric objects
Points and free vectors
Points and free vectors do not behave the same way under a change of frame.
- points pick up both rotation and translation
- free vectors pick up rotation only
Displacement vectors are differences of points, so the translation part cancels out and only the rotation remains.
That is the convention behind the usual physical vectors in this repo, such as omega, f, g, v, and a.
Quaternions
Component order
Quaternion components are stored in [w, x, y, z] order. [8], [9]
That same order is used when constructing an Eigen quaternion:
const Eigen::Quaterniond q(w, x, y, z);Multiplication convention
Quaternion multiplication uses the Hamilton convention.
Gravity
Gravity direction in A
Frame A is gravity-aligned with +z up.
So the gravity vector expressed in A is:
\[ {}^{A}\mathbf{g} = \begin{bmatrix} 0 \\ 0 \\ -g \end{bmatrix} \]