Crate geo

The geo crate provides geospatial primitive types and algorithms.

Types

• Coord: A two-dimensional coordinate. All geometry types are composed of Coords, though Coord itself is not a Geometry type.
• Point: A single point represented by one Coord
• MultiPoint: A collection of Points
• Line: A line segment represented by two Coords
• LineString: A series of contiguous line segments represented by two or more Coords
• MultiLineString: A collection of LineStrings
• Polygon: A bounded area represented by one LineString exterior ring, and zero or more LineString interior rings
• MultiPolygon: A collection of Polygons
• Rect: An axis-aligned bounded rectangle represented by minimum and maximum Coords
• Triangle: A bounded area represented by three Coord vertices
• GeometryCollection: A collection of Geometrys
• Geometry: An enumeration of all geometry types, excluding Coord

The preceding types are reexported from the geo-types crate. Consider using that crate if you only need access to these types and no other geo functionality.

Semantics

The geospatial types provided here aim to adhere to the OpenGIS Simple feature access standards. Thus, the types here are inter-operable with other implementations of the standards: JTS, GEOS, etc.

Algorithms

Measures

Algorithms for measures along a line, and how a line is measured.

Metric Spaces

• 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.

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

• 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)
• 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 LineStrings using the Fréchet distance

Area

• 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

• OutlierDetection: Detect outliers in a group of points using LOF

Simplification

• Simplify: Simplify a geometry using the Ramer–Douglas–Peucker algorithm
• SimplifyIdx: Calculate a simplified geometry using the Ramer–Douglas–Peucker algorithm, returning coordinate indices
• SimplifyVw: Simplify a geometry using the Visvalingam-Whyatt algorithm
• SimplifyVwPreserve: Simplify a geometry using a topology-preserving variant of the Visvalingam-Whyatt algorithm
• SimplifyVwIdx: Calculate a simplified geometry using the Visvalingam-Whyatt algorithm, returning coordinate indices

Query

• ClosestPoint: Find the point on a geometry closest to a given point
• HaversineClosestPoint: Find the point on a geometry closest to a given point on a sphere using spherical coordinates and lines being great arcs.
• IsConvex: Calculate the convexity of a LineString
• LineInterpolatePoint: Generates a point that lies a given fraction along the line
• LineLocatePoint: Calculate the fraction of a line’s total length representing the location of the closest point on the line to the given point

Topology

• Contains: Calculate if a geometry contains another geometry
• CoordinatePosition: Calculate the position of a coordinate relative to a geometry
• HasDimensions: Determine the dimensions of a geometry
• Intersects: Calculate if a geometry intersects another geometry
• line_intersection: Calculates the intersection, if any, between two lines.
• Relate: Topologically relate two geometries based on DE-9IM semantics.
• Within: Calculate if a geometry lies completely within another geometry.

Triangulation

• TriangulateEarcut: Triangulate polygons using the earcut algorithm. Requires the "earcutr" feature, which is enabled by default.

Winding

• Orient: Apply a specified winding Direction to a Polygon’s interior and exterior rings
• Winding: Calculate and manipulate the WindingOrder of a LineString

Iteration

• CoordsIter: Iterate over the coordinates of a geometry
• MapCoords: Map a function over all the coordinates in a geometry, returning a new geometry
• MapCoordsInPlace: Map a function over all the coordinates in a geometry in-place
• LinesIter: Iterate over lines of a geometry

Boundary

• BoundingRect: Calculate the axis-aligned bounding rectangle of a geometry
• MinimumRotatedRect: Calculate the minimum bounding box of a geometry
• ConcaveHull: Calculate the concave hull of a geometry
• ConvexHull: Calculate the convex hull of a geometry
• Extremes: Calculate the extreme coordinates and indices of a geometry

Affine transformations

• Rotate: Rotate a geometry around its centroid
• Scale: Scale a geometry up or down by a factor
• Skew: Skew a geometry by shearing angles along the x and y dimension
• Translate: Translate a geometry along its axis
• AffineOps: generalised composable affine operations

Conversion

• Convert: Convert (infalliby) the type of a geometry’s coordinate value
• TryConvert: Convert (falliby) the type of a geometry’s coordinate value
• ToDegrees: Radians to degrees coordinate transforms for a given geometry.
• ToRadians: Degrees to radians coordinate transforms for a given geometry.

Miscellaneous

• Centroid: Calculate the centroid of a geometry
• ChaikinSmoothing: Smoothen LineString, Polygon, MultiLineString and MultiPolygon using Chaikin’s algorithm.
• [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.
• [Transform]: Transform a geometry using Proj.
• RemoveRepeatedPoints: Remove repeated points from a geometry.

Spatial Indexing

geo geometries (Point, Line, LineString, Polygon) can be used with the rstar R*-tree crate for fast distance and nearest-neighbour queries. Multi- geometries can be added to the tree by iterating over their members and adding them. Note in particular the availability of the bulk_load method and GeomWithData struct.

Features

The following optional Cargo features are available:

• earcutr:
  • Enables the earcutr crate, which provides triangulation of polygons using the earcut algorithm.
  • ☑ Enabled by default.
• proj-network:
  • Enables network grid support for the proj crate.
  • After enabling this feature, further configuration is required to use the network grid.
  • ☐ Disabled by default.
• use-proj:
  • Enables coordinate conversion and transformation of Point geometries using the proj crate
  • ☐ Disabled by default.
• use-serde:
  • Allows geometry types to be serialized and deserialized with Serde.
  • ☐ Disabled by default.
• multithreading:
  • Enables multithreading support for the i_overlay crate (via Rayon), and activates the multithreading flag in geo-types, enabling multi-threaded iteration over Multi* geometries.
  • ☑ Enabled by default.

Ecosystem

There’s a wide variety of geo-compatible crates in the ecosystem that offer functionality not included in the geo crate, including:

• Reading and writing file formats (e.g. GeoJSON, WKT, shapefile)
• Latitude and longitude parsing
• Label placement
• Geocoding
• and much more…

Re-exports

• pub use crate::relate::PreparedGeometry;
• pub use crate::algorithm::*;
• pub use geometry::*;

Modules

• algorithm
  This module includes all the functions of geometric calculations
• geometry
  This module makes all geometry types available
• prelude
  A prelude which re-exports the traits for manipulating objects in this crate. Typically imported with use geo::prelude::*.

Macros

• coord
  Creates a Coord from the given scalars.
• geometry_delegate_impl
  Implements the common pattern where a Geometry enum simply delegates its trait impl to it’s inner type.
• line_string
  Creates a LineString containing the given coordinates.
• point
  Creates a Point from the given coordinates.
• polygon
  Creates a Polygon containing the given coordinates.
• wkt
  Creates a crate::geometry from a WKT literal.

Enums

• Closest
  The result of trying to find the closest spot on an object to a point.

Traits

• CoordFloat
  For algorithms which can only use floating point Points/Coords, like area or length calculations
• CoordNum
  For algorithms which can use both integer and floating point Points/Coords
• GeoFloat
  A common numeric trait used for geo algorithms
• GeoNum
  A trait for methods which work for both integers and floating point