package.README.md Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of robust-predicates Show documentation
Show all versions of robust-predicates Show documentation
Fast robust predicates for computational geometry
The newest version!
# robust-predicates
Fast robust predicates for computational geometry in JavaScript. Provides reliable 2D and 3D point orientation tests (`orient2d`, `orient3d`, `incircle`, `insphere`) that are not susceptible to floating point errors (without sacrificing performance). A modern port of [Jonathan R Shewchuk's C code](https://www.cs.cmu.edu/~quake/robust.html), an industry standard since 1996.
_Figure: non-robust vs robust `orient2d` test for points within a tiny range (2-42)._
[](https://travis-ci.com/mourner/robust-predicates)
[](https://github.com/mourner/projects)
[](https://unpkg.com/robust-predicates)
## [Demo](https://observablehq.com/@mourner/non-robust-arithmetic-as-art)
## API
Note: unlike J. Shewchuk's original code, all the functions in this library assume `y` axis is oriented _downwards_ ↓, so the semantics are different.
### `orient2d(ax,ay, bx,by, cx,cy)`
- Returns a *positive* value if the points `a`, `b`, and `c` occur in _counterclockwise_ order (`c` lies to the left of the directed line defined by points `a` and `b`).
- Returns a *negative* value if they occur in _clockwise_ order (`c` lies to the right of the directed line `ab`).
- Returns *zero* if they are _collinear_.
The result is also an approximation of twice the signed area of the triangle defined by the three points.
### `incircle(ax,ay, bx,by, cx,cy, dx,dy)`
- Returns a _positive_ value if the point `d` lies _outside_ the circle passing through `a`, `b`, and `c`.
- Returns a _negative_ value if it lies _inside_.
- Returns _zero_ if the four points are _cocircular_.
The points `a`, `b`, and `c` must be in _counterclockwise_ order, or the sign of the result will be reversed.
### `orient3d(ax,ay,az, bx,by,bz, cx,cy,cz, dx,dy,dz)`
- Returns a _positive_ value if the point `d` lies _above_ the plane passing through `a`, `b`, and `c`, meaning that `a`, `b`, and `c` appear in counterclockwise order when viewed from `d`.
- Returns a _negative_ value if `d` lies _below_ the plane.
- Returns _zero_ if the points are _coplanar_.
The result is also an approximation of six times the signed volume of the tetrahedron defined by the four points.
### `insphere(ax,ay,az, bx,by,bz, cx,cy,cz, dx,dy,dz, ex,ey,ez)`
- Returns a _positive_ value if the point `e` lies _outside_ the sphere passing through `a`, `b`, `c`, and `d`.
- Returns a _negative_ value if it lies _inside_.
- Returns _zero_ if the five points are _cospherical_.
The points `a`, `b`, `c`, and `d` must be ordered so that they have a _positive orientation_
(as defined by `orient3d`), or the sign of the result will be reversed.
### `orient2dfast`, `orient3dfast`, `incirclefast`, `inspherefast`
Simple, approximate, non-robust versions of predicates above. Use when robustness isn't needed.
## Example
```js
import {orient2d} from 'robust-predicates';
const ccw = orient2d(ax, ay, bx, by, cx, cy) > 0;
````
## Install
Install with `npm install robust-predicates` or `yarn add robust-predicates`, or use one of the browser builds:
- [predicates.min.js](https://unpkg.com/robust-predicates/umd/predicates.min.js) (all predicates)
- [orient2d.min.js](https://unpkg.com/robust-predicates/umd/orient2d.min.js) (`orient2d`, `orient2dfast`)
- [orient3d.min.js](https://unpkg.com/robust-predicates/umd/orient3d.min.js) (`orient3d`, `orient3dfast`)
- [incircle.min.js](https://unpkg.com/robust-predicates/umd/incircle.min.js) (`incircle`, `incirclefast`)
- [insphere.min.js](https://unpkg.com/robust-predicates/umd/insphere.min.js) (`insphere`, `inspherefast`)
## Thanks
This project is just a port — all the brilliant, hard work was done by [Jonathan Richard Shewchuk](https://people.eecs.berkeley.edu/~jrs/).
The port was also inspired by [Mikola Lysenko](https://twitter.com/MikolaLysenko)'s excellent [Robust Arithmetic Notes](https://github.com/mikolalysenko/robust-arithmetic-notes) and related projects like [robust-orientation](https://github.com/mikolalysenko/robust-orientation) and [robust-in-sphere](https://github.com/mikolalysenko/robust-in-sphere).
## License
Since the original code is in the public domain, this project follows the same choice. See [Unlicense](https://unlicense.org).