Attitude

Note: This document is AI-translated. Please refer to the source code for specific APIs and behaviors.

Overview

The Attitude module provides complete attitude representation and conversion functionality, supporting three main attitude representation methods: quaternions, Euler angles, and rotation matrices, with conversions between them.

Core Concepts

Attitude Representation Methods

1. Quaternion

• Singularity-free attitude representation
• Suitable for interpolation and continuous rotation
• Low memory footprint (4 doubles)

2. Euler Angles

• Intuitive attitude representation (roll, pitch, yaw)
• Supports 12 rotation sequences
• May have gimbal lock issues

3. Rotation Matrix (Matrix3d)

• 3×3 orthogonal matrix
• Suitable for vector transformation
• No singularity issues

Rotation Sequences

The module supports 12 Euler angle rotation sequences:

Type	Rotation Sequence	Enum Value
Tait-Bryan angles	X→Y→Z	eXYZ = 123
Tait-Bryan angles	X→Z→Y	eXZY = 132
Tait-Bryan angles	Y→X→Z	eYXZ = 213
Tait-Bryan angles	Y→Z→X	eYZX = 231
Tait-Bryan angles	Z→X→Y	eZXY = 312
Tait-Bryan angles	Z→Y→X	eZYX = 321
Classic Euler angles	X→Y→X	eXYX = 121
Classic Euler angles	X→Z→X	eXZX = 131
Classic Euler angles	Y→X→Y	eYXY = 212
Classic Euler angles	Y→Z→Y	eYZY = 232
Classic Euler angles	Z→X→Z	eZXZ = 313
Classic Euler angles	Z→Y→Z	eZYZ = 323

Note: Tait-Bryan angles use three different axes, while classic Euler angles use the same first and third axes.

Usage Examples

Example 1: Basic Conversion

#include "AstCore/AttitudeConvert.hpp"
#include "AstCore/Euler.hpp"
#include "AstCore/Quaternion.hpp"
#include <iostream>


int main() {
    AST_USING_NAMESPACE 
    // 创建四元数 (绕Z轴旋转90度)
    Quaternion quat = {0.707, 0, 0, 0.707};
    
    // 四元数转旋转矩阵
    Matrix3d matrix;
    aQuatToMatrix(quat, matrix);
    
    std::cout << "四元数转矩阵成功" << std::endl;
    
    // 旋转矩阵转欧拉角 (ZYX顺序)
    Euler euler;
    aMatrixToEuler(matrix, Euler::eZYX, euler);
    
    std::cout << "欧拉角: " << euler.angle1() << ", " 
              << euler.angle2() << ", " << euler.angle3() << std::endl;
    
    return 0;
}

Example 2: Euler Angle Usage

#include "AstCore/Euler.hpp"
#include "AstCore/Quaternion.hpp"
#include <iostream>

int main() {
    AST_USING_NAMESPACE
    {
        // 创建欧拉角 (弧度) - 滚转10°, 俯仰20°, 偏航30°
        Euler euler{0.1745, 0.3491, 0.5236};
        
        // 转换为旋转矩阵 (ZYX顺序)
        Matrix3d rot_mat;
        euler.toMatrix(Euler::eZYX, rot_mat);
        
        std::cout << "欧拉角转矩阵完成" << std::endl;
    }
    {
        // 另一个作用域：转换为四元数
        Euler euler{0.1745, 0.3491, 0.5236};
        Quaternion quat;
        euler.toQuat(Euler::eZYX, quat);
        
        std::cout << "四元数: " << quat.qs() << ", " << quat.qx() 
                  << ", " << quat.qy() << ", " << quat.qz() << std::endl;
    }
}

Example 3: Quaternion Operations

#include "AstCore/Quaternion.hpp"
#include <iostream>

int main() {
    AST_USING_NAMESPACE
    {
        Quaternion q = {0.5, 0.5, 0.5, 0.5};
        
        // 归一化
        q.normalize();
        
        std::cout << "归一化后范数: " << q.norm() << std::endl;
    }
    
    {
        // 获取归一化副本
        Quaternion q = {1.0, 2.0, 3.0, 4.0};
        Quaternion q_normalized = q.normalized();
        
        std::cout << "归一化副本范数: " << q_normalized.norm() << std::endl;
    }
    {
        // 设置为单位四元数
        Quaternion q;
        q.setIdentity();
        
        std::cout << "单位四元数: " << q.qs() << ", " << q.qx() 
                  << ", " << q.qy() << ", " << q.qz() << std::endl;
    }
}

Example 4: Complete Conversion Flow

#include "AstCore/AttitudeConvert.hpp"
#include "AstCore/Euler.hpp"
#include "AstCore/Quaternion.hpp"
#include <iostream>

int main() {
    AST_USING_NAMESPACE
    // 初始欧拉角 (滚转, 俯仰, 偏航)
    Euler initial_euler{0.3, 0.2, 0.1};
    std::cout << "初始欧拉角: " << initial_euler.angle1() << ", " 
              << initial_euler.angle2() << ", " << initial_euler.angle3() << std::endl;
    
    {
        // 欧拉角 -> 四元数
        Quaternion quat;
        initial_euler.toQuat(Euler::eZYX, quat);
        std::cout << "转换后的四元数: " << quat.qs() << ", " << quat.qx() 
                  << ", " << quat.qy() << ", " << quat.qz() << std::endl;
    }
    
    {
        // 四元数 -> 矩阵
        Quaternion quat;
        initial_euler.toQuat(Euler::eZYX, quat);
        
        Matrix3d matrix;
        aQuatToMatrix(quat, matrix);
        std::cout << "转换到矩阵完成 " << std::endl;
    }
    
    {
        // 矩阵 -> 欧拉角 (完整循环)
        Quaternion quat;
        initial_euler.toQuat(Euler::eZYX, quat);
        
        Matrix3d matrix;
        aQuatToMatrix(quat, matrix);
        
        Euler final_euler;
        aMatrixToEuler(matrix, Euler::eZYX, final_euler);
        
        std::cout << "最终欧拉角: " << final_euler.angle1() << ", " 
                  << final_euler.angle2() << ", " << final_euler.angle3() << std::endl;
    }
    
    return 0;
}

Angle Range Description

The valid ranges of Euler angles differ depending on the rotation sequence type:

• Tait-Bryan angles (ABC sequence):

  • angle2 in the interval [-π/2, π/2]
  • angle1, angle3 in the interval [-π, π]

• Classic Euler angles (ABA sequence):

  • angle2 in the interval [0, π]
  • angle1, angle3 in the interval [-π, π]

Error Handling

Conversion functions return errc_t type to indicate operation status, and callers should check the return value to ensure successful conversion.

Dependencies

• AstGlobal.h: Project global definitions
• MathOperator.hpp: Mathematical operation functions
• Matrix3d, Vector3d: Matrix and vector types

API Reference

///
/// @file      AttitudeConvert.hpp
/// @brief     
/// @details   
/// @author    axel
/// @date      2026-03-05
/// @copyright 版权所有 (C) 2026-present, ast项目.
///
/// ast项目（https://github.com/space-ast/ast）
/// 本项目基于 Apache 2.0 开源许可证分发。
/// 您可在遵守许可证条款的前提下使用、修改和分发本软件。
/// 许可证全文请见：
/// 
///    http://www.apache.org/licenses/LICENSE-2.0
/// 
/// 重要须知：
/// 软件按"现有状态"提供，无任何明示或暗示的担保条件。
/// 除非法律要求或书面同意，作者与贡献者不承担任何责任。
/// 使用本软件所产生的风险，需由您自行承担。

#pragma once

#include "AstGlobal.h"
#include "AttitudeConvertProto.hpp"
#include "AttitudeConvertInline.hpp"