routers 0.2.3

Rust-Based Routing Tooling for System-Agnostic Maps.
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

use std::sync::Arc;

use crate::transition::{MatchError, RoutedPath};
use crate::{PredicateCache, SolverVariant};

use geo::LineString;
use routers_network::{Entry, Metadata, Network};

pub const DEFAULT_SEARCH_DISTANCE: f64 = 50.0; // 50m

pub struct MatchOptions<E: Entry, M: Metadata, N: Network<E, M>> {
    /// The distance the solver will use to search for candidates
    /// around every given input position.
    ///
    /// For positions where accuracy is high, such as the probability
    /// of a candidate being within a lower search distance is above
    /// 3 standard deviations (99.7%), you may lower the value to this
    /// point.
    ///
    /// The default value is [DEFAULT_SEARCH_DISTANCE].
    ///
    /// > Positions that exist at a distance further than this search distance
    /// > may still exist within the result should it be highly probable they
    /// > are the correct position.
    ///
    /// The recommended value range is 25-100m. While higher
    /// values are permitted, and there is no ceiling, a
    /// higher value has a direct impact on the computation time.
    pub search_distance: f64,

    /// An owned instance of the specified runtime for the generic
    /// metadata implementation.
    ///
    /// This value may be obtained by using the associated methods
    /// on a provided runtime implementation, [Metadata::runtime]
    /// or [Metadata::default_runtime].
    ///
    /// Alternatively, it may be created directly if the value and
    /// type are known. This may be particularly useful in a custom
    /// implementation of graph metadata.
    pub runtime: M::Runtime,

    /// The variant of solver to be used by the matcher.
    /// Any given value of the enumeration is accepted,
    pub solver: SolverVariant,

    pub cache: Option<Arc<PredicateCache<E, M, N>>>,
}

impl<E: Entry, M: Metadata, N: Network<E, M>> Default for MatchOptions<E, M, N> {
    fn default() -> Self {
        Self {
            search_distance: DEFAULT_SEARCH_DISTANCE,
            runtime: M::default_runtime(),
            solver: SolverVariant::default(),
            cache: None,
        }
    }
}

impl<E: Entry, M: Metadata, N: Network<E, M>> MatchOptions<E, M, N> {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_runtime(self, runtime: M::Runtime) -> Self {
        Self { runtime, ..self }
    }

    pub fn with_cache(self, cache: Arc<PredicateCache<E, M, N>>) -> Self {
        Self {
            cache: Some(cache),
            ..self
        }
    }

    pub fn with_solver(self, solver: impl Into<SolverVariant>) -> Self {
        Self {
            solver: solver.into(),
            ..self
        }
    }

    pub fn with_search_distance(self, search_distance: Option<f64>) -> Self {
        Self {
            search_distance: search_distance.unwrap_or(self.search_distance),
            ..self
        }
    }
}

pub trait Match<E, M, N>
where
    E: Entry,
    M: Metadata,
    N: Network<E, M>,
{
    /// Matches a given [linestring](LineString) against the map.
    ///
    /// Matching involves the use of a hidden markov model
    /// using the [`Transition`](crate::Transition) module
    /// to collapse the given input onto the map, finding
    /// appropriate matching for each input value.
    fn r#match(
        &self,
        linestring: LineString,
        opts: MatchOptions<E, M, N>,
    ) -> Result<RoutedPath<E, M>, MatchError>;

    /// Snaps a given linestring against the map.
    ///
    /// TODO: Docs
    fn snap(
        &self,
        linestring: LineString,
        opts: MatchOptions<E, M, N>,
    ) -> Result<RoutedPath<E, M>, MatchError>;
}

/// Simplifies the interface to the `Match` trait, providing methods that uses appropriate options.
pub trait MatchSimpleExt<E, M, N>: Match<E, M, N>
where
    E: Entry,
    M: Metadata,
    N: Network<E, M>,
{
    fn r#match_simple(&self, linestring: LineString) -> Result<RoutedPath<E, M>, MatchError> {
        self.r#match(linestring, MatchOptions::default())
    }

    fn snap_simple(&self, linestring: LineString) -> Result<RoutedPath<E, M>, MatchError> {
        self.snap(linestring, MatchOptions::default())
    }
}

impl<T, E: Entry, M: Metadata, N: Network<E, M>> MatchSimpleExt<E, M, N> for T where
    T: Match<E, M, N>
{
}