Struct Direction 

pub struct Direction(/* private fields */);

A unit vector in space.

Implementations

impl Direction

pub const X: Self

+X.

pub const Y: Self

+Y.

pub const Z: Self

+Z.

pub fn new(v: Vector, tol: Tolerances) -> OgeomResult<Self>

Normalize v into a direction.

Errors

OgeomError::Construction if v is non-finite or shorter than tol.confusion().

pub fn from_coords(x: f64, y: f64, z: f64, tol: Tolerances) -> OgeomResult<Self>

Normalize components into a direction.

Errors

As Direction::new.

pub fn unit(v: Vector, tol: Tolerances) -> OgeomResult<Self>

A direction from a vector that is already a unit vector.

Checks rather than normalizes, and the distinction is the whole reason it exists: dividing a unit vector by its own magnitude does not give it back, it gives something a bit or two away. That is invisible until something has to reproduce a direction exactly: reading a document back from a file, above all, where the drift turns a round trip that should be the identity into one that changes the model a little every time.

Errors

OgeomError::Construction if v is non-finite, or its length differs from one by more than tol.confusion().

pub const fn vector(self) -> Vector

The underlying unit vector.

pub const fn x(self) -> f64

X component.

pub const fn y(self) -> f64

Y component.

pub const fn z(self) -> f64

Z component.

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

Components as an array.

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

Dot product with another direction: the cosine of the angle between them, in [-1, 1] up to rounding.

pub fn dot_vector(self, v: Vector) -> f64

Dot product with a free vector.

pub fn cross_vector(self, other: Self) -> Vector

Cross product, as a free vector. Its magnitude is the sine of the angle between the two directions, so it is not itself a direction; for nearly parallel inputs it is nearly null.

pub fn cross_with(self, v: Vector) -> Vector

Cross product with a free vector.

Its magnitude is the component of v perpendicular to this direction, which makes it the accurate way to get a perpendicular distance: subtracting the parallel component instead cancels catastrophically for a point far along the direction.

pub fn cross(self, other: Self, tol: Tolerances) -> OgeomResult<Self>

Cross product, renormalized into a direction.

Collinearity is judged against the angular tolerance, not the linear one: for unit inputs the cross product’s magnitude is the sine of the angle between them, a dimensionless quantity that a length tolerance does not describe.

Errors

OgeomError::Construction if the two directions are collinear.

pub fn from_cross(a: Vector, b: Vector, tol: Tolerances) -> OgeomResult<Self>

The unit normal to two free vectors.

The right way to build a normal from two edges of a triangle. Naively normalizing a.cross(b) compares its magnitude (which is twice the triangle’s area, and so scales as the square of the size) against a length tolerance. A triangle a micron across then looks degenerate even though its normal is perfectly well determined. The test here is relative: |a x b| > tol.angular() * |a| * |b|, which asks the question that actually matters, whether the two vectors are collinear, and gives the same answer at every scale.

Errors

OgeomError::Construction if a and b are collinear, or either is null.

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

Angle to other, in [0, π].

pub fn is_equal(self, other: Self, tol: Tolerances) -> bool

Whether the two point the same way, within tol.angular().

pub fn is_opposite(self, other: Self, tol: Tolerances) -> bool

Whether the two point opposite ways, within tol.angular().

pub fn is_parallel(self, other: Self, tol: Tolerances) -> bool

Whether the two are parallel, ignoring sense.

pub fn is_normal(self, other: Self, tol: Tolerances) -> bool

Whether the two are perpendicular, within tol.angular().

pub fn any_perpendicular(self) -> Self

Some direction perpendicular to this one.

Which one is unspecified but deterministic. Chosen by crossing with whichever axis this direction is least aligned with, so the cross product is never near-degenerate and the result is numerically sound for every input.

pub const fn reversed(self) -> Self

This direction reflected through the origin.

pub fn to_2d(self, tol: Tolerances) -> OgeomResult<Direction2>

This direction with the Z component dropped, renormalized.

Errors

OgeomError::Construction if this direction is parallel to Z, leaving nothing to project.

Trait Implementations

impl Clone for Direction

fn clone(&self) -> Direction

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Direction

impl Debug for Direction

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

Formats the value using the given formatter.

impl From<Direction> for Vector

fn from(d: Direction) -> Self

Converts to this type from the input type.

impl Mul<Direction> for f64

type Output = Vector

The resulting type after applying the * operator.

fn mul(self, d: Direction) -> Vector

Performs the * operation.

impl Mul<f64> for Direction

fn mul(self, s: f64) -> Vector

Scaling a direction yields a free vector: the result is no longer unit length, so it is no longer a direction.

type Output = Vector

The resulting type after applying the * operator.

impl Neg for Direction

type Output = Direction

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl PartialEq for Direction

fn eq(&self, other: &Direction) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Direction