Struct Vector3

Source

pub struct Vector3 {
    pub x: f64,
    pub y: f64,
    pub z: f64,
}

Expand description

A 3D Cartesian vector for coordinate calculations.

Used throughout the library for position vectors, direction vectors, and as intermediate representations during coordinate transformations.

§Fields

Components are public for direct access when performance matters:

x: First component (toward vernal equinox in equatorial coordinates)
y: Second component (90° east in equatorial coordinates)
z: Third component (toward celestial pole in equatorial coordinates)

§Construction

use celestial_core::Vector3;

// Direct construction
let v = Vector3::new(1.0, 2.0, 3.0);

// Unit vectors along axes
let x = Vector3::x_axis();
let y = Vector3::y_axis();
let z = Vector3::z_axis();

// From spherical coordinates (RA, Dec in radians)
let star = Vector3::from_spherical(0.5, 0.3);

// From an array
let v = Vector3::from_array([1.0, 2.0, 3.0]);

Fields§

§x: f64§y: f64§z: f64

Implementations§

Source §

impl Vector3

Source

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

Creates a new vector from x, y, z components.

Source

pub fn zeros() -> Self

Returns the zero vector [0, 0, 0].

Source

pub fn x_axis() -> Self

Returns the unit vector along the X axis [1, 0, 0].

In equatorial coordinates, this points toward the vernal equinox.

Source

pub fn y_axis() -> Self

Returns the unit vector along the Y axis [0, 1, 0].

In equatorial coordinates, this is 90° east of the vernal equinox on the equator.

Source

pub fn z_axis() -> Self

Returns the unit vector along the Z axis [0, 0, 1].

In equatorial coordinates, this points toward the north celestial pole.

Source

pub fn get(&self, index: usize) -> AstroResult<f64>

Returns the component at the given index (0=x, 1=y, 2=z).

Returns an error for indices outside 0-2. For unchecked access, use indexing syntax v[i] or the public fields directly.

Source

pub fn set(&mut self, index: usize, value: f64) -> AstroResult<()>

Sets the component at the given index (0=x, 1=y, 2=z).

Returns an error for indices outside 0-2. For unchecked access, use indexing syntax v[i] = value or the public fields directly.

Source

pub fn magnitude(&self) -> f64

Returns the Euclidean length (L2 norm) of the vector.

For a unit vector, this returns 1.0. For the zero vector, returns 0.0.

Source

pub fn magnitude_squared(&self) -> f64

Returns the squared magnitude.

Faster than magnitude when you only need to compare lengths or don’t need the actual distance.

Source

pub fn normalize(&self) -> Self

Returns a unit vector pointing in the same direction.

If the vector has zero length, returns the zero vector unchanged (avoids NaN).

use celestial_core::Vector3;

let v = Vector3::new(3.0, 4.0, 0.0);
let unit = v.normalize();
assert!((unit.magnitude() - 1.0).abs() < 1e-15);
assert_eq!(unit, Vector3::new(0.6, 0.8, 0.0));

Source

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

Computes the dot product (inner product) with another vector.

For unit vectors, this equals the cosine of the angle between them: a.dot(&b) = cos(θ). Use this to compute angular separation between celestial positions.

use celestial_core::Vector3;

let a = Vector3::x_axis();
let b = Vector3::y_axis();
assert_eq!(a.dot(&b), 0.0);  // Perpendicular

let c = Vector3::new(1.0, 2.0, 3.0);
let d = Vector3::new(4.0, 5.0, 6.0);
assert_eq!(c.dot(&d), 32.0);  // 1*4 + 2*5 + 3*6

Source

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

Computes the cross product with another vector.

The result is perpendicular to both input vectors, with direction given by the right-hand rule. The magnitude equals |a||b|sin(θ).

use celestial_core::Vector3;

let x = Vector3::x_axis();
let y = Vector3::y_axis();
let z = x.cross(&y);
assert_eq!(z, Vector3::z_axis());  // X × Y = Z

Source

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

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

Source

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

Creates a vector from a [f64; 3] array.

Source

pub fn from_spherical(ra: f64, dec: f64) -> Self

Creates a unit vector from spherical coordinates.

ra: Azimuthal angle from +X toward +Y (right ascension), in radians
dec: Elevation from XY plane (declination), in radians

The result is always a unit vector (magnitude = 1).

use celestial_core::Vector3;
use std::f64::consts::FRAC_PI_2;

// RA=0, Dec=0 → points along +X
let v = Vector3::from_spherical(0.0, 0.0);
assert!((v.x - 1.0).abs() < 1e-15);

// RA=90°, Dec=0 → points along +Y
let v = Vector3::from_spherical(FRAC_PI_2, 0.0);
assert!((v.y - 1.0).abs() < 1e-15);

// RA=0, Dec=90° → points along +Z (north pole)
let v = Vector3::from_spherical(0.0, FRAC_PI_2);
assert!((v.z - 1.0).abs() < 1e-15);

Source

pub fn to_spherical(&self) -> (f64, f64)

Converts the vector to spherical coordinates (θ, φ).

Returns (theta, phi) where:

theta: Azimuthal angle from +X toward +Y (like RA), in radians (-π, π]
phi: Elevation from XY plane (like Dec), in radians [-π/2, π/2]

The vector does not need to be normalized; direction is preserved regardless of magnitude. For the zero vector, returns (0.0, 0.0).

use celestial_core::Vector3;
use std::f64::consts::FRAC_PI_2;

let v = Vector3::new(0.0, 0.0, 1.0);  // North pole
let (theta, phi) = v.to_spherical();
assert_eq!(theta, 0.0);
assert_eq!(phi, FRAC_PI_2);