## geogram_predicates

Rust bindings to the Geogram library's predicates module

### 9 releases

 0.1.9 Jun 7, 2024 May 6, 2024 Apr 29, 2024

#237 in Math

Apache-2.0

425KB
12K SLoC

# Geogram Predicates

A crate for rust interoperability with `geogram`s robust predicates; via `cxx`.

Geogram is a scientifically proven, well-documented, feature-rich geometry processing library, which leverages "[...] arithmetic filters (Meyer and Pion), expansion arithmetics (Shewchuk) and simulation of simplicity (Edelsbrunner)."
Be sure to check it out here.

It yields easy access to dependecy-free parts of its code base, as so called Pluggable Software Modules (PSM), which in turn make it easy to write `cxx_bridges` for these.

## Example

With that, you can add geometry predicates to your rust project, without the need to re-implement existing state-of-the-art software. E.g. using geograms incircle predicate for triangles in `rust` looks like this:

``````use geogram_predicates as gp

// Define three points that form a triangle
let a = [0.0, 0.0];
let b = [2.0, 0.0];
let c = [1.0, 1.0];

// Define two points, to test against the triangles circum-circle
let p_in = [1.0, -0.4];
let p_out = [1.0, -1.2];

let is_in_circle_p_in = gp::in_circle_2d_SOS(&a, &b, &c, &p_in);
assert_eq!(1, is_in_circle_p_in);

let is_in_circle_p_out = gp::in_circle_2d_SOS(&a, &b, &c, &p_out);
assert_eq!(-1, is_in_circle_p_out);

// Do something fancy based on the result
// ...
``````

## Visualizing Advantages of Robust Predicates

Below are visualizations comparing naive and robust `orient_2d` & `in_circle_2d` implementations. You can generate these images yourself by running the examples for `orient_2d` or `in_circle_2d`.

Naive Robust
`orient_2d`
`in_circle_2d`

## List of currently supported predicates

### 2D

• in_circle_2D_SOS()
• orient_2d()
• orient_2dlifted_SOS()
• points_are_identical_2d()

### 3D

• det_3d()
• in_sphere_3d_SOS()
• orient_3d()
• orient_3dlifted_SOS()
• points_are_identical_3d()

### Other

• det_4d()
• geo_sgn()
• initialize()
• show_stats()
• terminate()

There are a lot of predictes still to be implemented. If you are in need for a specific one have a look at the geograms predicate list. The bridge for any one predicate is implemented pretty quickly, so this crate is easily extendable.

## Design

The API to the `geogram predicates` is designed with the following design principles in mind:

• Relation to geogram: the function names, signatures and doc strings should be as close as possible to the original. This keeps maintaining, updating and comparing as simple as possible

## Contribution

If you see something as

• a missing geogram predicate,
• software desing principles that could be improved,
• potential bugs,
• ambiguous documentation, typos etc.,
• ...

feel free to open a PR to address this.

## Acknowledgements

Credits go to geogram and cxx, which make this project possible.

Also georust/robust should be mentioned, for helping set up the examples and their visualizations.

The files in `include/geogram_predicates_psm` are licensed w.r.t.