C-AML Attitude Math Library written in C

Overview

The Attitude Math Library is a C-based mathematical library designed for attitude control applications, providing robust support for quaternion operations, Euler angle conversions, direction cosine matrices (DCMs), and vector math. This library serves as a foundation for building attitude control systems in drones and robotics.

Read the compiled documentation for the current conventions, validation boundary, and generated C API.

---

Features

• Quaternion Operations:
  • Normalize, multiply, and invert quaternions.
  • Convert between quaternions, Euler angles, and DCMs.
  • Rotate vectors with both optimized and fully explicit formulations.
  • Convert quaternions to axis-angle form and interpolate with SLERP.
• Euler Angles:
  • Convert Euler angles to/from DCMs.
  • Convert Euler angles to/from quaternions.
• Direction Cosine Matrices (DCM):
  • Verify orthonormality with dcm_is_orthonormal.
  • Apply transformations to vectors.
• Vector Operations:
  • Compute addition, subtraction, dot products, and cross products.
  • Normalize vectors.
  • Calculate vector magnitude.
• Utility Functions:
  • Convert degrees to radians and vice versa.
  • Wrap angles to a specified range.

---

Purpose

The library is designed to:

1. Provide a reliable mathematical foundation for attitude control calculations.
2. Support developers and researchers in implementing and testing drone or robotic control systems.

---

Getting Started

Prerequisites

To use this library, you need:

• A C compiler (e.g., GCC or Clang)
• A Linux or Windows development environment

Installation

1. Clone the repository:

   git clone https://github.com/antshiv/attitudeMathLibrary.git
   cd attitudeMathLibrary

2. Build the library:

   make

3. Link the library to your project. Include the header files and link the compiled library binary during the build process.

The root Makefile is a small wrapper around CMake. It keeps CMake as the source of truth while making the common commands easier to remember:

make help
make test
make test-list
make test-list-details
make test-quaternion-relative
make test_quaternion_relative
make run_quaternion_relative

If you prefer raw CMake:

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

File Structure

• src/: Contains source files for the library.
• include/: Header files for the library.
• CMakeLists.txt: Build configuration.
• Makefile: Convenience wrapper for common CMake/CTest commands.
• README.md: Documentation (this file).

---

Usage

Library Functions

Recent updates expose additional helpers:

• quaternion_inverse, quaternion_to_axis_angle, quaternion_rotate_vector, and quaternion_rotate_vector_explicit are now part of the public API.
• quaternion_relative computes the current-to-target correction quaternion for control and tracking flows.
• quaternion_orientation_error_axis_angle converts that correction into a rotation axis and angle.
• dcm_is_orthonormal can be used to sanity-check direction cosine matrices before they enter control loops.
• Checked conversion APIs reject unsupported Euler orders, non-finite inputs, reflections, and malformed DCMs instead of silently returning plausible output.
• Use quaternion_set_explicit_debug(int enabled) to toggle verbose tracing inside quaternion_rotate_vector_explicit when teaching or debugging the q⊗v⊗q* sequence.

Quaternions

• Convert quaternion to DCM:

  double q[4] = {1.0, 0.0, 0.0, 0.0};
  double dcm[3][3];
  quaternion_to_dcm(q, dcm);

• Normalize a quaternion:

  quaternion_normalize(q);

• Compute the correction from current orientation to target orientation:

  double q_current[4]; // estimated drone/camera orientation
  double q_target[4];  // desired orientation
  double q_error[4];
   
  if (quaternion_relative(q_current, q_target, q_error)) {
      // q_target ~= q_error ⊗ q_current
  }

• Convert that correction into an axis-angle command:

  double axis[3];
  double angle;
   
  quaternion_orientation_error_axis_angle(q_current, q_target, axis, &angle);

Euler Angles

• Convert Euler angles to DCM:

  EulerAngles e = {roll, pitch, yaw, EULER_ZYX};
  euler_to_dcm(&e, dcm);

Vector Operations

• Compute cross product:

  double a[3] = {1.0, 0.0, 0.0};
  double b[3] = {0.0, 1.0, 0.0};
  double out[3];
  vector3_cross(a, b, out);

---

Building and Running Tests

All executables in tests/ are picked up automatically by CMake.

make

• Run the entire suite: make test
• List tests without executing: make test-list
• Explain what each test covers: make test-list-details
• Run the current-to-target quaternion test through CTest: make test-quaternion-relative or make test_quaternion_relative
• Build and run the current-to-target quaternion demo binary directly: make run-quaternion-relative or make run_quaternion_relative
• Run a specific binary directly, e.g. ./build/test_quaternion_rotate

Inside the generated build/ directory, the CMake target name is the executable name, not the source path. For example:

cd build
make test_quaternion_relative

not:

make tests/test_quaternion_relative

Educational demos

• test_quaternion_rotate compares the optimized and explicit rotation helpers to guard against regressions.
• test_quaternion_rotate_explicit_demo enables quaternion_set_explicit_debug(1) so you can watch each step in the explicit q⊗v⊗q* computation:

  ./build/test_quaternion_rotate_explicit_demo

  This is useful for walkthroughs or debugging orientation pipelines.

Embedded validation

attitude_validation_run() contains deterministic, heap-free fixtures shared by host CTest and the Zephyr sample. It checks ordinary rotations, 180-degree rotations, gimbal-lock orientations, quaternion/DCM/Euler reconstruction, and invalid-input rejection.

Build the sample for any supported Zephyr board:

west build -p always -b nrf5340dk_nrf5340_cpuapp samples/zephyr

This repository can also use the W530 as a remote build-and-flash station while source remains on the primary development laptop:

./scripts/validate_zephyr_remote.sh
BOARD=mimxrt1170_evk_cm7 ./scripts/validate_zephyr_remote.sh

The nRF5340 command builds, flashes J-Link probe 960169267, captures the stable if04 virtual serial port, and fails unless the board emits ATTITUDE_VALIDATION PASS. Other boards currently perform a cross-build only; add their probe and console contract before treating them as hardware evidence.

---

SEO Keywords

• Drone attitude control
• Quaternion math library
• Direction cosine matrices
• Euler angles to quaternion conversion
• C-based attitude library

---

Contributions

Contributions are welcome! Feel free to fork the repository, create a new branch, and submit a pull request. For major changes, open an issue to discuss your proposed modifications first.

---

License

The repository does not currently contain a license file. Until one is added, no open-source permission should be inferred from this source being public.

---

Contact

For questions, feedback, or collaboration, reach out to us at [antho.nosp@m.ny.s.nosp@m.hivak.nosp@m.umar.nosp@m.@ants.nosp@m.hiv..nosp@m.com].