# OpenSimplex Noise
[](https://github.com/lmas/opensimplex/actions)
[](https://pypi.org/project/opensimplex/)
[](https://pypistats.org/packages/opensimplex)
[OpenSimplex] is a noise generation function like [Perlin] or [Simplex] noise, but better.
OpenSimplex noise is an n-dimensional gradient noise function that was
developed in order to overcome the patent-related issues surrounding
Simplex noise, while continuing to also avoid the visually-significant
directional artifacts characteristic of Perlin noise.
- Kurt Spencer
This is merely a python port of Kurt Spencer's [original code] (released to the public domain)
and neatly wrapped up in a package.
[OpenSimplex]: https://en.wikipedia.org/wiki/OpenSimplex_noise
[Perlin]: https://en.wikipedia.org/wiki/Perlin_noise
[Simplex]: https://en.wikipedia.org/wiki/Simplex_noise
[original code]: https://gist.github.com/KdotJPG/b1270127455a94ac5d19
## Status
The `master` branch contains the latest code (possibly unstable),
with automatic tests running for **Python 3.8, 3.9, 3.10 on Linux, MacOS and Windows**.
**FreeBSD** is also supported, though it's only locally tested as Github Actions
don't offer FreeBSD support.
Please refer to the [version tags] for the latest stable version.
[version tags]: https://github.com/lmas/opensimplex/tags
Updates for **v0.4+**:
- Adds a hard dependency on 'Numpy', for array optimizations aimed at heavier workloads.
- Adds optional dependency on 'Numba', for further speed optimizations using caching
(currently untested due to issues with llvmlite).
- Adds typing support.
- General refactor and cleanup of the library, tests and docs.
- **Breaking changes: API functions uses new names.**
## Contributions
Bug reports, bug fixes and other issues with existing features of the library are welcomed and will be handled during
the maintainer's free time. New stand-alone examples are also accepted.
However, pull requests with new features for the core internals will not be accepted as it eats up too much weekend
time, which I would rather spend on library stability instead.
## Usage
**Installation**
pip install opensimplex
**Basic usage**
>>> import opensimplex
>>> opensimplex.seed(1234)
>>> n = opensimplex.noise2(x=10, y=10)
>>> print(n)
0.580279369186297
**Running tests and benchmarks**
Setup a development environment:
make dev
source devenv/bin/activate
make deps
And then run the tests:
make test
Or the benchmarks:
make benchmark
For more advanced examples, see the files in the [tests](./tests/) and [examples](./examples/) directories.
## API
**opensimplex.seed(seed)**
Seeds the underlying permutation array (which produces different outputs),
using a 64-bit integer number.
If no value is provided, a static default will be used instead.
seed(13)
**random_seed()**
Works just like seed(), except it uses the system time (in ns) as a seed value.
Not guaranteed to be random so use at your own risk.
random_seed()
**get_seed()**
Return the value used to seed the initial state.
:return: seed as integer
>>> get_seed()
3
**opensimplex.noise2(x, y)**
Generate 2D OpenSimplex noise from X,Y coordinates.
:param x: x coordinate as float
:param y: y coordinate as float
:return: generated 2D noise as float, between -1.0 and 1.0
>>> noise2(0.5, 0.5)
-0.43906247097569345
**opensimplex.noise2array(x, y)**
Generates 2D OpenSimplex noise using Numpy arrays for increased performance.
:param x: numpy array of x-coords
:param y: numpy array of y-coords
:return: 2D numpy array of shape (y.size, x.size) with the generated noise
for the supplied coordinates
>>> rng = numpy.random.default_rng(seed=0)
>>> ix, iy = rng.random(2), rng.random(2)
>>> noise2array(ix, iy)
array([[ 0.00449931, -0.01807883],
[-0.00203524, -0.02358477]])
**opensimplex.noise3(x, y, z)**
Generate 3D OpenSimplex noise from X,Y,Z coordinates.
:param x: x coordinate as float
:param y: y coordinate as float
:param z: z coordinate as float
:return: generated 3D noise as float, between -1.0 and 1.0
>>> noise3(0.5, 0.5, 0.5)
0.39504955501618155
**opensimplex.noise3array(x, y, z)**
Generates 3D OpenSimplex noise using Numpy arrays for increased performance.
:param x: numpy array of x-coords
:param y: numpy array of y-coords
:param z: numpy array of z-coords
:return: 3D numpy array of shape (z.size, y.size, x.size) with the generated
noise for the supplied coordinates
>>> rng = numpy.random.default_rng(seed=0)
>>> ix, iy, iz = rng.random(2), rng.random(2), rng.random(2)
>>> noise3array(ix, iy, iz)
array([[[0.54942818, 0.54382411],
[0.54285204, 0.53698967]],
[[0.48107672, 0.4881196 ],
[0.45971748, 0.46684901]]])
**opensimplex.noise4(x, y, z, w)**
Generate 4D OpenSimplex noise from X,Y,Z,W coordinates.
:param x: x coordinate as float
:param y: y coordinate as float
:param z: z coordinate as float
:param w: w coordinate as float
:return: generated 4D noise as float, between -1.0 and 1.0
>>> noise4(0.5, 0.5, 0.5, 0.5)
0.04520359600370195
**opensimplex.noise4array(x, y, z, w)**
Generates 4D OpenSimplex noise using Numpy arrays for increased performance.
:param x: numpy array of x-coords
:param y: numpy array of y-coords
:param z: numpy array of z-coords
:param w: numpy array of w-coords
:return: 4D numpy array of shape (w.size, z.size, y.size, x.size) with the
generated noise for the supplied coordinates
>>> rng = numpy.random.default_rng(seed=0)
>>> ix, iy, iz, iw = rng.random(2), rng.random(2), rng.random(2), rng.random(2)
>>> noise4array(ix, iy, iz, iw)
array([[[[0.30334626, 0.29860705],
[0.28271858, 0.27805178]],
[[0.26601215, 0.25305428],
[0.23387872, 0.22151356]]],
[[[0.3392759 , 0.33585534],
[0.3343468 , 0.33118285]],
[[0.36930335, 0.36046537],
[0.36360679, 0.35500328]]]])
## FAQ
- What does the distribution of the noise values look like?
- Is this relevantly different enough to avoid any real trouble with the
original patent?
> If you read the [patent
> claims](http://www.google.com/patents/US6867776):
>
> Claim #1 talks about the hardware-implementation-optimized
> gradient generator. Most software implementations of Simplex Noise
> don't use this anyway, and OpenSimplex Noise certainly doesn't.
>
> Claim #2(&3&4) talk about using (x',y',z')=(x+s,y+s,z+s) where
> s=(x+y+z)/3 to transform the input (render space) coordinate onto
> a simplical grid, with the intention to make all of the
> "scissor-simplices" approximately regular. OpenSimplex Noise (in
> 3D) uses s=-(x+y+z)/6 to transform the input point to a point on
> the Simplectic honeycomb lattice so that the simplices bounding
> the (hyper)cubes at (0,0,..,0) and (1,1,...,1) work out to be
> regular. It then mathematically works out that s=(x+y+z)/3 is
> needed for the inverse transform, but that's performing a
> different (and opposite) function.
>
> Claim #5(&6) are specific to the scissor-simplex lattice. Simplex
> Noise divides the (squashed) n-dimensional (hyper)cube into n!
> simplices based on ordered edge traversals, whereas OpenSimplex
> Noise divides the (stretched) n-dimensional (hyper)cube into n
> polytopes (simplices, rectified simplices, birectified simplices,
> etc.) based on the separation (hyper)planes at integer values of
> (x'+y'+z'+...).
>
> Another interesting point is that, if you read all of the claims,
> none of them appear to apply to the 2D analogue of Simplex noise
> so long as it uses a gradient generator separate from the one
> described in claim #1. The skew function in Claim #2 only
> applies to 3D, and #5 explicitly refers to n>=3.
>
> And none of the patent claims speak about using surflets /
> "spherically symmetric kernels" to generate the "images with
> texture that do not have visible grid artifacts," which is
> probably the biggest similarity between the two algorithms.
>
> - **Kurt**, on [Reddit].
[Reddit]: https://www.reddit.com/r/proceduralgeneration/comments/2gu3e7/like_perlins_simplex_noise_but_dont_like_the/ckmqz2y
## Credits
- Kurt Spencer - Original work
- Owen Raccuglia - Test cases, [Go Module]
- /u/redblobgames - Fixed conversion for Java's long type, see [Reddit]
And all the other Github [Contributors] and [Bug Hunters]. Thanks!
[Go Module]: https://github.com/ojrac/opensimplex-go
[Reddit]: https://old.reddit.com/r/proceduralgeneration/comments/327zkm/repeated_patterns_in_opensimplex_python_port/cq8tth7/
[Contributors]: https://github.com/lmas/opensimplex/graphs/contributors
[Bug Hunters]: https://github.com/lmas/opensimplex/issues?q=is%3Aclosed
## License
While the original work was released to the public domain by Kurt, this package is using the MIT license.
Please see the file LICENSE for details.
## Example Output
More example code and trinkets can be found in the [examples] directory.
[examples]: https://github.com/lmas/opensimplex/tree/master/examples
Example images visualising 2D, 3D and 4D noise on a 2D plane, using the default seed:
**2D noise**
**3D noise**
**4D noise**
Raw data
{
"_id": null,
"home_page": "https://github.com/lmas/opensimplex",
"name": "opensimplex",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "opensimplex simplex noise 2D 3D 4D",
"author": "Alex",
"author_email": "opensimplex@larus.se",
"download_url": "https://files.pythonhosted.org/packages/15/34/6d317790b710cac4e3565b9d2f2ffacd01a126a4ec728a1b935c80742e75/opensimplex-0.4.5.tar.gz",
"platform": null,
"description": "\n# OpenSimplex Noise\n\n[](https://github.com/lmas/opensimplex/actions)\n[](https://pypi.org/project/opensimplex/)\n[](https://pypistats.org/packages/opensimplex)\n\n[OpenSimplex] is a noise generation function like [Perlin] or [Simplex] noise, but better.\n\n OpenSimplex noise is an n-dimensional gradient noise function that was\n developed in order to overcome the patent-related issues surrounding\n Simplex noise, while continuing to also avoid the visually-significant\n directional artifacts characteristic of Perlin noise.\n - Kurt Spencer\n\nThis is merely a python port of Kurt Spencer's [original code] (released to the public domain)\nand neatly wrapped up in a package.\n\n[OpenSimplex]: https://en.wikipedia.org/wiki/OpenSimplex_noise\n[Perlin]: https://en.wikipedia.org/wiki/Perlin_noise\n[Simplex]: https://en.wikipedia.org/wiki/Simplex_noise\n[original code]: https://gist.github.com/KdotJPG/b1270127455a94ac5d19\n\n## Status\n\nThe `master` branch contains the latest code (possibly unstable),\nwith automatic tests running for **Python 3.8, 3.9, 3.10 on Linux, MacOS and Windows**.\n**FreeBSD** is also supported, though it's only locally tested as Github Actions\ndon't offer FreeBSD support.\n\nPlease refer to the [version tags] for the latest stable version.\n\n[version tags]: https://github.com/lmas/opensimplex/tags\n\n\nUpdates for **v0.4+**:\n\n- Adds a hard dependency on 'Numpy', for array optimizations aimed at heavier workloads.\n- Adds optional dependency on 'Numba', for further speed optimizations using caching\n (currently untested due to issues with llvmlite).\n- Adds typing support.\n- General refactor and cleanup of the library, tests and docs.\n- **Breaking changes: API functions uses new names.**\n\n## Contributions\n\nBug reports, bug fixes and other issues with existing features of the library are welcomed and will be handled during\nthe maintainer's free time. New stand-alone examples are also accepted.\n\nHowever, pull requests with new features for the core internals will not be accepted as it eats up too much weekend\ntime, which I would rather spend on library stability instead.\n\n## Usage\n\n**Installation**\n\n pip install opensimplex\n\n**Basic usage**\n\n >>> import opensimplex\n >>> opensimplex.seed(1234)\n >>> n = opensimplex.noise2(x=10, y=10)\n >>> print(n)\n 0.580279369186297\n\n**Running tests and benchmarks**\n\nSetup a development environment:\n\n make dev\n source devenv/bin/activate\n make deps\n\nAnd then run the tests:\n\n make test\n\nOr the benchmarks:\n\n make benchmark\n\nFor more advanced examples, see the files in the [tests](./tests/) and [examples](./examples/) directories.\n\n## API\n\n**opensimplex.seed(seed)**\n\n Seeds the underlying permutation array (which produces different outputs),\n using a 64-bit integer number.\n If no value is provided, a static default will be used instead.\n\n seed(13)\n\n**random_seed()**\n\n Works just like seed(), except it uses the system time (in ns) as a seed value.\n Not guaranteed to be random so use at your own risk.\n\n random_seed()\n\n**get_seed()**\n\n Return the value used to seed the initial state.\n :return: seed as integer\n\n >>> get_seed()\n 3\n\n**opensimplex.noise2(x, y)**\n\n Generate 2D OpenSimplex noise from X,Y coordinates.\n :param x: x coordinate as float\n :param y: y coordinate as float\n :return: generated 2D noise as float, between -1.0 and 1.0\n\n >>> noise2(0.5, 0.5)\n -0.43906247097569345\n\n**opensimplex.noise2array(x, y)**\n\n Generates 2D OpenSimplex noise using Numpy arrays for increased performance.\n :param x: numpy array of x-coords\n :param y: numpy array of y-coords\n :return: 2D numpy array of shape (y.size, x.size) with the generated noise\n for the supplied coordinates\n\n >>> rng = numpy.random.default_rng(seed=0)\n >>> ix, iy = rng.random(2), rng.random(2)\n >>> noise2array(ix, iy)\n array([[ 0.00449931, -0.01807883],\n [-0.00203524, -0.02358477]])\n\n**opensimplex.noise3(x, y, z)**\n\n Generate 3D OpenSimplex noise from X,Y,Z coordinates.\n :param x: x coordinate as float\n :param y: y coordinate as float\n :param z: z coordinate as float\n :return: generated 3D noise as float, between -1.0 and 1.0\n\n >>> noise3(0.5, 0.5, 0.5)\n 0.39504955501618155\n\n**opensimplex.noise3array(x, y, z)**\n\n Generates 3D OpenSimplex noise using Numpy arrays for increased performance.\n :param x: numpy array of x-coords\n :param y: numpy array of y-coords\n :param z: numpy array of z-coords\n :return: 3D numpy array of shape (z.size, y.size, x.size) with the generated\n noise for the supplied coordinates\n\n >>> rng = numpy.random.default_rng(seed=0)\n >>> ix, iy, iz = rng.random(2), rng.random(2), rng.random(2)\n >>> noise3array(ix, iy, iz)\n array([[[0.54942818, 0.54382411],\n [0.54285204, 0.53698967]],\n [[0.48107672, 0.4881196 ],\n [0.45971748, 0.46684901]]])\n\n**opensimplex.noise4(x, y, z, w)**\n\n Generate 4D OpenSimplex noise from X,Y,Z,W coordinates.\n :param x: x coordinate as float\n :param y: y coordinate as float\n :param z: z coordinate as float\n :param w: w coordinate as float\n :return: generated 4D noise as float, between -1.0 and 1.0\n\n >>> noise4(0.5, 0.5, 0.5, 0.5)\n 0.04520359600370195\n\n**opensimplex.noise4array(x, y, z, w)**\n\n Generates 4D OpenSimplex noise using Numpy arrays for increased performance.\n :param x: numpy array of x-coords\n :param y: numpy array of y-coords\n :param z: numpy array of z-coords\n :param w: numpy array of w-coords\n :return: 4D numpy array of shape (w.size, z.size, y.size, x.size) with the\n generated noise for the supplied coordinates\n\n >>> rng = numpy.random.default_rng(seed=0)\n >>> ix, iy, iz, iw = rng.random(2), rng.random(2), rng.random(2), rng.random(2)\n >>> noise4array(ix, iy, iz, iw)\n array([[[[0.30334626, 0.29860705],\n [0.28271858, 0.27805178]],\n [[0.26601215, 0.25305428],\n [0.23387872, 0.22151356]]],\n [[[0.3392759 , 0.33585534],\n [0.3343468 , 0.33118285]],\n [[0.36930335, 0.36046537],\n [0.36360679, 0.35500328]]]])\n\n## FAQ\n\n- What does the distribution of the noise values look like?\n\n\n\n- Is this relevantly different enough to avoid any real trouble with the\noriginal patent?\n\n > If you read the [patent\n > claims](http://www.google.com/patents/US6867776):\n >\n > Claim #1 talks about the hardware-implementation-optimized\n > gradient generator. Most software implementations of Simplex Noise\n > don't use this anyway, and OpenSimplex Noise certainly doesn't.\n >\n > Claim #2(&3&4) talk about using (x',y',z')=(x+s,y+s,z+s) where\n > s=(x+y+z)/3 to transform the input (render space) coordinate onto\n > a simplical grid, with the intention to make all of the\n > \"scissor-simplices\" approximately regular. OpenSimplex Noise (in\n > 3D) uses s=-(x+y+z)/6 to transform the input point to a point on\n > the Simplectic honeycomb lattice so that the simplices bounding\n > the (hyper)cubes at (0,0,..,0) and (1,1,...,1) work out to be\n > regular. It then mathematically works out that s=(x+y+z)/3 is\n > needed for the inverse transform, but that's performing a\n > different (and opposite) function.\n >\n > Claim #5(&6) are specific to the scissor-simplex lattice. Simplex\n > Noise divides the (squashed) n-dimensional (hyper)cube into n!\n > simplices based on ordered edge traversals, whereas OpenSimplex\n > Noise divides the (stretched) n-dimensional (hyper)cube into n\n > polytopes (simplices, rectified simplices, birectified simplices,\n > etc.) based on the separation (hyper)planes at integer values of\n > (x'+y'+z'+...).\n >\n > Another interesting point is that, if you read all of the claims,\n > none of them appear to apply to the 2D analogue of Simplex noise\n > so long as it uses a gradient generator separate from the one\n > described in claim #1. The skew function in Claim #2 only\n > applies to 3D, and #5 explicitly refers to n>=3.\n >\n > And none of the patent claims speak about using surflets /\n > \"spherically symmetric kernels\" to generate the \"images with\n > texture that do not have visible grid artifacts,\" which is\n > probably the biggest similarity between the two algorithms.\n >\n > - **Kurt**, on [Reddit].\n\n[Reddit]: https://www.reddit.com/r/proceduralgeneration/comments/2gu3e7/like_perlins_simplex_noise_but_dont_like_the/ckmqz2y\n\n\n## Credits\n\n- Kurt Spencer - Original work\n- Owen Raccuglia - Test cases, [Go Module]\n- /u/redblobgames - Fixed conversion for Java's long type, see [Reddit]\n\nAnd all the other Github [Contributors] and [Bug Hunters]. Thanks!\n\n[Go Module]: https://github.com/ojrac/opensimplex-go\n[Reddit]: https://old.reddit.com/r/proceduralgeneration/comments/327zkm/repeated_patterns_in_opensimplex_python_port/cq8tth7/\n[Contributors]: https://github.com/lmas/opensimplex/graphs/contributors\n[Bug Hunters]: https://github.com/lmas/opensimplex/issues?q=is%3Aclosed\n\n## License\n\nWhile the original work was released to the public domain by Kurt, this package is using the MIT license.\n\nPlease see the file LICENSE for details.\n\n## Example Output\n\nMore example code and trinkets can be found in the [examples] directory.\n\n[examples]: https://github.com/lmas/opensimplex/tree/master/examples\n\nExample images visualising 2D, 3D and 4D noise on a 2D plane, using the default seed:\n\n**2D noise**\n\n\n\n**3D noise**\n\n\n\n**4D noise**\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "OpenSimplex is a noise generation function like Perlin or Simplex noise, but better.",
"version": "0.4.5",
"project_urls": {
"Download": "https://github.com/lmas/opensimplex/releases",
"Homepage": "https://github.com/lmas/opensimplex"
},
"split_keywords": [
"opensimplex",
"simplex",
"noise",
"2d",
"3d",
"4d"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6e72f5ce1974fdf035c37b0877d863c3f02d34b78851a411cfc0504a8e21236",
"md5": "404ec73f2ae985e61091ec513d5b6a81",
"sha256": "5e34f2b6f7e2d3e798d7f060b45cb1f92c02b68b6fc2626ac2a36bd53ec6c773"
},
"downloads": -1,
"filename": "opensimplex-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "404ec73f2ae985e61091ec513d5b6a81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 268019,
"upload_time": "2023-07-09T13:37:17",
"upload_time_iso_8601": "2023-07-09T13:37:17.559581Z",
"url": "https://files.pythonhosted.org/packages/a6/e7/2f5ce1974fdf035c37b0877d863c3f02d34b78851a411cfc0504a8e21236/opensimplex-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15346d317790b710cac4e3565b9d2f2ffacd01a126a4ec728a1b935c80742e75",
"md5": "4c3fb7a2a614eccbb3d3f5060bd5adab",
"sha256": "c390cf70dea97b32bd1a49ba6781e84f48dc93b1cc6c06f36d9d44c548299f90"
},
"downloads": -1,
"filename": "opensimplex-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "4c3fb7a2a614eccbb3d3f5060bd5adab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 271542,
"upload_time": "2023-07-09T13:37:19",
"upload_time_iso_8601": "2023-07-09T13:37:19.876667Z",
"url": "https://files.pythonhosted.org/packages/15/34/6d317790b710cac4e3565b9d2f2ffacd01a126a4ec728a1b935c80742e75/opensimplex-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-09 13:37:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lmas",
"github_project": "opensimplex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "wheel",
"specs": [
[
"==",
"0.38.1"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"65.5.1"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"4.0.1"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"6.4.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.1.2"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.8.0"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"22.6.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.23.0"
]
]
}
],
"lcname": "opensimplex"
}
JSON
