From 7632a4ec7b3f59622284ec86288f0c0cd12f57c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tristram=20Gr=C3=A4bener?= Date: Thu, 19 Sep 2024 14:03:44 +0200 Subject: [PATCH] python: generate python pyi stubs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This allows to have type hints and comments when using the library Signed-off-by: Tristram Gräbener --- Cargo.lock | 316 +++++++++++++++++++++++++++++++++---- python/Cargo.toml | 6 +- python/pyproject.toml | 4 +- python/src/bin/stub_gen.rs | 8 + python/src/lib.rs | 48 +++++- 5 files changed, 350 insertions(+), 32 deletions(-) create mode 100644 python/src/bin/stub_gen.rs diff --git a/Cargo.lock b/Cargo.lock index 82453d5..aef3dae 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -74,6 +74,12 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "anyhow" +version = "1.0.89" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86fdf8605db99b54d3cd748a44c6d04df638eb5dafb219b135d0149bd0db01f6" + [[package]] name = "approx" version = "0.5.1" @@ -95,6 +101,12 @@ version = "1.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" +[[package]] +name = "bitflags" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de" + [[package]] name = "bumpalo" version = "3.16.0" @@ -141,7 +153,7 @@ version = "4.5.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "528131438037fd55894f62d6e9f068b8f45ac57ffa77517819645d10aed04f64" dependencies = [ - "heck", + "heck 0.5.0", "proc-macro2", "quote", "syn", @@ -205,7 +217,7 @@ version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "79127ed59a85d7687c409e9978547cffb7dc79675355ed22da6b66fd5f6ead01" dependencies = [ - "itertools", + "itertools 0.11.0", "num-traits", ] @@ -215,6 +227,12 @@ version = "1.11.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a47c1c47d2f5964e29c61246e81db715514cd532db6b5116a25ea3c03d6780a2" +[[package]] +name = "equivalent" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5" + [[package]] name = "flat_map" version = "0.0.10" @@ -231,7 +249,7 @@ version = "24.3.25" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8add37afff2d4ffa83bc748a70b4b1370984f6980768554182424ef71447c35f" dependencies = [ - "bitflags", + "bitflags 1.3.2", "rustc_version", ] @@ -334,6 +352,12 @@ dependencies = [ "stable_deref_trait", ] +[[package]] +name = "heck" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8" + [[package]] name = "heck" version = "0.5.0" @@ -346,12 +370,28 @@ version = "0.3.9" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d231dfb89cfffdbc30e7fc41579ed6066ad03abda9e567ccafae602b97ec5024" +[[package]] +name = "indexmap" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68b900aa2f7301e21c36462b170ee99994de34dff39a4a6a528e80e7376d07e5" +dependencies = [ + "equivalent", + "hashbrown", +] + [[package]] name = "indoc" version = "2.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b248f5224d1d606005e02c97f5aa4e88eeb230488bcc03bc9ca4d7991399f2b5" +[[package]] +name = "inventory" +version = "0.3.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f958d3d68f4167080a18141e10381e7634563984a537f2a49a30fd8e53ac5767" + [[package]] name = "itertools" version = "0.11.0" @@ -361,6 +401,15 @@ dependencies = [ "either", ] +[[package]] +name = "itertools" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186" +dependencies = [ + "either", +] + [[package]] name = "itoa" version = "1.0.11" @@ -403,6 +452,8 @@ dependencies = [ "geo-types", "liblrs", "pyo3", + "pyo3-stub-gen", + "pyo3-stub-gen-derive 0.6.0", ] [[package]] @@ -411,11 +462,37 @@ version = "0.2.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4ec2a862134d2a7d32d7983ddcdd1c4923530833c9f2ea1a44fc5fa473989058" +[[package]] +name = "lock_api" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07af8b9cdd281b7915f413fa73f29ebd5d55d0d3f0155584dade1ff18cea1b17" +dependencies = [ + "autocfg", + "scopeguard", +] + [[package]] name = "log" -version = "0.4.21" +version = "0.4.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24" + +[[package]] +name = "maplit" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e2e65a1a2e43cfcb47a895c4c8b10d1f4a61097f9f254f183aee60cad9c651d" + +[[package]] +name = "matrixmultiply" +version = "0.3.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "90ed8c1e510134f979dbc4f070f87d4313098b704861a105fe34231c70a3901c" +checksum = "9380b911e3e96d10c1f415da0876389aaf1b56759054eeb0de7df940c456ba1a" +dependencies = [ + "autocfg", + "rawpointer", +] [[package]] name = "memchr" @@ -441,6 +518,37 @@ dependencies = [ "adler", ] +[[package]] +name = "ndarray" +version = "0.15.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "adb12d4e967ec485a5f71c6311fe28158e9d6f4bc4a447b474184d0f91a8fa32" +dependencies = [ + "matrixmultiply", + "num-complex", + "num-integer", + "num-traits", + "rawpointer", +] + +[[package]] +name = "num-complex" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-integer" +version = "0.1.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f" +dependencies = [ + "num-traits", +] + [[package]] name = "num-traits" version = "0.2.18" @@ -461,6 +569,21 @@ dependencies = [ "libc", ] +[[package]] +name = "numpy" +version = "0.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec170733ca37175f5d75a5bea5911d6ff45d2cd52849ce98b685394e4f2f37f4" +dependencies = [ + "libc", + "ndarray", + "num-complex", + "num-integer", + "num-traits", + "pyo3", + "rustc-hash", +] + [[package]] name = "once_cell" version = "1.19.0" @@ -510,6 +633,29 @@ dependencies = [ "pub-iterator-type", ] +[[package]] +name = "parking_lot" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1bf18183cf54e8d6059647fc3063646a1801cf30896933ec2311622cc4b9a27" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e401f977ab385c9e4e3ab30627d6f26d00e2c73eef317493c4ec6d468726cf8" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-targets", +] + [[package]] name = "portable-atomic" version = "1.6.0" @@ -518,9 +664,9 @@ checksum = "7170ef9988bc169ba16dd36a7fa041e5c4cbeb6a35b76d4c03daded371eae7c0" [[package]] name = "proc-macro2" -version = "1.0.80" +version = "1.0.86" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a56dea16b0a29e94408b9aa5e2940a4eedbd128a1ba20e8f7ae60fd3d465af0e" +checksum = "5e719e8df665df0d1c8fbfd238015744736151d4445ec0836b8e628aae103b77" dependencies = [ "unicode-ident", ] @@ -558,15 +704,15 @@ checksum = "858afdbecdce657c6e32031348cf7326da7700c869c368a136d31565972f7018" [[package]] name = "pyo3" -version = "0.22.1" +version = "0.21.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4e99090d12f6182924499253aaa1e73bf15c69cea8d2774c3c781e35badc3548" +checksum = "a5e00b96a521718e08e03b1a622f01c8a8deb50719335de3f60b3b3950f069d8" dependencies = [ "cfg-if", "indoc", "libc", "memoffset", - "once_cell", + "parking_lot", "portable-atomic", "pyo3-build-config", "pyo3-ffi", @@ -576,9 +722,9 @@ dependencies = [ [[package]] name = "pyo3-build-config" -version = "0.22.1" +version = "0.21.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7879eb018ac754bba32cb0eec7526391c02c14a093121857ed09fbf1d1057d41" +checksum = "7883df5835fafdad87c0d888b266c8ec0f4c9ca48a5bed6bbb592e8dedee1b50" dependencies = [ "once_cell", "target-lexicon", @@ -586,9 +732,9 @@ dependencies = [ [[package]] name = "pyo3-ffi" -version = "0.22.1" +version = "0.21.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ce2baa5559a411fc1cf519295f24c34b53d5d725818bc96b5abf94762da09041" +checksum = "01be5843dc60b916ab4dad1dca6d20b9b4e6ddc8e15f50c47fe6d85f1fb97403" dependencies = [ "libc", "pyo3-build-config", @@ -596,9 +742,9 @@ dependencies = [ [[package]] name = "pyo3-macros" -version = "0.22.1" +version = "0.21.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "049621c20a23f2def20f4fe67978d1da8d8a883d64b9c21362f3b776e254edc7" +checksum = "77b34069fc0682e11b31dbd10321cbf94808394c56fd996796ce45217dfac53c" dependencies = [ "proc-macro2", "pyo3-macros-backend", @@ -608,26 +754,78 @@ dependencies = [ [[package]] name = "pyo3-macros-backend" -version = "0.22.1" +version = "0.21.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0e969ee2e025435f1819d31a275ba4bb9cbbdf3ac535227fdbd85b9322ffe144" +checksum = "08260721f32db5e1a5beae69a55553f56b99bd0e1c3e6e0a5e8851a9d0f5a85c" dependencies = [ - "heck", + "heck 0.4.1", "proc-macro2", "pyo3-build-config", "quote", "syn", ] +[[package]] +name = "pyo3-stub-gen" +version = "0.6.1" +dependencies = [ + "anyhow", + "inventory", + "itertools 0.13.0", + "log", + "maplit", + "num-complex", + "numpy", + "pyo3", + "pyo3-stub-gen-derive 0.6.1", + "serde", + "toml", +] + +[[package]] +name = "pyo3-stub-gen-derive" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "295a22fe8963404c42f3d62c78099dde32ec508a3e756b0dc86a1e7fa604eb34" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "pyo3-stub-gen-derive" +version = "0.6.1" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + [[package]] name = "quote" -version = "1.0.36" +version = "1.0.37" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0fa76aaf39101c457836aec0ce2316dbdc3ab723cdda1c6bd4e6ad4208acaca7" +checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af" dependencies = [ "proc-macro2", ] +[[package]] +name = "rawpointer" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3" + +[[package]] +name = "redox_syscall" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0884ad60e090bf1345b93da0a5de8923c93884cd03f40dfcfddd3b4bee661853" +dependencies = [ + "bitflags 2.6.0", +] + [[package]] name = "robust" version = "1.1.0" @@ -645,6 +843,12 @@ dependencies = [ "smallvec", ] +[[package]] +name = "rustc-hash" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2" + [[package]] name = "rustc_version" version = "0.4.0" @@ -660,6 +864,12 @@ version = "1.0.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e86697c916019a8588c99b5fac3cead74ec0b4b819707a682fd4d23fa0ce1ba1" +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + [[package]] name = "self_cell" version = "1.0.3" @@ -674,24 +884,33 @@ checksum = "92d43fe69e652f3df9bdc2b85b2854a0825b86e4fb76bc44d945137d053639ca" [[package]] name = "serde" -version = "1.0.197" +version = "1.0.210" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3fb1c873e1b9b056a4dc4c0c198b24c3ffa059243875552b2bd0933b1aee4ce2" +checksum = "c8e3592472072e6e22e0a54d5904d9febf8508f65fb8552499a1abc7d1078c3a" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" -version = "1.0.197" +version = "1.0.210" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7eb0b34b42edc17f6b7cac84a52a1c5f0e1bb2227e997ca9011ea3dd34e8610b" +checksum = "243902eda00fad750862fc144cea25caca5e20d615af0a81bee94ca738f1df1f" dependencies = [ "proc-macro2", "quote", "syn", ] +[[package]] +name = "serde_spanned" +version = "0.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb5b1b31579f3811bf615c144393417496f152e12ac8b7663bf664f4a815306d" +dependencies = [ + "serde", +] + [[package]] name = "smallvec" version = "1.13.2" @@ -742,9 +961,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" [[package]] name = "syn" -version = "2.0.59" +version = "2.0.77" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4a6531ffc7b071655e4ce2e04bd464c4830bb585a61cabb96cf808f05172615a" +checksum = "9f35bcdf61fd8e7be6caf75f429fdca8beb3ed76584befb503b1569faee373ed" dependencies = [ "proc-macro2", "quote", @@ -777,6 +996,40 @@ dependencies = [ "syn", ] +[[package]] +name = "toml" +version = "0.8.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1ed1f98e3fdc28d6d910e6737ae6ab1a93bf1985935a1193e68f93eeb68d24e" +dependencies = [ + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", +] + +[[package]] +name = "toml_datetime" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0dd7358ecb8fc2f8d014bf86f6f638ce72ba252a2c3a2572f2a795f1d23efb41" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_edit" +version = "0.22.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b072cee73c449a636ffd6f32bd8de3a9f7119139aff882f44943ce2986dc5cf" +dependencies = [ + "indexmap", + "serde", + "serde_spanned", + "toml_datetime", + "winnow", +] + [[package]] name = "unicode-ident" version = "1.0.12" @@ -928,6 +1181,15 @@ version = "0.52.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "bec47e5bfd1bff0eeaf6d8b485cc1074891a197ab4225d504cb7a1ab88b02bf0" +[[package]] +name = "winnow" +version = "0.6.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68a9bda4691f099d435ad181000724da8e5899daa10713c2d432552b9ccd3a6f" +dependencies = [ + "memchr", +] + [[package]] name = "zerocopy" version = "0.7.32" diff --git a/python/Cargo.toml b/python/Cargo.toml index c4e8693..3317818 100644 --- a/python/Cargo.toml +++ b/python/Cargo.toml @@ -4,9 +4,11 @@ version = "0.1.2" edition = "2021" [lib] -crate-type = ["cdylib"] +crate-type = ["cdylib", "rlib"] [dependencies] liblrs = { path = ".." } geo-types = "*" -pyo3 = { version = "0.22.1", features = ["extension-module"]} \ No newline at end of file +pyo3-stub-gen = {path="/home/tristram/travail/sncf/pyo3-stub-gen/pyo3-stub-gen"} +pyo3-stub-gen-derive = "0.6" +pyo3 = { version = "0.21", features = ["extension-module"]} \ No newline at end of file diff --git a/python/pyproject.toml b/python/pyproject.toml index d0ddaa7..9e181d3 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -1,7 +1,9 @@ +[project] +name="liblrs_python" [build-system] requires = ["maturin>=1.0,<2.0"] build-backend = "maturin" [tool.maturin] # "extension-module" tells pyo3 we want to build an extension module (skips linking against libpython.so) -features = ["pyo3/extension-module"] \ No newline at end of file +features = ["pyo3/extension-module"] diff --git a/python/src/bin/stub_gen.rs b/python/src/bin/stub_gen.rs new file mode 100644 index 0000000..e41a9a6 --- /dev/null +++ b/python/src/bin/stub_gen.rs @@ -0,0 +1,8 @@ +use pyo3_stub_gen::Result; + +fn main() -> Result<()> { + // `stub_info` is a function defined by `define_stub_info_gatherer!` macro. + let stub = liblrs_python::stub_info()?; + stub.generate()?; + Ok(()) +} \ No newline at end of file diff --git a/python/src/lib.rs b/python/src/lib.rs index 2ed3a9b..c6e8ffb 100644 --- a/python/src/lib.rs +++ b/python/src/lib.rs @@ -4,8 +4,10 @@ use liblrs::lrs_ext::*; use liblrs::{builder::Properties, lrs::LrsBase}; use pyo3::{exceptions::PyTypeError, prelude::*}; +use pyo3_stub_gen::{derive::*, define_stub_info_gatherer}; /// Holds the whole Linear Referencing System. +#[gen_stub_pyclass] #[pyclass] pub struct Lrs { lrs: ExtLrs, @@ -25,6 +27,7 @@ fn liblrs_python(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> { #[derive(Clone, Copy)] /// A geographical [`Point`], it can be either a projected or spherical coordinates. +#[gen_stub_pyclass] #[pyclass] pub struct Point { /// Position on x-axis or `longitude`. @@ -35,6 +38,7 @@ pub struct Point { pub y: f64, } +#[gen_stub_pymethods] #[pymethods] impl Point { #[new] @@ -70,6 +74,7 @@ impl From for geo_types::Coord { } } +#[gen_stub_pyclass] #[pyclass] /// Represent a position on an [`LrmScale`] relative as an `offset` to an [`Anchor`]. pub struct LrmScaleMeasure { @@ -99,6 +104,7 @@ impl From<&LrmScaleMeasure> for liblrs::lrm_scale::LrmScaleMeasure { } } +#[gen_stub_pymethods] #[pymethods] impl LrmScaleMeasure { #[new] @@ -112,6 +118,7 @@ impl LrmScaleMeasure { } #[derive(Clone, Copy)] +#[gen_stub_pyclass] #[pyclass] /// A traversal is composed by segments pub struct SegmentOfTraversal { @@ -121,6 +128,7 @@ pub struct SegmentOfTraversal { pub reversed: bool, } +#[gen_stub_pymethods] #[pymethods] impl SegmentOfTraversal { #[new] @@ -142,6 +150,7 @@ impl From for liblrs::builder::SegmentOfTraversal { } #[derive(Clone, Copy)] +#[gen_stub_pyclass] #[pyclass] /// The linear position of an anchor doesn’t always match the measured distance /// For example if a road was transformed into a bypass, resulting in a longer road, @@ -155,6 +164,7 @@ pub struct AnchorOnLrm { pub distance_along_lrm: f64, } +#[gen_stub_pymethods] #[pymethods] impl AnchorOnLrm { #[new] @@ -175,6 +185,7 @@ impl From for liblrs::builder::AnchorOnLrm { } } +#[gen_stub_pyclass] #[pyclass] /// An `Anchor` is a reference point for a given [`Curve`]. /// It can be a milestone, a bridge… @@ -204,6 +215,7 @@ impl From<&liblrs::lrm_scale::Anchor> for Anchor { } } +#[gen_stub_pymethods] #[pymethods] impl Lrs { /// Load the data. @@ -277,25 +289,29 @@ impl Lrs { } } +#[gen_stub_pyclass] #[pyclass] struct Builder { inner: liblrs::builder::Builder<'static>, } +#[gen_stub_pymethods] #[pymethods] impl Builder { #[new] + /// Instantiate a new builder fn new() -> Self { Self { inner: liblrs::builder::Builder::new(), } } + /// Add a new topological node (e.g. a railway switch) pub fn add_node(&mut self, id: &str, coord: Point, properties: Properties) -> usize { self.inner.add_node(id, coord.into(), properties) } - #[pyo3(signature = (id, coord, properties, name=None))] + /// Add a new anchor by its cooordinates pub fn add_anchor( &mut self, id: &str, @@ -306,7 +322,7 @@ impl Builder { self.inner.add_anchor(id, name, coord.into(), properties) } - #[pyo3(signature = (id, position_on_curve, properties, name=None))] + /// Add a new anchor by its position along the curve pub fn add_projected_anchor( &mut self, id: &str, @@ -318,6 +334,10 @@ impl Builder { .add_projected_anchor(id, name, position_on_curve, properties) } + /// Add a new segment + /// + /// The geometry represents the curve + /// start_node_index and end_node_index are the topological extremeties returned by `add_node` pub fn add_segment( &mut self, id: &str, @@ -330,11 +350,18 @@ impl Builder { .add_segment(id, &geometry, start_node_index, end_node_index) } + /// Add a traversal + /// + /// segments represent the curve of the traversal pub fn add_traversal(&mut self, traversal_id: &str, segments: Vec) { let segments: Vec<_> = segments.into_iter().map(|segment| segment.into()).collect(); self.inner.add_traversal(traversal_id, &segments); } + /// Add a linear referencing model + /// + /// It is composed by the traversal identified by traversa_index (that represents the curve) + /// and the anchors (that represent the milestones) pub fn add_lrm( &mut self, id: &str, @@ -347,10 +374,14 @@ impl Builder { .add_lrm(id, traversal_index, &anchors, properties) } + /// List all the traversals by their id and index pub fn get_traversal_indexes(&mut self) -> std::collections::HashMap { self.inner.get_traversal_indexes() } + /// Read the topology from an OpenStreetMap source + /// + /// It reads the nodes, segments and traversals. pub fn read_from_osm( &mut self, input_osm_file: String, @@ -362,22 +393,30 @@ impl Builder { .read_from_osm(&input_osm_file, &lrm_tag, required, to_reject) } + /// Save the lrs to a file pub fn save(&mut self, out_file: String, properties: Properties) { self.inner.save(&out_file, properties) } + /// Compute the euclidean distance between two lrms pub fn euclidean_distance(&self, lrm_index_a: usize, lrm_index_b: usize) -> f64 { self.inner.euclidean_distance(lrm_index_a, lrm_index_b) } + /// List all the node indices of a traversal pub fn get_nodes_of_traversal(&self, lrm_index: usize) -> Vec { self.inner.get_nodes_of_traversal(lrm_index).to_vec() } + /// Get the coordinates of a node identified by its index pub fn get_node_coord(&self, node_index: usize) -> Point { self.inner.get_node_coord(node_index).into() } + /// Project a point on a the curve of an lrm + /// + /// Return a value between 0 and 1, both included + /// Return None if the curve of the traversal is not defined pub fn project(&self, lrm_index: usize, point: Point) -> Option { self.inner .project(lrm_index, geo_types::point! {x: point.x, y: point.y}) @@ -385,7 +424,12 @@ impl Builder { .ok() } + /// Reverse the orientation of the lrm + /// + /// If it is composed by the segments (a, b)-(b, c) it will be (c, b)-(b, a) pub fn reverse(&mut self, lrm_index: usize) { self.inner.reverse(lrm_index) } } + +define_stub_info_gatherer!(stub_info); \ No newline at end of file