inner-space 0.3.0

#![no_std]
#![deny(missing_docs)]
/*!
Traits for vector inner products and common operations.

Provides `DotProduct` trait.
If the default dot product with scalar output is implemented for a type, the `InnerSpace` trait will be derived for it, which provides many useful helpers like `magnitude`, `normalize`, `project`, `reject`, `reflect`, `angle`, ...

Use this to build libraries generic over these trait, like rendering, physics, and vector math.
*/

use scalars::{InverseTrigonometry, One, Sqrt};

pub use vector_space::*;

/// This trait defines the dot product.
pub trait DotProduct<T = Self>: VectorSpace {
    /// The output type of the dot product.
    type Output;

    /// The dot product (contraction).
    fn dot(&self, other: &T) -> <Self as DotProduct<T>>::Output;

    /// The scalar product (positive-definite).
    ///
    /// Defaults to `dot`. Override for types where the dot product is not positive-definite
    /// (e.g. GA bivectors and rotors) so that `InnerSpace::magnitude` works correctly.
    fn scalar(&self, other: &T) -> <Self as DotProduct<T>>::Output {
        self.dot(other)
    }
}

impl DotProduct for f32 {
    type Output = Self;
    fn dot(&self, other: &Self) -> Self {
        *self * *other
    }
}
impl DotProduct for f64 {
    type Output = Self;
    fn dot(&self, other: &Self) -> Self {
        *self * *other
    }
}

/// This trait adds common vector operations to a vector space if the dot product is defined.
pub trait InnerSpace: DotProduct<Output = <Self as VectorSpace>::Scalar> {
    /// The squared magnitude.
    ///
    /// This is more efficient than calculating the magnitude.
    /// Useful if you need the squared magnitude anyway.
    #[inline]
    fn magnitude2(&self) -> Self::Scalar {
        self.scalar(self)
    }

    /// The magnitude of a vector.
    #[inline]
    fn magnitude(&self) -> Self::Scalar {
        self.magnitude2().sqrt()
    }

    /// The normalized vector.
    #[inline]
    fn normalize(self) -> Self {
        let mag = self.magnitude();
        self / mag
    }

    /// The angle between two vectors.
    #[inline]
    fn angle(&self, other: &Self) -> Self::Scalar {
        (self.dot(other) / (self.magnitude() * other.magnitude())).acos()
    }

    /// Sets the magnitude of a vector.
    #[inline]
    fn with_magnitude(self, magnitude: Self::Scalar) -> Self {
        let mag = self.magnitude();
        self * (magnitude / mag)
    }

    /// Sets the direction of a vector.
    #[inline]
    fn with_direction(self, dir: Self) -> Self {
        dir * self.magnitude()
    }

    /// The value of the vector along the specified axis.
    #[inline]
    fn query_axis(&self, dir: Self) -> Self::Scalar {
        self.dot(&dir.normalize())
    }

    /// Projects a vector onto an already normalized direction vector.
    #[inline]
    fn normalized_project(self, dir: Self) -> Self {
        let scalar = self.dot(&dir);
        dir * scalar
    }

    /// Projects a vector onto the specified direction vector.
    #[inline]
    fn project(self, dir: Self) -> Self {
        let ratio = self.dot(&dir) / dir.magnitude2();
        dir * ratio
    }

    /// Rejects a vector from an already normalized direction vector.
    #[inline]
    fn normalized_reject(self, dir: Self) -> Self {
        let scalar = self.dot(&dir);
        let proj = dir * scalar;
        self - proj
    }

    /// Rejects a vector from the specified direction vector.
    #[inline]
    fn reject(self, dir: Self) -> Self {
        let ratio = self.dot(&dir) / dir.magnitude2();
        self - dir * ratio
    }

    /// Reflects a vector from an already normalized direction vector.
    #[inline]
    fn normalized_reflect(self, dir: Self) -> Self {
        let scalar = self.dot(&dir);
        let proj = dir * scalar;
        proj * (Self::Scalar::one() + Self::Scalar::one()) - self
    }

    /// Reflects a vector from the specified direction vector.
    #[inline]
    fn reflect(self, dir: Self) -> Self {
        let ratio = self.dot(&dir) / dir.magnitude2();
        dir * ratio * (Self::Scalar::one() + Self::Scalar::one()) - self
    }
}

impl<T: DotProduct<Output = Self::Scalar>> InnerSpace for T {}

/// The distance between two points.
pub fn distance<T: AffineSpace>(a: T, b: T) -> <T::Diff as VectorSpace>::Scalar
where
    T::Diff: InnerSpace,
{
    (b - a).magnitude()
}

/// The squared distance between two points.
pub fn distance2<T: AffineSpace>(a: T, b: T) -> <T::Diff as VectorSpace>::Scalar
where
    T::Diff: InnerSpace,
{
    (b - a).magnitude2()
}

/// The normalized direction between two points.
pub fn direction<T: AffineSpace>(a: T, b: T) -> T::Diff
where
    T::Diff: InnerSpace,
{
    (b - a).normalize()
}