Struct Coordinate 

pub struct Coordinate<In> { /* private fields */ }

Defines a point (ie, position) in the coordinate system specified by In.

You can construct one using Cartesian or spherical coordinates, or using bearing + range. You can also use the coordinate! macro for a concise constructor with named arguments.

Depending on the convention of the coordinate system (eg, NedLike, FrdLike, or RightHandedXyzLike), you’ll have different appropriately-named accessors for the coordinate’s cartesian components like Coordinate::ned_north or Coordinate::frd_front.

Note that this type implements Deserialize despite having unsafe constructors – this is because doing otherwise would be extremely unergonomic. However, when deserializing, the coordinate system of the deserialized value is not checked, so this is a foot-gun to be mindful of.

Implementations

impl<In> Coordinate<In>

pub fn build(components: <In::Convention as HasComponents>::Components) -> Self

where In: CoordinateSystem, In::Convention: HasComponents,

Constructs a coordinate at the given (x, y, z) Cartesian point in the CoordinateSystem In.

pub fn builder() -> Builder<In, Unset, Unset, Unset>

where In: CoordinateSystem,

Provides a constructor for a Coordinate in the CoordinateSystem In.

pub fn from_cartesian( x: impl Into<Length>, y: impl Into<Length>, z: impl Into<Length>, ) -> Self

👎Deprecated: prefer Coordinate::builder to avoid risk of argument order confusion

Constructs a coordinate at the given (x, y, z) Cartesian point in the CoordinateSystem In.

Prefer Coordinate::builder, Coordinate::build, or coordinate to avoid risk of argument order confusion. This function will be removed in a future version of Sguaba in favor of those.

The meaning of x, y, and z is dictated by the CoordinateSystem::Convention of In. For example, in NedLike, x is North, y is East, and z is “down” (ie, orthogonal to the earth’s surface).

This method is permanently deprecated because it is particularly vulnerable to argument order confusion (eg, accidentally passing in the “down” component of a FRD coordinate first instead of last). Methods like Coordinate::builder and the coordinate! macro should be preferred instead, as they do not have this problem. However, this method is left for use-cases where those alternatives cannot be used, such as when writing code that is fully generic over the coordinate system, and thus cannot use the safer constructors provided by those APIs. If this applies to you, make sure you apply due diligence when writing out the argument ordering.

pub fn from_spherical( radius: impl Into<Length>, polar: impl Into<Angle>, azimuth: impl Into<Angle>, ) -> Self

Constructs a coordinate at the given (r, θ, φ) spherical point in the CoordinateSystem In.

This constructor follows the physics convention for spherical coordinates, which defines

• r as the radial distance, meaning the slant distance to origin;
• θ (theta) as the polar angle meaning the angle with respect to positive polar axis (Z); and
• φ (phi) as the azimuthal angle, meaning the angle of rotation from the initial meridian plane (positive X towards positive Y).

The axes and planes above are in turn dictated by the CoordinateSystem::Convention of In. For example, in NedLike, the polar angle is the angle relative to straight down and the azimuthal angle is the angle from North. In FrdLike, the polar angle is the angle relative to “down” and the azimuthal angle is the angle from forward.

Note that this convention does not necessarily match the conventions of each coordinate system. For example, in NedLike and FrdLike coordinate systems, we often talk about “azimuth and elevation”, but those are distinct from the spherical coordinates. In that context, the definition of azimuth (luckily) matches that of spherical coordinates, but elevation tends to be defined as the angle from the positive X axis rather than from the positive Z axis. If you want to define a coordinate based on azimuth and elevation, use Coordinate::from_bearing.

Examples

use approx::assert_relative_eq;
use sguaba::{coordinate, system, Coordinate};
use uom::si::f64::{Angle, Length};
use uom::si::{angle::degree, length::meter};

system!(struct Ned using NED);

let zero = Length::new::<meter>(0.);
let unit = Length::new::<meter>(1.);
assert_relative_eq!(
    Coordinate::<Ned>::from_spherical(unit, Angle::new::<degree>(0.), Angle::new::<degree>(0.)),
    coordinate!(n = zero, e = zero, d = unit),
);
assert_relative_eq!(
    Coordinate::<Ned>::from_spherical(unit, Angle::new::<degree>(90.), Angle::new::<degree>(0.)),
    coordinate!(n = unit, e = zero, d = zero),
);
assert_relative_eq!(
    Coordinate::<Ned>::from_spherical(unit, Angle::new::<degree>(90.), Angle::new::<degree>(90.)),
    coordinate!(n = zero, e = unit, d = zero),
);

pub fn from_bearing(bearing: Bearing<In>, range: impl Into<Length>) -> Self

where In: BearingDefined,

Constructs a coordinate at the given azimuth, elevation, and range in the CoordinateSystem In.

This constructor is based on the bearing as it defined by the implementation of BearingDefined for In. For NedLike and FrdLike coordinate systems, this is:

• azimuth is the angle clockwise as seen from “up” along the XY plane from the positive X axis (eg, North or Forward); and
• elevation is the angle towards Z from the XY plane; and
• r is the radial distance, meaning the slant distance to origin.

See also horizontal coordinate systems.

Examples

use approx::assert_relative_eq;
use sguaba::{coordinate, system, Bearing, Coordinate};
use uom::si::f64::{Angle, Length};
use uom::si::{angle::degree, length::meter};

system!(struct Ned using NED);

let zero = Length::new::<meter>(0.);
let unit = Length::new::<meter>(1.);
assert_relative_eq!(
    Coordinate::<Ned>::from_bearing(
      Bearing::builder()
        .azimuth(Angle::new::<degree>(0.))
        .elevation(Angle::new::<degree>(0.)).expect("elevation is in-range")
        .build(),
      unit
    ),
    coordinate!(n = unit, e = zero, d = zero),
);
assert_relative_eq!(
    Coordinate::<Ned>::from_bearing(
      Bearing::builder()
        .azimuth(Angle::new::<degree>(90.))
        .elevation(Angle::new::<degree>(0.)).expect("elevation is in-range")
        .build(),
      unit
    ),
    coordinate!(n = zero, e = unit, d = zero),
);
assert_relative_eq!(
    Coordinate::<Ned>::from_bearing(
      Bearing::builder()
        .azimuth(Angle::new::<degree>(90.))
        .elevation(Angle::new::<degree>(90.)).expect("elevation is in-range")
        .build(),
      unit
    ),
    coordinate!(n = zero, e = zero, d = -unit),
);

pub fn origin() -> Self

Constructs a coordinate at the origin of the coordinate system In.

Examples

use sguaba::{coordinate, system, Coordinate};
use uom::si::f64::{Length};
use uom::si::length::meter;

system!(struct Ned using NED);

let zero = Length::new::<meter>(0.);
assert_eq!(
    Coordinate::<Ned>::origin(),
    coordinate!(n = zero, e = zero, d = zero),
);

pub unsafe fn map_as_zero_in<To>(self) -> RigidBodyTransform<In, To>

Constructs a translation into CoordinateSystem To such that self is “zero” in To.

Less informally, if this translation is applied to this Coordinate<In>, it will yield Coordinate::origin in Coordination<To>.

Conversely, if the inverse of this translation is applied to Coordinate::origin in Orientation<To>, it will yield this Coordinate<In>.

Or, alternatively phrased, this yields a translation transformation that

1. takes a coordinate, vector, or orientation observed by the object with this position in the coordinate system In; and
2. returns that coordinate or vector as if it were observed in a coordinate system (To) where this Coordinate<In> is Coordinate::origin.

Or, if you prefer a more mathematical description: this defines the pose of the whole coordinate system To in In.

Safety

This method allows you to end up with erroneous transforms if you’re not careful. See Pose::map_as_zero_in for more details.

Specifically in the case of Coordinate, you are also asserting that only translation (ie, no rotation) is needed to convert from In to To.

Examples

use approx::assert_relative_eq;
use sguaba::{system, Bearing, Coordinate, engineering::Orientation, systems::Ecef};
use uom::si::f64::Length;
use uom::si::length::meter;

system!(struct PlaneCenteredEcef using right-handed XYZ);

// plane position in ECEF
let position = Coordinate::<Ecef>::builder()
    .x(Length::new::<meter>(30_000.))
    .y(Length::new::<meter>(25_000.))
    .z(Length::new::<meter>(19_000.))
    .build();


// plane observes something at a particular ECEF coordinate
let observation = Coordinate::<PlaneCenteredEcef>::builder()
    .x(Length::new::<meter>(1_000.))
    .y(Length::new::<meter>(6_000.))
    .z(Length::new::<meter>(0.))
    .build();

// if we now want this vector to be relative to the plane (ie, a direction
// of arrival vector), we need to map from one space to the other. so, we
// declare that the plane's position in ECEF is zero (ie, origin) in
// `PlaneCenteredEcef`:
let ecef_to_plane_centered_ecef = unsafe { position.map_as_zero_in::<PlaneCenteredEcef>() };

// this transformation lets us move from ECEF to plane-centered ECEF
// and vice-versa:
let observation_in_ecef = ecef_to_plane_centered_ecef.inverse_transform(observation);

pub fn cast<NewIn>(self) -> Coordinate<NewIn>

where In: EquivalentTo<NewIn>,

Casts the coordinate system type parameter of the coordinate to the equivalent coordinate system NewIn.

See EquivalentTo for details on when this is useful (and safe).

Note that this performs no transform on the coordinate’s components, as that should be unnecessary when EquivalentTo is implemented.

use sguaba::{coordinate, system, systems::EquivalentTo, Coordinate};
use uom::si::{f64::Length, length::meter};

system!(struct PlaneNedFromCrate1 using NED);
system!(struct PlaneNedFromCrate2 using NED);

// SAFETY: these are truly the same thing just defined in different places
unsafe impl EquivalentTo<PlaneNedFromCrate1> for PlaneNedFromCrate2 {}
unsafe impl EquivalentTo<PlaneNedFromCrate2> for PlaneNedFromCrate1 {}

let zero = Length::new::<meter>(0.);
let unit = Length::new::<meter>(1.);
let coordinate_in_1 = coordinate!(n = unit, e = zero, d = unit; in PlaneNedFromCrate1);

assert_eq!(
    coordinate!{
      n = coordinate_in_1.ned_north(),
      e = coordinate_in_1.ned_east(),
      d = coordinate_in_1.ned_down(),
    },
    coordinate_in_1.cast::<PlaneNedFromCrate2>()
);

pub fn lerp(&self, rhs: &Self, t: f64) -> Self

Linearly interpolate between this coordinate and another coordinate.

Specifically, returns self * (1.0 - t) + rhs * t, i.e., the linear blend of the two coordinates using the scalar value t.

The value for t is not restricted to the range [0, 1].

impl<In> Coordinate<In>

where In: CoordinateSystem<Convention = RightHandedXyzLike>,

pub fn x(&self) -> Length

pub fn y(&self) -> Length

pub fn z(&self) -> Length

pub fn x_axis() -> Vector<In>

pub fn y_axis() -> Vector<In>

pub fn z_axis() -> Vector<In>

impl<In> Coordinate<In>

where In: CoordinateSystem<Convention = NedLike>,

pub fn ned_north(&self) -> Length

pub fn ned_east(&self) -> Length

pub fn ned_down(&self) -> Length

pub fn ned_north_axis() -> Vector<In>

pub fn ned_east_axis() -> Vector<In>

pub fn ned_down_axis() -> Vector<In>

impl<In> Coordinate<In>

where In: CoordinateSystem<Convention = FrdLike>,

pub fn frd_front(&self) -> Length

pub fn frd_right(&self) -> Length

pub fn frd_down(&self) -> Length

pub fn frd_front_axis() -> Vector<In>

pub fn frd_right_axis() -> Vector<In>

pub fn frd_down_axis() -> Vector<In>

impl<In> Coordinate<In>

where In: CoordinateSystem<Convention = EnuLike>,

pub fn enu_east(&self) -> Length

pub fn enu_north(&self) -> Length

pub fn enu_up(&self) -> Length

pub fn enu_east_axis() -> Vector<In>

pub fn enu_north_axis() -> Vector<In>

pub fn enu_up_axis() -> Vector<In>

impl<In> Coordinate<In>

pub fn to_cartesian(&self) -> [Length; 3]

Returns the cartesian components of this coordinate in XYZ order.

To turn this into a simple (ie, unitless) [f64; 3], use array::map combined with .get::<meter>().

pub fn distance_from_origin(&self) -> Length

Computes the distance of this point from the coordinate system’s origin.

Examples

use approx::assert_relative_eq;
use sguaba::{coordinate, Coordinate, Vector, systems::Ecef};
use uom::si::f64::{Length};
use uom::si:: length::meter;

let zero = Length::new::<meter>(0.);
let unit = Length::new::<meter>(1.);
let p = coordinate!(x = unit, y = unit, z = zero; in Ecef);
assert_eq!(
    p.distance_from_origin(),
    (p - Coordinate::<Ecef>::origin()).magnitude(),
);

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

Computes the distance between this point and the given point.

Examples

use approx::assert_relative_eq;
use sguaba::{coordinate, Coordinate, Vector, systems::Ecef};
use uom::si::f64::{Length};
use uom::si:: length::meter;

let zero = Length::new::<meter>(0.);
let unit = Length::new::<meter>(1.);
let p = coordinate!(x = unit, y = unit, z = zero; in Ecef);
assert_eq!(
    p.distance_from(&Coordinate::<Ecef>::origin()),
    p.distance_from_origin(),
);
assert_eq!(
    p.distance_from(&p),
    zero,
);

pub fn bearing_from_origin(&self) -> Option<Bearing<In>>

where In: BearingDefined,

Calculates the bearing towards the point from Coordinate::origin.

Returns None for Coordinate::origin as the azimuth to it is ill-defined.

Returns an azimuth of zero for coordinates along the Z axis.

impl Coordinate<Ecef>

pub fn from_wgs84(wgs84: &Wgs84) -> Self

Converts latitude, longitude, and altitude to the Earth-Centered, Earth-Fixed coordinate system.

See: https://en.wikipedia.org/wiki/Geographic_coordinate_conversion#From_geodetic_to_ECEF_coordinates

pub fn to_wgs84(&self) -> Wgs84

Converts an Earth-Centered, Earth-Fixed coordinate into latitude, longitude, and altitude.

Note that this conversion is not trivial and needs to be approximated.

The implementation currently only guarantees conversion to WGS84 datums with altitude between -10km and 50km from the surface of the WGS84 ellipsoid, roughly corresponding to the bottom of the Mariana Trench to the top of the stratosphere. Outside this range, the implementation may panic.

This implementation currently uses Ferrari’s solution, but this may change in the future.

Trait Implementations

impl<In> AbsDiffEq for Coordinate<In>

Available on crate features approx only.

type Epsilon = Quantity<dyn Dimension<M = Z0, L = PInt<UInt<UTerm, B1>>, T = Z0, N = Z0, Th = Z0, I = Z0, Kind = dyn Kind, J = Z0>, dyn Units<f64, electric_current = ampere, length = meter, amount_of_substance = mole, mass = kilogram, time = second, luminous_intensity = candela, thermodynamic_temperature = kelvin>, f64>

Used for specifying relative comparisons.

fn default_epsilon() -> Self::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl<In> Add<Vector<In>> for Coordinate<In>

type Output = Coordinate<In>

The resulting type after applying the + operator.

fn add(self, rhs: Vector<In>) -> Self::Output

Performs the + operation.

impl<In> AddAssign<Vector<In>> for Coordinate<In>

fn add_assign(&mut self, rhs: Vector<In>)

Performs the += operation.

impl<In> Clone for Coordinate<In>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<In: Debug> Debug for Coordinate<In>

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

Formats the value using the given formatter.

impl<In> Default for Coordinate<In>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, In> Deserialize<'de> for Coordinate<In>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<In> Display for Coordinate<In>

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

Formats the value using the given formatter.

impl From<Coordinate<Ecef>> for Wgs84

fn from(ecef: Coordinate<Ecef>) -> Self

Converts to this type from the input type.

impl<In> From<Coordinate<In>> for Vector<In, Z0>

fn from(value: Coordinate<In>) -> Self

Converts to this type from the input type.

impl From<Wgs84> for Coordinate<Ecef>

fn from(wgs84: Wgs84) -> Self

Converts to this type from the input type.

impl<From, To> Mul<Coordinate<To>> for RigidBodyTransform<From, To>

type Output = Coordinate<From>

The resulting type after applying the * operator.

fn mul(self, rhs: Coordinate<To>) -> Self::Output

Performs the * operation.

impl<From, To> Mul<Coordinate<To>> for Rotation<From, To>

type Output = Coordinate<From>

The resulting type after applying the * operator.

fn mul(self, rhs: Coordinate<To>) -> Self::Output

Performs the * operation.

impl<From, To> Mul<RigidBodyTransform<From, To>> for Coordinate<From>

type Output = Coordinate<To>

The resulting type after applying the * operator.

fn mul(self, rhs: RigidBodyTransform<From, To>) -> Self::Output

Performs the * operation.

impl<From, To> Mul<Rotation<From, To>> for Coordinate<From>

type Output = Coordinate<To>

The resulting type after applying the * operator.

fn mul(self, rhs: Rotation<From, To>) -> Self::Output

Performs the * operation.

impl<In> Neg for Coordinate<In>

type Output = Coordinate<In>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<In> PartialEq for Coordinate<In>

fn eq(&self, other: &Self) -> 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<In> RelativeEq for Coordinate<In>

Available on crate features approx only.

fn default_max_relative() -> Self::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Self, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl<In> Serialize for Coordinate<In>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<In> Sub<Vector<In>> for Coordinate<In>

type Output = Coordinate<In>

The resulting type after applying the - operator.

fn sub(self, rhs: Vector<In>) -> Self::Output

Performs the - operation.

impl<In> Sub for Coordinate<In>

type Output = Vector<In>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<In> SubAssign<Vector<In>> for Coordinate<In>

fn sub_assign(&mut self, rhs: Vector<In>)

Performs the -= operation.

impl<In> Copy for Coordinate<In>