Struct Direction 

pub struct Direction<F: ReferenceFrame> { /* private fields */ }

A unit vector representing orientation in 3D space.

Directions are frame-dependent but center-independent (free vectors). The internal storage is a Vector3<f64> with magnitude 1 (dimensionless).

Type Parameters

• F: The reference frame (e.g., ICRS, EclipticMeanJ2000, Equatorial)

Invariants

All public constructors ensure the direction is normalized. For unchecked construction, use from_xyz_unchecked.

Zero-Cost Abstraction

This type is #[repr(transparent)] over XYZ<f64>, ensuring no runtime overhead compared to raw Vector3<f64>.

Renormalization Policy

The Mul<Direction> implementation for crate::Rotation3 uses Direction::new_unchecked internally and does not auto-renormalize the result. A single rotation preserves the unit-norm invariant to within machine epsilon, but long composition chains (r_n * ... * r_2 * r_1 * dir) accumulate floating-point error and the magnitude will drift away from 1.0. For pipelines that apply many rotations in sequence (e.g. integrators, repeated frame transforms), call renormalize or renormalized periodically to restore the invariant.

Implementations

impl<F: ReferenceFrame> Direction<F>

pub fn new(x: f64, y: f64, z: f64) -> Self

Creates a direction from components, normalizing to unit length.

Panics

Panics if the input vector has zero magnitude (cannot normalize a zero vector). Use Direction::try_new for fallible construction when the input may be zero.

Example

use affn::cartesian::Direction;
use affn::frames::ReferenceFrame;

#[derive(Debug, Copy, Clone)]
struct WorldFrame;
impl ReferenceFrame for WorldFrame {
    fn frame_name() -> &'static str { "WorldFrame" }
}

let dir = Direction::<WorldFrame>::new(3.0, 4.0, 0.0);
assert!((dir.x() - 0.6).abs() < 1e-12);
assert!((dir.y() - 0.8).abs() < 1e-12);

pub fn try_new(x: f64, y: f64, z: f64) -> Option<Self>

Attempts to create a direction, returning None if the input is zero.

pub fn normalize(x: f64, y: f64, z: f64) -> Self

Creates a direction from components (alias for new).

Provided for API symmetry with earlier versions.

pub fn from_array(v: [f64; 3]) -> Self

Creates a direction from a [f64; 3] array, normalizing to unit length.

impl<F: ReferenceFrame> Direction<F>

pub fn new_unchecked(x: f64, y: f64, z: f64) -> Self

Creates a direction from raw components without normalization.

Safety

The caller must ensure the components form a unit vector.

impl<F: ReferenceFrame> Direction<F>

pub fn renormalize(&mut self)

Restores the unit-norm invariant in place.

Divides each component by the current magnitude. If the magnitude is non-finite (NaN or infinite) or smaller than f64::EPSILON, the value is left unchanged rather than panicking or producing NaNs.

Use this after long chains of Rotation3 * Direction operations to counteract accumulated floating-point drift.

pub fn renormalized(self) -> Self

By-value variant of renormalize.

Returns a renormalized copy of self. If the current magnitude is non-finite or below f64::EPSILON, the original value is returned unchanged.

impl<F: ReferenceFrame> Direction<F>

pub fn x(&self) -> f64

Returns the x-component.

pub fn y(&self) -> f64

Returns the y-component.

pub fn z(&self) -> f64

Returns the z-component.

pub fn as_array(&self) -> [f64; 3]

Returns the components as a [f64; 3] array.

pub fn reinterpret_frame<F2: ReferenceFrame>(self) -> Direction<F2>

Reinterprets this direction as belonging to a different reference frame.

This is a zero-cost operation: the unit-vector components are preserved unchanged; only the compile-time frame tag is replaced.

Use after applying a mathematical rotation whose result still carries the original frame tag.

impl<F: ReferenceFrame> Direction<F>

pub fn scale<U: LengthUnit>(&self, magnitude: Quantity<U>) -> Displacement<F, U>

Scales the direction by a length to produce a displacement vector.

Example

use affn::cartesian::Direction;
use affn::frames::ReferenceFrame;
use qtty::units::*; use qtty::{Quantity, M, KM, DEG, RAD, SEC}; use qtty::angular::{Degrees, Radians}; use qtty::length::{Meters, Kilometers};

#[derive(Debug, Copy, Clone)]
struct WorldFrame;
impl ReferenceFrame for WorldFrame {
    fn frame_name() -> &'static str { "WorldFrame" }
}

let dir = Direction::<WorldFrame>::new(1.0, 0.0, 0.0);
let vec = dir.scale(5.0 * M);
assert!((vec.x().value() - 5.0).abs() < 1e-12);

pub fn position<C, U>(&self, magnitude: Quantity<U>) -> Position<C, F, U>

where C: ReferenceCenter<Params = ()>, U: LengthUnit,

Creates a position at the given distance from the origin in this direction.

For centers with Params = (), this is a convenience method.

pub fn position_with_params<C, U>( &self, center_params: C::Params, magnitude: Quantity<U>, ) -> Position<C, F, U>

where C: ReferenceCenter, U: LengthUnit,

Creates a position with explicit center parameters.

impl<F: ReferenceFrame> Direction<F>

pub fn dot(&self, other: &Self) -> f64

Computes the dot product with another direction.

Returns cosine of the angle between directions (range: -1 to 1).

pub fn cross(&self, other: &Self) -> Option<Self>

Computes the cross product with another direction.

The result is normalized if non-zero (perpendicular directions).

pub fn negate(&self) -> Self

Negates the direction (points in opposite direction).

pub fn angle_to(&self, other: &Self) -> f64

Returns the angle between this direction and another, in radians.

impl<F: ReferenceFrame> Direction<F>

pub fn to_spherical(&self) -> Direction<F>

Converts this Cartesian direction to spherical coordinates.

Returns a spherical direction with polar (latitude) and azimuth (longitude) angles in degrees. Angles are canonicalized to:

• polar in [-90°, +90°]
• azimuth in [0°, 360°)

impl<F: ReferenceFrame> Direction<F>

pub fn display(&self) -> String

Returns a formatted string representation.

Trait Implementations

impl<F: Clone + ReferenceFrame> Clone for Direction<F>

fn clone(&self) -> Direction<F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug + ReferenceFrame> Debug for Direction<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F> Display for Direction<F>

where F: ReferenceFrame,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F> LowerExp for Direction<F>

where F: ReferenceFrame,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: ReferenceFrame, U: LengthUnit> Mul<&Direction<F>> for &Quantity<U>

type Output = <Quantity<U> as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<&Direction<F>> for &Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<&Direction<F>> for Quantity<U>

type Output = <Quantity<U> as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<&Direction<F>> for Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Direction<F>) -> <Self as Mul<&Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<&Quantity<U>> for &Direction<F>

type Output = <Direction<F> as Mul<Quantity<U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Quantity<U>) -> <Self as Mul<&Quantity<U>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<&Quantity<U>> for Direction<F>

type Output = <Direction<F> as Mul<Quantity<U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &Quantity<U>) -> <Self as Mul<&Quantity<U>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<Direction<F>> for &Quantity<U>

type Output = <Quantity<U> as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Direction<F>) -> <Self as Mul<Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<Direction<F>> for &Rotation3

type Output = <Rotation3 as Mul<Direction<F>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Direction<F>) -> <Self as Mul<Direction<F>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<Direction<F>> for Quantity<U>

type Output = Vector<F, U>

The resulting type after applying the * operator.

fn mul(self, dir: Direction<F>) -> Self::Output

Performs the * operation.

impl<F: ReferenceFrame> Mul<Direction<F>> for Rotation3

Rotation3 * Direction<F> — rotates a unit direction, preserving frame.

Translations do not apply to directions; only rotation changes their orientation. The result is guaranteed to remain a unit vector because rotation preserves norms.

type Output = Direction<F>

The resulting type after applying the * operator.

fn mul(self, rhs: Direction<F>) -> Direction<F>

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<Quantity<U>> for &Direction<F>

type Output = <Direction<F> as Mul<Quantity<U>>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Quantity<U>) -> <Self as Mul<Quantity<U>>>::Output

Performs the * operation.

impl<F: ReferenceFrame, U: LengthUnit> Mul<Quantity<U>> for Direction<F>

type Output = Vector<F, U>

The resulting type after applying the * operator.

fn mul(self, magnitude: Quantity<U>) -> Self::Output

Performs the * operation.

impl<F> UpperExp for Direction<F>

where F: ReferenceFrame,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Copy + ReferenceFrame> Copy for Direction<F>