traj-dist-rs 1.0.0-rc.5

High-performance trajectory distance & similarity measures in Rust with Python bindings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

//! # Core Traits Module
//!
//! This module defines the core traits used throughout the traj-dist-rs library
//! for coordinate and trajectory representations.
//!
//! ## Traits
//!
//! - `AsCoord`: Trait for accessing x and y coordinates of a point
//! - `CoordSequence`: Trait for accessing sequences of coordinates (trajectories)
//! - `DistanceCalculator`: Interface for DP-based distance algorithm calculators
//!
//! ## Implementations
//!
//! This module provides implementations of these traits for common types:
//! - `[f64; 2]` - Array of two f64 values (x, y)
//! - `&[f64; 2]` - Reference to array
//! - `Vec<[f64; 2]>` - Vector of coordinate arrays
//!
//! ## Usage
//!
//! These traits allow algorithms to work with any coordinate representation
//! that implements them, providing flexibility for different use cases.
//!
//! For concrete implementations of `DistanceCalculator`, see [`crate::distance::base`]:
//! - `TrajectoryCalculator`: Computes distances on-the-fly from trajectory coordinates
//! - `PrecomputedDistanceCalculator`: Uses a precomputed distance matrix (zero-copy)

// Re-export DistanceCalculator trait for convenient access at the traits module level
pub use crate::distance::base::DistanceCalculator;

/// Trait for coordinate representation
///
/// This trait defines the interface for accessing x and y coordinates
/// of a point in 2D space. It is used by trajectory algorithms to
/// uniformly access coordinate values regardless of the underlying
/// coordinate representation.
///
/// ## Example
///
/// ```rust
/// use traj_dist_rs::traits::AsCoord;
///
/// let point = [1.0, 2.0];
/// assert_eq!(point.x(), 1.0);
/// assert_eq!(point.y(), 2.0);
/// ```
pub trait AsCoord {
    /// Get the x-coordinate (longitude or easting)
    ///
    /// Returns the x-coordinate value of the point.
    fn x(&self) -> f64;

    /// Get the y-coordinate (latitude or northing)
    ///
    /// Returns the y-coordinate value of the point.
    fn y(&self) -> f64;
}

/// Trait for coordinate sequence representation
///
/// This trait defines the interface for accessing sequences of coordinates,
/// such as trajectories or paths. It provides methods to get the length
/// of the sequence and access individual coordinates by index.
///
/// ## Example
///
/// ```rust
/// use traj_dist_rs::traits::{CoordSequence, AsCoord};
///
/// let trajectory = vec![[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]];
/// assert_eq!(trajectory.len(), 3);
/// assert_eq!(trajectory.get(1).x(), 1.0);
/// assert_eq!(trajectory.get(1).y(), 1.0);
/// ```
pub trait CoordSequence {
    /// The type of coordinate in this sequence
    type Coord: AsCoord;

    /// Get the number of coordinates in the sequence
    ///
    /// Returns the total number of coordinate points in the sequence.
    fn len(&self) -> usize;

    /// Check if the sequence is empty
    ///
    /// Returns `true` if the sequence contains no coordinates, `false` otherwise.
    /// This is implemented as `self.len() == 0` by default.
    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Get the i-th coordinate in the sequence
    ///
    /// Returns a copy of the coordinate at the specified index.
    ///
    /// # Panics
    ///
    /// This method may panic if the index is out of bounds.
    fn get(&self, i: usize) -> Self::Coord;
}

/// Implementation of `AsCoord` for 2-element array of f64
///
/// This implementation allows `[f64; 2]` arrays to be used as coordinates.
/// The first element is treated as x-coordinate and the second as y-coordinate.
impl AsCoord for [f64; 2] {
    fn x(&self) -> f64 {
        self[0]
    }

    fn y(&self) -> f64 {
        self[1]
    }
}

impl AsCoord for &[f64; 2] {
    fn x(&self) -> f64 {
        self[0]
    }

    fn y(&self) -> f64 {
        self[1]
    }
}

/// Implementation of `CoordSequence` for vector of 2-element f64 arrays
///
/// This implementation allows `Vec<[f64; 2]>` to be used as a sequence of coordinates,
/// which is a common representation for trajectories.
impl CoordSequence for Vec<[f64; 2]> {
    type Coord = [f64; 2];

    fn len(&self) -> usize {
        self.as_slice().len()
    }

    fn get(&self, i: usize) -> Self::Coord {
        self.as_slice()[i]
    }
}