From 17c69b25ca23654524491eb1eeaf64f5e6278f2c Mon Sep 17 00:00:00 2001 From: Michael Kirk Date: Mon, 28 Oct 2024 12:11:07 -0700 Subject: [PATCH] reorganize frontpage docs to account for line_measures work --- geo/src/algorithm/line_measures/bearing.rs | 2 +- .../algorithm/line_measures/destination.rs | 2 +- geo/src/algorithm/line_measures/distance.rs | 2 +- geo/src/lib.rs | 64 +++++++++---------- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/geo/src/algorithm/line_measures/bearing.rs b/geo/src/algorithm/line_measures/bearing.rs index d092ec9e88..67a1694e7f 100644 --- a/geo/src/algorithm/line_measures/bearing.rs +++ b/geo/src/algorithm/line_measures/bearing.rs @@ -1,6 +1,6 @@ use geo_types::{CoordFloat, Point}; -/// Calculate the bearing between two points +/// Calculate the bearing between two points. pub trait Bearing { /// Calculate the bearing from `origin` to `destination` in degrees. /// diff --git a/geo/src/algorithm/line_measures/destination.rs b/geo/src/algorithm/line_measures/destination.rs index 91ffb73ef4..513524937e 100644 --- a/geo/src/algorithm/line_measures/destination.rs +++ b/geo/src/algorithm/line_measures/destination.rs @@ -1,6 +1,6 @@ use geo_types::{CoordFloat, Point}; -/// Calculate the destination point from an origin point, a bearing and a distance. +/// Calculate the destination point from an origin point, given a bearing and a distance. pub trait Destination { /// Returns a new point having travelled the `distance` along a line /// from the `origin` point with the given `bearing`. diff --git a/geo/src/algorithm/line_measures/distance.rs b/geo/src/algorithm/line_measures/distance.rs index e89749fb28..4ec9d994be 100644 --- a/geo/src/algorithm/line_measures/distance.rs +++ b/geo/src/algorithm/line_measures/distance.rs @@ -1,4 +1,4 @@ -/// Calculate the distance between the `Origin` and `Destination` geometry. +/// Calculate the minimum distance between two geometries. pub trait Distance { /// Note that not all implementations support all geometry combinations, but at least `Point` to `Point` /// is supported. diff --git a/geo/src/lib.rs b/geo/src/lib.rs index 4b69dd6371..11cf8bc4ae 100644 --- a/geo/src/lib.rs +++ b/geo/src/lib.rs @@ -31,32 +31,43 @@ //! //! # Algorithms //! -//! ## Area +//! ## Measures //! -//! - **[`Area`]**: Calculate the planar area of a geometry -//! - **[`ChamberlainDuquetteArea`]**: Calculate the geodesic area of a geometry on a sphere using the algorithm presented in _Some Algorithms for Polygons on a Sphere_ by Chamberlain and Duquette (2007) -//! - **[`GeodesicArea`]**: Calculate the geodesic area and perimeter of a geometry on an ellipsoid using the algorithm presented in _Algorithms for geodesics_ by Charles Karney (2013) +//! Algorithms for measures along a line, and how a line is measured. //! -//! ## Boolean Operations +//! ### Metric Spaces //! -//! - **[`BooleanOps`]**: combine or split (Multi)Polygons using intersecton, union, xor, or difference operations +//! - **[`Euclidean`]**: The [Euclidean plane] measures distance with the pythagorean formula. Not suitable for lon/lat geometries. +//! - **[`Haversine`]**: The [Haversine Formula] measures distance on a sphere. Only suitable for lon/lat geometries. +//! - **[`Geodesic`]**: Geodesic methods based on [Karney (2013)] more accurately reflect the shape of the Earth, but are slower than Haversine. Only suitable for lon/lat geometries. +//! - **[`Rhumb`]**: [Rhumb line] (a.k.a. loxodrome) measures can be useful for navigation applications where maintaining a constant bearing or direction is important. Only suitable for lon/lat geometries. //! -//! ## Distance +//! ### Operations on Metric Spaces +//! +//! - **[`Distance`]**: Calculate the minimum distance between two geometries. +//! - **[`Length`]**: Calculate the length of a `Line`, `LineString`, or `MultiLineString`. +//! - **[`Bearing`]**: Calculate the bearing between two points. +//! +//! - **[`Destination`]**: Calculate the destination point from an origin point, given a bearing and a distance. +//! - **[`InterpolatePoint`]**: Interpolate points along a line. +//! - **[`Densify`]**: Insert points into a geometry so there is never more than `max_segment_length` between points. +//! +//! ### Misc measures //! -//! - **[`EuclideanDistance`]**: Calculate the minimum euclidean distance between geometries -//! - **[`GeodesicDistance`]**: Calculate the minimum geodesic distance between geometries using the algorithm presented in _Algorithms for geodesics_ by Charles Karney (2013) //! - **[`HausdorffDistance`]**: Calculate "the maximum of the distances from a point in any of the sets to the nearest point in the other set." (Rote, 1991) -//! - **[`HaversineDistance`]**: Calculate the minimum geodesic distance between geometries using the haversine formula -//! - **[`RhumbDistance`]**: Calculate the length of a rhumb line connecting the two geometries //! - **[`VincentyDistance`]**: Calculate the minimum geodesic distance between geometries using Vincenty’s formula +//! - **[`VincentyLength`]**: Calculate the geodesic length of a geometry using Vincenty’s formula +//! - **[`FrechetDistance`]**: Calculate the similarity between [`LineString`]s using the Fréchet distance //! -//! ## Length +//! ## Area //! -//! - **[`EuclideanLength`]**: Calculate the euclidean length of a geometry -//! - **[`GeodesicLength`]**: Calculate the geodesic length of a geometry using the algorithm presented in _Algorithms for geodesics_ by Charles Karney (2013) -//! - **[`HaversineLength`]**: Calculate the geodesic length of a geometry using the haversine formula -//! - **[`RhumbLength`]**: Calculate the length of a geometry assuming it's composed of rhumb lines -//! - **[`VincentyLength`]**: Calculate the geodesic length of a geometry using Vincenty’s formula +//! - **[`Area`]**: Calculate the planar area of a geometry +//! - **[`ChamberlainDuquetteArea`]**: Calculate the geodesic area of a geometry on a sphere using the algorithm presented in _Some Algorithms for Polygons on a Sphere_ by Chamberlain and Duquette (2007) +//! - **[`GeodesicArea`]**: Calculate the geodesic area and perimeter of a geometry on an ellipsoid using the algorithm presented in _Algorithms for geodesics_ by Charles Karney (2013) +//! +//! ## Boolean Operations +//! +//! - **[`BooleanOps`]**: combine or split (Multi)Polygons using intersecton, union, xor, or difference operations //! //! ## Outlier Detection //! @@ -72,9 +83,6 @@ //! //! ## Query //! -//! - **[`HaversineBearing`]**: Calculate the bearing between points using great circle calculations. -//! - **[`GeodesicBearing`]**: Calculate the bearing between points on a [geodesic](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid) -//! - **[`RhumbBearing`]**: Calculate the angle from north of the rhumb line connecting two points. //! - **[`ClosestPoint`]**: Find the point on a geometry //! closest to a given point //! - **[`HaversineClosestPoint`]**: Find the point on a geometry @@ -87,10 +95,6 @@ //! fraction of a line’s total length representing the location of the closest point on the //! line to the given point //! -//! ## Similarity -//! -//! - **[`FrechetDistance`]**: Calculate the similarity between [`LineString`]s using the Fréchet distance -//! //! ## Topology //! //! - **[`Contains`]**: Calculate if a geometry contains another @@ -156,14 +160,6 @@ //! //! - **[`Centroid`]**: Calculate the centroid of a geometry //! - **[`ChaikinSmoothing`]**: Smoothen `LineString`, `Polygon`, `MultiLineString` and `MultiPolygon` using Chaikin's algorithm. -//! - **[`Densify`]**: Densify linear geometry components by interpolating points -//! - **[`DensifyHaversine`]**: Densify spherical geometry by interpolating points on a sphere -//! - **[`GeodesicDestination`]**: Given a start point, bearing, and distance, calculate the destination point on a [geodesic](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid) -//! - **[`GeodesicIntermediate`]**: Calculate intermediate points on a [geodesic](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid) -//! - **[`HaversineDestination`]**: Given a start point, bearing, and distance, calculate the destination point on a sphere assuming travel on a great circle -//! - **[`HaversineIntermediate`]**: Calculate intermediate points on a sphere along a great-circle line -//! - **[`RhumbDestination`]**: Given a start point, bearing, and distance, calculate the destination point on a sphere assuming travel along a rhumb line -//! - **[`RhumbIntermediate`]**: Calculate intermediate points on a sphere along a rhumb line //! - **[`proj`]**: Project geometries with the `proj` crate (requires the `use-proj` feature) //! - **[`LineStringSegmentize`]**: Segment a LineString into `n` segments. //! - **[`LineStringSegmentizeHaversine`]**: Segment a LineString using Haversine distance. @@ -197,9 +193,12 @@ //! * [Geocoding][geocoding crate] //! * [and much more...][georust website] //! +//! [Euclidean plane]: https://en.wikipedia.org/wiki/Euclidean_plane //! [`geo-types`]: https://crates.io/crates/geo-types +//! [haversine formula]: https://en.wikipedia.org/wiki/Haversine_formula// //! [`proj` crate]: https://github.com/georust/proj //! [geojson crate]: https://crates.io/crates/geojson +//! [Karney (2013)]: https://arxiv.org/pdf/1109.4448.pdf //! [wkt crate]: https://crates.io/crates/wkt //! [shapefile crate]: https://crates.io/crates/shapefile //! [latlng crate]: https://crates.io/crates/latlon @@ -212,6 +211,7 @@ //! [network grid]: https://proj.org/usage/network.html //! [OGC-SFA]: https://www.ogc.org/standards/sfa //! [proj crate file download]: https://docs.rs/proj/*/proj/#grid-file-download +//! [rhumb line]: https://en.wikipedia.org/wiki/Rhumb_line //! [Serde]: https://serde.rs/ #[cfg(feature = "use-serde")]