Poisson disk sampling in arbitrary dimensions
MIT License
Poisson disk sampling in arbitrary dimensions.
With npm do:
npm install poisson-disk-sampling
With yarn do:
yarn add poisson-disk-sampling
A compiled version for web browsers is also available on a CDN:
<script src="https://cdn.jsdelivr.net/gh/kchapelier/[email protected]/build/poisson-disk-sampling.min.js"></script>
var p = new PoissonDiskSampling({
shape: [600, 300, 200],
minDistance: 20,
maxDistance: 30,
tries: 10
});
var points = p.fill();
console.log(points); // array of sample points, themselves represented as simple arrays
var p = new PoissonDiskSampling({
shape: [500, 500],
minDistance: 1,
maxDistance: 30,
tries: 20,
distanceFunction: function (p) {
return getImagePixelValueSomehow(p[0], p[1]); // value between 0 and 1
}
});
var points = p.fill();
console.log(points); // array of sample points, themselves represented as simple arrays
new PoissonDiskSampling(options[, rng])
The following code will allow the generation of points where both coordinates will range from 0 up to 50 (including 0, but not including 50, 0 <= c < 50).
// Poisson disk sampling in a 2D square
var pds = new PoissonDiskSampling({
shape: [50, 50],
minDistance: 4,
maxDistance: 4,
tries: 10
});
// Poisson disk sampling in a 3D volume
var pds = new PoissonDiskSampling({
shape: [900, 400, 400],
minDistance: 20,
maxDistance: 25,
tries: 10
});
// Poisson disk sampling in a 2D square using
// a custom function to drive the distance between each point
var pds = new PoissonDiskSampling({
shape: [400, 400],
minDistance: 4,
maxDistance: 20,
tries: 20,
distanceFunction: function (point) {
return point[0] / 400;
},
bias: 0
});
pds.fill()
Fill the grid with random points following the distance constraint.
Returns the entirety of the points in the grid as an array of coordinate arrays. The points are sorted in their generation order.
var points = pds.fill();
console.log(points[0]);
// prints something like [30, 16]
pds.getAllPoints()
Get all the points present in the grid without trying to generate any new points.
Returns the entirety of the points in the grid as an array of coordinate arrays. The points are sorted in their generation order.
var points = pds.getAllPoints();
console.log(points[0]);
// prints something like [30, 16]
pds.getAllPointsWithDistance()
Get all the points present in the grid along with the result of the distance function.
Returns the entirety of the points in the grid as an array of coordinate + distance function result arrays. The points are sorted in their generation order.
Calling this method on an instance of PoissonDiskSampling without a distanceFunction will throw an error.
var points = pds.getAllPointsWithDistance();
console.log(points[0]);
// prints something like [30, 16, 0.4], 0.4 being the result of the distance function
pds.addRandomPoint()
Add a completely random point to the grid. There won't be any check on the distance constraint with the other points already present in the grid.
Returns the point as a coordinate array.
pds.addPoint(point)
Add an arbitrary point to the grid. There won't be any check on the distance constraint with the other points already present in the grid.
Returns the point added to the grid.
If the point given is not of the correct dimension (i.e. inserting a 2D point in a 3D grid) or doesn't fit in the grid size, null will be returned.
pds.addPoint([20, 30, 40]);
pds.next()
Try to generate a new point in the grid following the distance constraint.
Returns a coordinate array when a point is generated, null otherwise.
var point;
while(point = pds.next()) {
console.log(point); // [x, y, z]
}
pds.reset()
Reinitialize the grid as well as the internal state.
When doing multiple samplings in the same grid, it is preferable to reuse the same instance of PoissonDiskSampling instead of creating a new one for each sampling.
Internally, there are two different implementations of the algorithm. The implementation is chosen depending on whether a distanceFunction is passed to the constructor. The library is designed in such a way as to keep it transparent to the end user.
In order to reduce the impact of this dependency on the size of the javascript bundle(s) in web projects, it is possible to explicitly require a given implementation.
var PoissonDiskSampling = require('poisson-disk-sampling/src/implementations/fixed-density');
or
var PoissonDiskSampling = require('poisson-disk-sampling/src/implementations/variable-density');
TypeScripts definitions (.d.ts
) provided by Aliyss are available through DefinitelyTyped. They can be installed locally using the following commands:
npm install --save-dev @types/poisson-disk-sampling
or
yarn add @types/poisson-disk-sampling --dev
Due to an issue on npmjs.com this version was not listed on the website even though it was available through the CLI.
moore
depgetAllPoints()
and reset()
maxDistance
when it is not setfill()
is called several timesmathp
dependencyFor new features and other enhancements, please make sure to contact me beforehand, either on Twitter or through an issue on Github.
MIT