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>.

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 is zero (cannot normalize).

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_vec3(vec: Vector3<f64>) -> Self

Creates a direction from a nalgebra Vector3, normalizing.

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 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_vec3(&self) -> Vector3<f64>

Returns the underlying nalgebra Vector3.

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::*;

#[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: ReferenceFrame> Display for Direction<F>

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

Formats the value using the given formatter.

impl<F: ReferenceFrame> LowerExp for Direction<F>

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 = Vector<F, U>

The resulting type after applying the * operator.

fn mul(self, dir: Direction<F>) -> Self::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: ReferenceFrame> UpperExp for Direction<F>

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

Formats the value using the given formatter.

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