Skip to content

Orientation Workflow

This example illustrates an orientation estimation workflow using qsp-orientation.

Note

This is a conceptual example. Code snippets are illustrative. Verify against the current package API before use.

Overview

qsp-orientation provides tools for estimating and tracking the attitude (orientation) of a rigid body from sensor data. The output is a sequence of quaternion-valued orientation estimates that describe the platform's rotation relative to a reference frame.

Scenario

You have raw 6-DOF IMU data (3-axis accelerometer + 3-axis gyroscope) sampled at 200 Hz and want to:

  1. Condition the data to remove noise
  2. Estimate the platform orientation at each time step
  3. Inspect the result

Load and condition sensor data

# Conceptual example — not a tested API call
import numpy as np
import qsp_core
import qsp_filter
import qsp_orientation

# Load IMU data
# Shape: (N, 6) — columns: [ax, ay, az, gx, gy, gz]
imu_raw = np.load("imu_data.npy")
sample_rate_hz = 200.0

# Separate accelerometer and gyroscope components
accel = imu_raw[:, :3]
gyro  = imu_raw[:, 3:]

# Construct QSP signals
accel_sig = qsp_core.VectorSignal(accel, sample_rate_hz=sample_rate_hz)
gyro_sig  = qsp_core.VectorSignal(gyro,  sample_rate_hz=sample_rate_hz)

# Apply low-pass filter to reduce noise
accel_filt = qsp_filter.lowpass(accel_sig, cutoff_hz=20.0)
gyro_filt  = qsp_filter.lowpass(gyro_sig,  cutoff_hz=20.0)

Estimate orientation

# Conceptual example
estimator = qsp_orientation.AttitudeEstimator(
    method="complementary",  # or "madgwick", "mahony", etc.
    sample_rate_hz=sample_rate_hz,
)

orientations = estimator.estimate(
    accel=accel_filt,
    gyro=gyro_filt,
)

# `orientations` is a sequence of unit quaternions
print(f"Estimated {len(orientations)} orientation samples")
print(f"First quaternion: {orientations[0]}")

Inspect results

# Extract Euler angles for inspection (if needed)
# Note: Euler angles have singularities — prefer quaternions for computation
euler_angles = qsp_orientation.to_euler(orientations, convention="ZYX")

print("Roll, Pitch, Yaw at final sample:")
print(f"  {euler_angles[-1]}")

Notes

  • Quaternion-based estimation avoids gimbal lock and is preferred for all computation. Convert to Euler angles only for display or logging.
  • The available estimator methods depend on the qsp-orientation package version. Refer to the package docs for the current method list.
  • Initial orientation (reference frame alignment) may require a static calibration period at startup.