Struct Position 

pub struct Position<C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit> { /* private fields */ }

An affine point in 3D Cartesian coordinates.

Positions represent locations in space relative to a reference center (origin). Unlike vectors, positions do not form a vector space.

Type Parameters

• C: The reference center (e.g., Heliocentric, Geocentric, Topocentric)
• F: The reference frame (e.g., ICRS, EclipticMeanJ2000, Equatorial)
• U: The length unit (e.g., AstronomicalUnit, Kilometer)

Center Parameters

Some centers (like Topocentric) require runtime parameters stored in C::Params. For most centers, Params = () (zero overhead).

Implementations

impl<C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit> Position<C, F, U>

pub fn new_with_params<T: Into<Quantity<U>>>( center_params: C::Params, x: T, y: T, z: T, ) -> Self

Creates a new position with explicit center parameters.

Arguments

• center_params: Runtime parameters for the center (e.g., ObserverSite for Topocentric)
• x, y, z: Component values (converted to Quantity<U>)

pub fn from_vec3(center_params: C::Params, vec3: Vector3<Quantity<U>>) -> Self

Creates a position from a nalgebra Vector3 with explicit center parameters.

pub const fn new_const( center_params: C::Params, x: Quantity<U>, y: Quantity<U>, z: Quantity<U>, ) -> Self

Const constructor for use in const contexts.

pub fn center_params(&self) -> &C::Params

Returns a reference to the center parameters.

impl<C, F, U> Position<C, F, U>

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

pub const CENTER: Self

The origin of this coordinate system (all coordinates zero).

pub fn new<T: Into<Quantity<U>>>(x: T, y: T, z: T) -> Self

Creates a new position for centers with Params = ().

This is a convenience constructor that doesn’t require passing () explicitly.

Example

use affn::cartesian::Position;
use affn::frames::ReferenceFrame;
use affn::centers::ReferenceCenter;
use qtty::*;

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

#[derive(Debug, Copy, Clone)]
struct WorldOrigin;
impl ReferenceCenter for WorldOrigin {
    type Params = ();
    fn center_name() -> &'static str { "WorldOrigin" }
}

let pos = Position::<WorldOrigin, WorldFrame, Meter>::new(1.0, 0.0, 0.0);

pub fn from_vec3_origin(vec3: Vector3<Quantity<U>>) -> Self

Creates a position from a nalgebra Vector3 for centers with Params = ().

impl<C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit> Position<C, F, U>

pub fn x(&self) -> Quantity<U>

Returns the x-component.

pub fn y(&self) -> Quantity<U>

Returns the y-component.

pub fn z(&self) -> Quantity<U>

Returns the z-component.

pub fn as_vec3(&self) -> &Vector3<Quantity<U>>

Returns the underlying nalgebra Vector3.

pub fn to_unit<U2: LengthUnit>(&self) -> Position<C, F, U2>

where C::Params: Clone,

Converts this position to another length unit.

The center and frame are preserved while each Cartesian component is converted independently via qtty::Quantity::to.

impl<C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit> Position<C, F, U>

pub fn distance(&self) -> Quantity<U>

Computes the distance from the reference center.

pub fn distance_to(&self, other: &Self) -> Quantity<U>

where C::Params: PartialEq,

Computes the distance to another position in the same center and frame.

Panics

Panics if the positions have different center parameters. For a non-panicking alternative, use try_distance_to.

Note on Parameterized Centers

For centers with Params = () (e.g., Geocentric, Heliocentric), this check is a compile-time guarantee and has zero runtime cost. For parameterized centers (e.g., Topocentric with ObserverSite), the check is performed at runtime.

pub fn try_distance_to( &self, other: &Self, ) -> Result<Quantity<U>, CenterParamsMismatchError>

where C::Params: PartialEq,

Checked version of distance_to that returns Err instead of panicking when center parameters don’t match.

For centers with Params = (), this always succeeds.

pub fn direction(&self) -> Option<Direction<F>>

Returns the direction (unit vector) from the center to this position.

Note: Directions are frame-only types (no center). This extracts the normalized direction of the position vector.

Returns None if the position is at the origin.

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

Returns the direction, assuming non-zero distance from origin.

Panics

May produce NaN if the position is at the origin.

pub fn to_spherical(&self) -> Position<C, F, U>

Converts this Cartesian position to spherical coordinates.

Returns a spherical position with the same center and frame, with (polar, azimuth, distance) computed from (x, y, z).

pub fn from_spherical(sph: &Position<C, F, U>) -> Self

Constructs a Cartesian position from spherical coordinates.

This is equivalent to spherical_pos.to_cartesian().

impl<C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit> Position<C, F, U>

pub fn checked_sub( &self, other: &Self, ) -> Result<Displacement<F, U>, CenterParamsMismatchError>

where C::Params: PartialEq,

Checked subtraction that returns Err instead of panicking when center parameters don’t match.

This is the safe alternative to the Sub operator (pos_a - pos_b). For centers with Params = (), this always succeeds.

Trait Implementations

impl<C, F, U> Add<Vector<F, U>> for Position<C, F, U>

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit,

fn add(self, displacement: Displacement<F, U>) -> Self::Output

Translates the position by a displacement vector.

type Output = Position<C, F, U>

The resulting type after applying the + operator.

impl<C: Clone + ReferenceCenter, F: Clone + ReferenceFrame, U: Clone + LengthUnit> Clone for Position<C, F, U>

where C::Params: Clone,

fn clone(&self) -> Position<C, F, U>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Debug + ReferenceCenter, F: Debug + ReferenceFrame, U: Debug + LengthUnit> Debug for Position<C, F, U>

where C::Params: Debug,

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

Formats the value using the given formatter.

impl<C, F, U> Display for Position<C, F, U>

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit, Quantity<U>: Display,

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

Formats the value using the given formatter.

impl<C, F, U> Sub<&Position<C, F, U>> for &Position<C, F, U>

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit,

fn sub(self, other: &Position<C, F, U>) -> Self::Output

Computes the displacement vector from other to self.

Panics

Panics if the positions have different center parameters.

type Output = Vector<F, U>

The resulting type after applying the - operator.

impl<C, F, U> Sub<Vector<F, U>> for Position<C, F, U>

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit,

fn sub(self, displacement: Displacement<F, U>) -> Self::Output

Translates the position backwards by a displacement vector.

type Output = Position<C, F, U>

The resulting type after applying the - operator.

impl<C, F, U> Sub for Position<C, F, U>

where C: ReferenceCenter, F: ReferenceFrame, U: LengthUnit,

fn sub(self, other: Self) -> Self::Output

Computes the displacement vector from other to self.

Panics

Panics if the positions have different center parameters. For a non-panicking alternative, use Position::checked_sub.

type Output = Vector<F, U>

The resulting type after applying the - operator.

impl<C: Copy + ReferenceCenter, F: Copy + ReferenceFrame, U: Copy + LengthUnit> Copy for Position<C, F, U>

where C::Params: Copy,