Skip to main content

Crate boost_geometry

Crate boost_geometry 

Source
Expand description

§geometry

A Rust port of Boost.Geometry, following the same philosophy: dimension-agnostic, coordinate-system-agnostic, bring-your-own-type, strategy-pluggable.

Add this crate alone to your Cargo.toml to use the library. See prelude for the recommended star-imports.

Layered design — each module is a re-export of one underlying crate:

  • tag — geometry kind tags + tag-hierarchy marker traits
  • coords — coordinate scalars, type promotion, Comparable<T>
  • cs — coordinate systems and reference spheroids
  • trait_ — the concepts: Geometry, Point, Linestring, …
  • model — default concrete types (Point2D, Polygon, …)
  • strategy — pluggable strategies per algorithm × CS family
  • algorithm — free functions users call (distance, area, …)
  • adapt — Adapt<T>, WithCs<T, Cs>, register macros

The umbrella mirrors boost/geometry/geometry.hpp: one entry-point that fans out into every public sub-namespace.

§End-user walkthrough

The proposal’s §5 end-user surface, fully runnable. Each fenced block below compiles as a doctest, so the examples cannot drift from the actual API surface.

§Cartesian distance — picks Pythagoras by default

use boost_geometry::prelude::*;

let a = Point2D::<f64, Cartesian>::new(0.0, 0.0);
let b = Point2D::<f64, Cartesian>::new(3.0, 4.0);
assert_eq!(distance(&a, &b), 5.0);

// Compare cheaply — no `sqrt`:
assert_eq!(comparable_distance(&a, &b), 25.0);

§Spherical distance — Haversine on the unit sphere

Multiplying the unit-sphere angle by a radius (km, miles, …) gives the surface distance in that unit. This mirrors the quick_start.cpp Amsterdam → Paris example from Boost.Geometry.

use boost_geometry::prelude::*;
use boost_geometry::adapt::{Adapt, WithCs};
use boost_geometry::strategy::spherical::Haversine;

let ams = WithCs::<_, Spherical<Degree>>::new(Adapt([4.90_f64, 52.37]));
let par = WithCs::<_, Spherical<Degree>>::new(Adapt([2.35_f64, 48.86]));
let angle = distance_with(&ams, &par, Haversine::UNIT);
let miles = angle * 3959.0;
assert!((miles - 267.02).abs() < 0.05);

§Geographic distance — Andoyer (default) and Vincenty (explicit) on WGS84

use boost_geometry::prelude::*;
use boost_geometry::adapt::{Adapt, WithCs};
use boost_geometry::strategy::geographic::Vincenty;

let ams = WithCs::<_, Geographic<Degree>>::new(Adapt([4.90_f64, 52.37]));
let par = WithCs::<_, Geographic<Degree>>::new(Adapt([2.35_f64, 48.86]));

// No strategy argument — picks Andoyer for the geographic family.
let m_a = distance(&ams, &par);
// Same pair through Vincenty — agrees with Andoyer to within metres.
let m_v = distance_with(&ams, &par, Vincenty::WGS84);
assert!((m_a - m_v).abs() < 50.0);
assert!(((m_a / 1_000.0) - 430.0).abs() < 1.0);

§#[derive(Point)] — your own struct as a Point

For the common case (“a struct with x and y”), the derive macro generates the Point impl. The macro plays the role of BOOST_GEOMETRY_REGISTER_POINT_2D on the C++ side.

use boost_geometry::Point;            // the derive macro
use boost_geometry::prelude::*;       // brings in `Point` (the trait) and `distance`

#[derive(Default, Point)]
#[geometry(cs = "Cartesian", scalar = "f64")]
struct MyXy { x: f64, y: f64 }

let d = distance(&MyXy { x: 0.0, y: 0.0 }, &MyXy { x: 3.0, y: 4.0 });
assert_eq!(d, 5.0);

§Adapt<T> — foreign data layouts (arrays, tuples)

For types you do not own ([T; N], (T, T), third-party point types), wrap them in adapt::Adapt. The wrapper defaults the coordinate system to Cartesian — for any other CS layer adapt::WithCs on top (see the spherical / geographic examples above).

use boost_geometry::prelude::*;
use boost_geometry::adapt::Adapt;

let a = Adapt([0.0_f64, 0.0]);
let b = Adapt([3.0_f64, 4.0]);
assert_eq!(distance(&a, &b), 5.0);

§Polygon, area, point-in-polygon

The polygon!, linestring!, and point! literal macros are #[macro_export]ed by geometry-model, so they are reachable as geometry_model::polygon! once the geometry crate is in your dependency tree.

use boost_geometry::prelude::*;
use boost_geometry::model::Polygon;
use geometry_model::polygon;

// Ring traversed clockwise (the default `PointOrder` for `Ring`).
let p: Polygon<Point2D<f64, Cartesian>> = polygon![
    [(0.0, 0.0), (0.0, 3.0), (4.0, 3.0), (4.0, 0.0), (0.0, 0.0)]
];
assert_eq!(area(&p), 12.0);
assert!(within(&Point2D::<f64, Cartesian>::new(2.0, 1.0), &p));
assert!(!within(&Point2D::<f64, Cartesian>::new(5.0, 5.0), &p));

§See also

Modules§

adapt
Adapters for foreign types — Adapt<T>, WithCs<T, Cs>, and the register_*! macros.
algorithm
Free-function algorithm entry points — distance, area, …
coords
Coordinate scalars, type promotion, and the comparable-distance wrapper.
cs
Coordinate systems, angle units, and reference spheroids.
model
Default concrete geometry types.
overlay
Re-exports every item from geometry-overlay — the boolean overlay engine (intersection, union, difference, sym_difference) and its predicate / turn-graph / traversal layers.
prelude
Conventional star-imports for end users:
rtree
Re-exports every item from geometry-rtree — the R-tree spatial index (Rtree, Predicate, split strategies, bulk load).
strategy
Pluggable algorithm strategies per coordinate-system family.
tag
Geometry kind tags and the tag-hierarchy marker traits.
trait_
Geometry concept traits — Geometry, Point, Linestring, …

Derive Macros§

Point
#[derive(Point)]. Re-exported so users only need a single geometry dependency in their Cargo.toml. #[derive(Point)] — see the crate-level docs for the attribute shape.