survex_rs/lib.rs
1//! # survex-rs
2//! Rust bindings to the Survex `img.c` library which can be used via a safe API utilising the
3//! [`SurveyData`][`data::SurveyData`] and [`Station`][`station::Station`] structs, or directly via
4//! unsafe Rust. For the source code and to contribute, see the GitHub repository at
5//! [anorthall/survex-rs](https://github.com/anorthall/survex-rs).
6//!
7//! ## Safe API
8//! The safe API is able to read data from a Survex .3d file and store it in a
9//! [`SurveyData`][`data::SurveyData`] instance. [`SurveyData`][`data::SurveyData`] instances
10//! contain a vector of references to [`Station`][`station::Station`] structs and a graph, built
11//! using [`petgraph`][`petgraph::graph::Graph`], of connections between those stations.
12//!
13//! A helper function, [`load_from_path`][`crate::read::load_from_path`], is provided to read a
14//! given Survex .3d file and return a [`SurveyData`][`data::SurveyData`] instance.
15//!
16//! ### Example
17//! ```rust
18//! use std::path::PathBuf;
19//! use survex_rs::read::load_from_path;
20//! use survex_rs::station::Point;
21//!
22//! let path = PathBuf::from("tests/data/nottsii.3d");
23//! let data = load_from_path(path).unwrap();
24//!
25//! println!("Loaded {} stations", data.stations.len());
26//! // Loaded 1904 stations
27//!
28//! println!("Loaded {} survey legs", data.graph.edge_count());
29//! // Loaded 1782 survey legs
30//!
31//! let station = data.get_by_label("nottsii.entrance").unwrap();
32//! let station = station.borrow();
33//! println!("Station '{}' is at {}", station.label, station.coords);
34//! // Station 'nottsii.entrance' is at 66668.00, 78303.00, 319.00
35//!
36//! let coords = Point::new(66668.00, 78303.00, 319.00);
37//! let station = data.get_by_coords(&coords).unwrap();
38//! let station = station.borrow();
39//! println!("{:#?}", station);
40//! // Station {
41//! // label: "nottsii.entrance",
42//! // coords: Point {
43//! // x: 66668.0,
44//! // y: 78303.0,
45//! // z: 319.0,
46//! // },
47//! // index: NodeIndex(1901),
48//! // lrud: LRUD {
49//! // left: None,
50//! // right: None,
51//! // up: None,
52//! // down: None,
53//! // },
54//! // surface: false,
55//! // underground: false,
56//! // entrance: true,
57//! // exported: true,
58//! // fixed: true,
59//! // anonymous: false,
60//! // wall: false,
61//! // }
62//! ```
63//!
64//! ## Unsafe API
65//! If you wish to simply access the Survex `img.c` library directly using unsafe Rust, you can do so
66//! via the bindings in the [`survex`][`crate::survex`] module.
67//!
68//! For an example of how to use the unsafe API, take a look at the source for
69//! [`load_from_path`][`crate::read::load_from_path`] in `src/read.rs`. You can browse the functions in the
70//! [`survex`][`crate::survex`] module and reference them to the Survex `img.c` and `img.h` files found in the `src/`
71//! directory of the [Survex source code](https://github.com/ojwb/survex).
72//!
73//! ## Project status
74//! This project is currently in early development and is not ready for production use. The API is subject to change at
75//! any time and semantic versioning is not yet being used.
76
77pub mod data;
78pub mod read;
79pub mod station;
80pub mod survex;