Struct PlaneFrame

pub struct PlaneFrame { /* private fields */ }

An origin and a right-handed orthonormal pair of in-plane axes.

Invariant

A PlaneFrame that exists is orthonormal within the tolerance it was built with. project and lift are exact inverses on that basis, so the type cannot be used to produce the silently wrong coordinates a skewed basis yields.

The fields are private precisely because the invariant is the point: a public x would let a caller reassign one axis and keep the type.

Implementations

impl PlaneFrame

pub const fn ground() -> PlaneFrame

The z = 0 ground plane with the world x and y axes.

pub fn new( origin: DVec3, x: DVec3, y: DVec3, tolerance: Tolerance, ) -> Result<PlaneFrame, FrameError>

Validate a basis and build a frame from it.

Unit length and perpendicularity are both DIMENSIONLESS comparisons, so both use the ANGULAR tolerance. Using the linear tolerance here would make a pure direction test scale with the model length unit: the same skewed basis would be refused in metres and accepted in millimetres.

Errors

Returns FrameError naming which property failed, so a caller can report the cause rather than a bare rejection.

pub fn project(&self, point: DVec3) -> DVec2

Map a model-space point to its in-plane coordinates.

Points off the plane project ONTO it: the out-of-plane component is discarded, not reported. Use signed_distance when the caller needs to know how far off the plane the point was.

pub fn lift(&self, point: DVec2) -> DVec3

Map in-plane coordinates back to model space.

pub fn signed_distance(&self, point: DVec3) -> f64

Signed distance from the plane, positive along the normal.

pub fn normal(&self) -> DVec3

The right-handed normal, x cross y.

Derived rather than stored: a stored normal is a third value that can disagree with the axes, which is the inconsistency this type exists to prevent.

pub fn from_normal( origin: DVec3, normal: DVec3, tolerance: Tolerance, ) -> Result<PlaneFrame, FrameError>

Build a frame from a normal, choosing an arbitrary in-plane x axis.

Use when the caller cares about the PLANE but not about which in-plane direction is x, such as sectioning. When the x direction is meaningful (a drawing’s horizontal, a wall’s length), pass it explicitly via new instead of accepting whatever this picks.

Errors

Returns FrameError when the normal is non-finite or too short to normalize.

pub const fn origin(&self) -> DVec3

The frame origin.

pub const fn x_axis(&self) -> DVec3

The in-plane axis mapped to the planar x coordinate.

pub const fn y_axis(&self) -> DVec3

The in-plane axis mapped to the planar y coordinate.

Trait Implementations

impl Clone for PlaneFrame

fn clone(&self) -> PlaneFrame

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for PlaneFrame

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

Formats the value using the given formatter.

impl PartialEq for PlaneFrame

fn eq(&self, other: &PlaneFrame) -> 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 Copy for PlaneFrame

impl StructuralPartialEq for PlaneFrame