embedded-so3-f32

Représentation et manipulation du groupe de rotation SO(3) via des quaternions unitaires, optimisée pour les systèmes embarqués no_std.

Ce projet garantit des rotations 3D stables, sans blocage de cardan (gimbal lock), sans utilisation de la bibliothèque standard (std) et sans aucune section unsafe.

✨ Caractéristiques

no_std : Conçu pour le bare-metal (Cortex-M, RISC-V, etc.).
Zéro unsafe : Sécurité mémoire totale garantie par le compilateur Rust.
Stabilité numérique : Ré-normalisation systématique lors des compositions pour éviter la dérive flottante.
Performance : Formule de Rodrigues pour l'application des rotations (15 multiplications au lieu de 28).
Robuste : Gestion stricte des erreurs via So3Error (rejet des NaN, ±inf et normes nulles).

🚀 Utilisation rapide

Ajoutez à votre Cargo.toml :

[dependencies]
embedded-so3-f32 = "0.1.0"

Exemple de rotation

use embedded_so3_f32::{Rotation, So3Error};

fn main() -> Result<(), So3Error> {
    // Rotation de 90° autour de l'axe Y
    // Quaternion : [w = cos(45°), x = 0, y = sin(45°), z = 0]
    let s = core::f32::consts::FRAC_1_SQRT_2;
    let rot_y = Rotation::new(s, 0.0, s, 0.0)?;

    // Vecteur initial sur l'axe X
    let v = [1.0_f32, 0.0, 0.0];

    // Application de la rotation
    let v_prime = rot_y.rotate_vector(v);
    // v_prime ≈ [0.0, 0.0, -1.0]  (système main droite)

    Ok(())
}

Composition avec l'opérateur `*`

let s = core::f32::consts::FRAC_1_SQRT_2;
let r90 = Rotation::new(s, s, 0.0, 0.0)?;  // 90° autour de X

let r180 = (r90 * r90)?;                    // 180° autour de X
let back = (r180 * r90.inverse())?;         // retour à 90°

🛠 API

Méthode / Constante	Description
`Rotation::new(w, x, y, z)`	Crée une rotation normalisée. Retourne `Err` si les entrées sont invalides.
`Rotation::IDENTITY`	Constante pour la rotation nulle `[1, 0, 0, 0]`.
`compose(&other)`	Compose deux rotations : `self ∘ other`.
`r1 * r2`	Sucre syntaxique pour `compose` (par valeur ou par référence).
`rotate_vector([x, y, z])`	Applique la rotation à un vecteur `[f32; 3]`.
`inverse()`	Retourne la rotation inverse (conjugué, sans coût de normalisation).
`as_array()`	Retourne les composants bruts sous la forme `[w, x, y, z]`.

⚠️ Gestion des erreurs

pub enum So3Error {
    InvalidNorm,      // norme nulle ou trop proche de zéro
    NonFiniteValue,   // NaN ou ±infini détecté
}

Toutes les fonctions qui peuvent échouer retournent Result<Rotation, So3Error>.
inverse() et rotate_vector() sont infaillibles car elles opèrent sur des quaternions déjà validés.

⚖️ Licence

Ce programme est un logiciel libre : vous pouvez le redistribuer et/ou le modifier selon les termes de la Licence Publique Générale GNU telle que publiée par la Free Software Foundation, soit la version 2 de la licence, soit (à votre choix) n'importe quelle version ultérieure.

Ce programme est distribué dans l'espoir qu'il sera utile, mais sans aucune garantie ; sans même la garantie implicite de commercialisation ou d'adéquation à un usage particulier. Voir la Licence Publique Générale GNU pour plus de détails.

embedded-so3-f32 0.1.0