83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 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.
|
|
|
|
<a href="https://observablehq.com/@mourner/non-robust-arithmetic-as-art"><img width="600" height="200" src="predicates.png" /></a>
|
|
|
|
_Figure: non-robust vs robust `orient2d` test for points within a tiny range (2<sup>-42</sup>)._
|
|
|
|
[](https://github.com/mourner/robust-predicates/actions)
|
|
[](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).
|