topology_traits/
lib.rs

1#![doc = include_str!("../README.md")]
2#![cfg_attr(not(feature = "std"), no_std)]
3
4use core::ops::{Add, Mul};
5use num_traits::real::Real;
6
7/// All elements in a quasi metric space should implement this trait.
8///
9/// If the struct implementing this trait also implements `Topology`,
10/// the `distance(to)` method should be equivalent to `self.shortest_path(to).length()`.
11pub trait QuasiMetric<T = f64> {
12    /// Returns the length of the shortest path between the two points.
13    fn distance(self, to: Self) -> T;
14}
15
16/// Trait for elements having a length.
17pub trait Length<T = f64> {
18    /// Returns the length of the element.
19    fn length(&self) -> T;
20}
21
22/// The merge trait is used to merge two elements together.
23///
24/// Often this is a linear interpolation between two elements.
25/// In the case of Quaternions it is a spherical linear interpolation.
26///
27/// A default implementation of this trait is provided for all `E` that
28/// are `Add<Output = E> + Mul<T, Output = E> + Copy` as these
29/// operations let us assume that the elements live in a vector-like space.
30///
31/// If the struct implementing this trait also implements `Topology`,
32/// the `merge(factor)` method should be equivalent to `self.shortest_path(to).contract(factor)`.
33pub trait Merge<T = f64> {
34    /// Merge between `self` and `to` using `factor`.
35    ///
36    /// This can be thought of creating a point on (one of) the shortest Paths
37    /// between the two given points.
38    ///
39    /// Merging `self` with a factor of `Zero` should return a copy of `self`.
40    /// Merging `to` with a factor of `One` should return a copy of `to`.
41    /// It is assumed that the factor decides how similar the result will be to either
42    /// `self` or `to`.
43    fn merge(self, to: Self, factor: T) -> Self;
44}
45
46/// Trait for structures containing two elements which can be merged together.
47pub trait Connected<P, T = f64> {
48    /// Returns the merged point of the start point and end point inside `self` with weight `factor`.
49    ///
50    /// Contracting with a factor of `Zero` should return the start point.
51    /// Contracting with a factor of `One` should return the end point.
52    /// The factor decides how similar the result will be to the start or end point.
53    fn contract(&self, factor: T) -> P;
54}
55
56/// Main trait for topological spaces.
57///
58/// The associated type `Path` should implement as many traits as possible which allows to implement
59/// other traits trivially.
60/// - Length -> QuasiMetric
61/// - Merge -> Connected
62pub trait Topology {
63    /// The type of paths in this space. Usually \[Self,Self\].
64    type Path;
65    /// Function which returns the shortest path between `self` as start point and `to` as end point.
66    ///
67    /// Often this returns a line are something equivalent from `self` to `to`.
68    fn shortest_path(self, to: Self) -> Self::Path;
69}
70
71impl<E, T> Merge<T> for E
72where
73    E: Add<Output = E> + Mul<T, Output = E> + Copy,
74    T: Real,
75{
76    fn merge(self, other: Self, factor: T) -> E {
77        self * (T::one() - factor) + other * factor
78    }
79}
topology_traits/lib.rs

topology_traits/
lib.rs
