{"id":16533823,"url":"https://github.com/kchapelier/poisson-disk-sampling","last_synced_at":"2025-04-05T13:08:47.144Z","repository":{"id":40558694,"uuid":"45303145","full_name":"kchapelier/poisson-disk-sampling","owner":"kchapelier","description":"Poisson disk sampling in arbitrary dimensions","archived":false,"fork":false,"pushed_at":"2022-10-10T19:39:25.000Z","size":437,"stargazers_count":216,"open_issues_count":0,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-18T21:20:16.582Z","etag":null,"topics":["arbitrary-dimensions","javascript","poisson","procedural-generation","sampling"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kchapelier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-31T13:42:09.000Z","updated_at":"2024-10-17T01:14:23.000Z","dependencies_parsed_at":"2022-09-21T01:50:20.963Z","dependency_job_id":null,"html_url":"https://github.com/kchapelier/poisson-disk-sampling","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kchapelier%2Fpoisson-disk-sampling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kchapelier%2Fpoisson-disk-sampling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kchapelier%2Fpoisson-disk-sampling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kchapelier%2Fpoisson-disk-sampling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kchapelier","download_url":"https://codeload.github.com/kchapelier/poisson-disk-sampling/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arbitrary-dimensions","javascript","poisson","procedural-generation","sampling"],"created_at":"2024-10-11T18:15:56.042Z","updated_at":"2025-04-05T13:08:47.116Z","avatar_url":"https://github.com/kchapelier.png","language":"JavaScript","readme":"# poisson-disk-sampling\n\n[![Build Status](https://travis-ci.org/kchapelier/poisson-disk-sampling.svg)](https://travis-ci.org/kchapelier/poisson-disk-sampling) [![NPM version](https://badge.fury.io/js/poisson-disk-sampling.svg)](http://badge.fury.io/js/poisson-disk-sampling)\n\nPoisson disk sampling in arbitrary dimensions.\n\n## Installing\n\nWith [npm](https://www.npmjs.com/) do:\n\n```\nnpm install poisson-disk-sampling\n```\n\nWith [yarn](https://yarnpkg.com/) do:\n\n```\nyarn add poisson-disk-sampling\n```\n\nA compiled version for web browsers is also available on a CDN:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/kchapelier/poisson-disk-sampling@2.3.1/build/poisson-disk-sampling.min.js\"\u003e\u003c/script\u003e\n```\n\n## Features\n\n- Can be used in any dimension (1D, 2D, 3D and more).\n- Can be used with a custom RNG function.\n- Allow the configuration of the max number of tries, the minimum distance and the maximum distance between each points.\n- Allow the use of custom function to drive the density of the distribution.\n- Similar general API as [fast-2d-poisson-disk-sampling](https://github.com/kchapelier/fast-2d-poisson-disk-sampling) and [jittered-hexagonal-grid-sampling](https://github.com/kchapelier/jittered-hexagonal-grid-sampling).\n\n## Basic example\n\n```js\nvar p = new PoissonDiskSampling({\n    shape: [600, 300, 200],\n    minDistance: 20,\n    maxDistance: 30,\n    tries: 10\n});\nvar points = p.fill();\n\nconsole.log(points); // array of sample points, themselves represented as simple arrays\n```\n\n### Result as an image\n\n\u003cimg src=\"https://github.com/kchapelier/poisson-disk-sampling/raw/master/img/example1.png\" style=\"image-rendering:pixelated; width:500px;\"\u003e\u003c/img\u003e\n\n## Example with an image driving the distribution density\n\n```js\nvar p = new PoissonDiskSampling({\n    shape: [500, 500],\n    minDistance: 1,\n    maxDistance: 30,\n    tries: 20,\n    distanceFunction: function (p) {\n        return getImagePixelValueSomehow(p[0], p[1]); // value between 0 and 1\n    }\n});\nvar points = p.fill();\n\nconsole.log(points); // array of sample points, themselves represented as simple arrays\n```\n\n### Result as an image\n\n\u003cimg src=\"https://github.com/kchapelier/poisson-disk-sampling/raw/master/img/example2.png\" style=\"image-rendering:pixelated; width:500px;\"\u003e\u003c/img\u003e\n\n### Complete working example\n\n[Demo online](http://www.kchapelier.com/poisson-disk-sampling/examples/distance-function-with-images-in-browser/) | [Source code](https://github.com/kchapelier/poisson-disk-sampling/tree/master/examples/distance-function-with-images-in-browser/)\n\n## Public API\n\n### Constructor\n\n**new PoissonDiskSampling(options[, rng])**\n\n- *options :*\n  - *shape :* Size/dimensions of the grid to generate points in, required.\n  - *minDistance :* Minimum distance between each points, required.\n  - *maxDistance :* Maximum distance between each points, defaults to minDistance times 2.\n  - *tries :* Maximum number of tries to generate a point, defaults to 30.\n  - *distanceFunction :* Function to control the distance between each point depending on their position, must return a value between 0 and 1.\n  - *bias :* When using a distanceFunction, will indicate which point constraint takes priority when evaluating two points (0 for the lowest distance, 1 for the highest distance), defaults to 0.\n- *rng :* A function to use as random number generator, defaults to Math.random.\n\nThe 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 \u003c= c \u003c 50**).\n\n```js\n// Poisson disk sampling in a 2D square\nvar pds = new PoissonDiskSampling({\n    shape: [50, 50],\n    minDistance: 4,\n    maxDistance: 4,\n    tries: 10\n});\n```\n\n```js\n// Poisson disk sampling in a 3D volume\nvar pds = new PoissonDiskSampling({\n    shape: [900, 400, 400],\n    minDistance: 20,\n    maxDistance: 25,\n    tries: 10\n});\n```\n\n```js\n// Poisson disk sampling in a 2D square using\n// a custom function to drive the distance between each point\nvar pds = new PoissonDiskSampling({\n    shape: [400, 400],\n    minDistance: 4,\n    maxDistance: 20,\n    tries: 20,\n    distanceFunction: function (point) {\n        return point[0] / 400;\n    },\n    bias: 0\n});\n```\n\n### Method\n\n**pds.fill()**\n\nFill the grid with random points following the distance constraint.\n\nReturns the entirety of the points in the grid as an array of coordinate arrays. The points are sorted in their generation order.\n\n```js\nvar points = pds.fill();\n\nconsole.log(points[0]);\n// prints something like [30, 16]\n```\n\n**pds.getAllPoints()**\n\nGet all the points present in the grid without trying to generate any new points.\n\nReturns the entirety of the points in the grid as an array of coordinate arrays. The points are sorted in their generation order.\n\n```js\nvar points = pds.getAllPoints();\n\nconsole.log(points[0]);\n// prints something like [30, 16]\n```\n\n**pds.getAllPointsWithDistance()**\n\nGet all the points present in the grid along with the result of the distance function.\n\nReturns 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.\n\nCalling this method on an instance of PoissonDiskSampling without a distanceFunction will throw an error.\n\n```js\nvar points = pds.getAllPointsWithDistance();\n\nconsole.log(points[0]);\n// prints something like [30, 16, 0.4], 0.4 being the result of the distance function\n```\n\n**pds.addRandomPoint()**\n\nAdd 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.\n\nReturns the point as a coordinate array.\n\n**pds.addPoint(point)**\n\n- *point :* Point represented as a coordinate array.\n\nAdd 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.\n\nReturns the point added to the grid.\n\nIf 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.\n\n```js\npds.addPoint([20, 30, 40]);\n```\n\n**pds.next()**\n\nTry to generate a new point in the grid following the distance constraint.\n\nReturns a coordinate array when a point is generated, null otherwise.\n\n```js\nvar point;\n\nwhile(point = pds.next()) {\n    console.log(point); // [x, y, z]\n}\n```\n\n**pds.reset()**\n\nReinitialize the grid as well as the internal state.\n\nWhen 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.\n\n## Usages in the wild\n\n * Image-based point clouds by Dmitri Cherniak: [#1](https://twitter.com/dmitricherniak/status/1348039557523116037) / [#2](https://twitter.com/dmitricherniak/status/1348065708333273090)\n * Creative Experiments by Lionel Radisson: [#1](https://twitter.com/MAKIO135/status/1225665997341749248) / [#2](https://twitter.com/MAKIO135/status/1224948519871696901)\n * [\"Poisson disc squares\", by Matt DesLauriers](https://twitter.com/mattdesl/status/973197660617355269)\n * [Mapgen4, a procedural wilderness map generator by Amit Patel](https://github.com/redblobgames/mapgen4)\n * [stsmapgen, a Slay the Spire-inspired procedural map generator by torin](https://github.com/yurkth/stsmapgen)\n\n## Implementation notes\n\nInternally, 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.\n\nIn 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.\n\n```\nvar PoissonDiskSampling = require('poisson-disk-sampling/src/implementations/fixed-density');\n```\n\nor\n\n```\nvar PoissonDiskSampling = require('poisson-disk-sampling/src/implementations/variable-density');\n```\n\n## TypeScript definitions\n\nTypeScripts definitions (`.d.ts`) provided by [Aliyss](https://github.com/Aliyss) are available through DefinitelyTyped. They can be installed locally using the following commands:\n\n```\nnpm install --save-dev @types/poisson-disk-sampling\n```\n\nor\n\n```\nyarn add @types/poisson-disk-sampling --dev\n```\n\n## History\n\n### [2.3.1](https://github.com/kchapelier/poisson-disk-sampling/tree/2.3.1) (2022-06-05) :\n\n- Slightly better performances and point density when working with a large shape\n\n### [2.3.0](https://github.com/kchapelier/poisson-disk-sampling/tree/2.3.0) (2022-05-21) :\n\n- Fix addPoint() erroneously accepting points on the outer bounds of the shape\n- Update dev dependencies\n\n### [2.2.3](https://github.com/kchapelier/poisson-disk-sampling/tree/2.2.3) (2022-02-26) :\n\n- Fix outdated CDN builds, no actual changes to the code provided through npm\n\n### [2.2.2](https://github.com/kchapelier/poisson-disk-sampling/tree/2.2.2) (2020-05-25) :\n\n- Minor performance-related tweaks for 3D and higher dimensions\n- Fix an issue causing the points to be generated in the [0, size-1] range instead of the [0, size) range\n\n### [2.2.1](https://github.com/kchapelier/poisson-disk-sampling/tree/2.2.1) (2020-05-11) :\n\n- Minor performance-related tweaks\n- Update dev dependencies\n\n### [2.2.0](https://github.com/kchapelier/poisson-disk-sampling/tree/2.2.0) (2020-02-17) :\n\n- Do not ignore distanceFunction anymore if minDistance and maxDistance are equal\n- Make it possible to explicitly require a specific implementation\n\n### [2.1.0](https://github.com/kchapelier/poisson-disk-sampling/tree/2.1.0) (2020-02-10) :\n\n*Due to an [issue](https://status.npmjs.org/incidents/1dpd0zjyhj2v?u=3q2zbsynvt3t) on npmjs.com this version was not listed on the website even though it was available through the CLI.*\n\n- Implement getAllPointsWithDistance()\n- Add a test suite for the variable density implementation\n- Fix an issue where the actual minDistance could be larger than the one set by the user in the variable density implementation\n\n### [2.0.0](https://github.com/kchapelier/poisson-disk-sampling/tree/2.0.0) (2020-02-03) :\n\n- Support distance function / variable density\n- Change constructor signature, the rest of the public API is unchanged\n\n### [1.0.6](https://github.com/kchapelier/poisson-disk-sampling/tree/1.0.6) (2019-09-28) :\n\n- Update dev dependencies\n\n### 1.0.5 (2019-05-27) :\n\n- Fix package on npm (adding missing file)\n\n### 1.0.4 (2019-05-27) :\n\n- Replace ndarray with a leaner custom implementation to drastically reduce the size of the package (~50%)\n- Update dev dependencies\n\n### 1.0.3 (2019-01-12) :\n\n- Update dev dependencies\n- Change node versions tested with travis\n\n### 1.0.2 (2017-09-30) :\n\n- Minor performance tweaks\n- Reduce npm package size\n- Update `moore` dep\n- Add benchmark script\n\n### 1.0.1 (2017-01-06) :\n\n- Add some checks on the points added with addPoint()\n- Implements tests\n- Add travis support\n\n### 1.0.0 (2016-09-16) :\n\n- Implement `getAllPoints()` and `reset()`\n- Fix incorrect handling of `maxDistance` when it is not set\n- Fix incorrect behavior when `fill()` is called several times\n- Declare the public API stable\n- API documentation\n- Remove `mathp` dependency\n\n### 0.0.1 (2015-11-28) :\n\n- First release\n\n## How to contribute ?\n\nFor new features and other enhancements, please make sure to contact me beforehand, either on [Twitter](https://twitter.com/kchplr) or through an issue on Github.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkchapelier%2Fpoisson-disk-sampling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkchapelier%2Fpoisson-disk-sampling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkchapelier%2Fpoisson-disk-sampling/lists"}