.. image:: https://img.shields.io/pypi/v/opensimplex-loops
:target: https://pypi.org/project/opensimplex-loops
.. image:: https://img.shields.io/pypi/pyversions/opensimplex-loops
:target: https://pypi.org/project/opensimplex-loops
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/License-MIT-purple.svg
:target: https://github.com/Dennis-van-Gils/opensimplex-loops/blob/master/LICENSE.txt
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.13304280.svg
:target: https://doi.org/10.5281/zenodo.13304280
OpenSimplex Loops
=================
This library provides higher-level functions that can generate seamlessly-looping
animated images and closed curves, and seamlessy-tileable images. It relies on 4D
OpenSimplex noise, which is a type of
`gradient noise <https://en.wikipedia.org/wiki/Gradient_noise>`_ that features
spatial coherence.
- Github: https://github.com/Dennis-van-Gils/opensimplex-loops
- PyPI: https://pypi.org/project/opensimplex-loops
This library is an extension to the
`OpenSimplex Python library by lmas <https://github.com/lmas/opensimplex>`_.
Inspiration taken from
`Coding Challenge #137: 4D OpenSimplex Noise Loop <https://youtu.be/3_0Ax95jIrk>`_
by `The Coding Train <https://www.youtube.com/c/TheCodingTrain>`_.
Demos
=====
``looping_animated_2D_image()``
-------------------------------
.. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_2D_image.gif
:alt: looping_animated_2D_image
Seamlessly-looping animated 2D images.
Code: `<demos/demo_looping_animated_2D_image.py>`_
``looping_animated_closed_1D_curve()``
--------------------------------------
.. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_circle.gif
:alt: looping_animated_circle
.. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_closed_1D_curve.gif
:alt: looping_animated_closed_1D_curve
Seamlessly-looping animated 1D curves, each curve in turn also closing up
seamlessly back-to-front.
Code: `<demos/demo_looping_animated_circle.py>`_
Code: `<demos/demo_looping_animated_closed_1D_curve.py>`_
``tileable_2D_image()``
-----------------------
.. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_tileable_2D_image.png
:alt: tileable_2D_image
Seamlessly-tileable 2D image.
Code: `<demos/demo_tileable_2D_image.py>`_
Installation
============
::
pip install opensimplex-loops
This will install the following dependencies:
- ``opensimplex``
- ``numpy``
- ``numba``
- ``numba-progress``
Notes:
- The `OpenSimplex` library by lmas does not enforce the use of the
`numba <https://numba.pydata.org/>`_ package, but is left optional instead.
Here, I have set it as a requirement due to the heavy computation required
by these highler-level functions. I have them optimized for `numba` which
enables multi-core parallel processing within Python, resulting in major
speed improvements compared to as running without. I have gotten computational
speedups by a factor of ~200.
- Note that the very first call of each of these OpenSimplex functions will take
a longer time than later calls. This is because `numba` needs to compile this
Python code to bytecode specific to your platform, once.
- The ``numba-progress`` package is actually optional. When present, a progress
bar will be shown during the noise generation.
API
===
``looping_animated_2D_image(...)``
----------------------------------
Generates a stack of seamlessly-looping animated 2D raster images drawn
from 4D OpenSimplex noise.
The first two OpenSimplex dimensions are used to describe a plane that gets
projected onto a 2D raster image. The last two dimensions are used to
describe a circle in time.
Args:
N_frames (`int`, default = 200)
Number of time frames
N_pixels_x (`int`, default = 1000)
Number of pixels on the x-axis
N_pixels_y (`int` | `None`, default = `None`)
Number of pixels on the y-axis. When set to None `N_pixels_y` will
be set equal to `N_pixels_x`.
t_step (`float`, default = 0.1)
Time step
x_step (`float`, default = 0.01)
Spatial step in the x-direction
y_step (`float` | `None`, default = `None`)
Spatial step in the y-direction. When set to None `y_step` will be
set equal to `x_step`.
dtype (`type`, default = `numpy.double`)
Return type of the noise array elements. To reduce the memory
footprint one can change from the default `numpy.double` to e.g.
`numpy.float32`.
seed (`int`, default = 3)
Seed value for the OpenSimplex noise
verbose (`bool`, default = `True`)
Print 'Generating noise...' to the terminal? If the `numba_progress`
package is present a progress bar will also be shown.
Returns:
The 2D image stack as 3D array [time, y-pixel, x-pixel] containing the
OpenSimplex noise values as floating points. The output is garantueed to
be in the range [-1, 1], but the exact extrema cannot be known a-priori
and are probably quite smaller than [-1, 1].
``looping_animated_closed_1D_curve(...)``
-----------------------------------------
Generates a stack of seamlessly-looping animated 1D curves, each curve in
turn also closing up seamlessly back-to-front, drawn from 4D OpenSimplex
noise.
The first two OpenSimplex dimensions are used to describe a circle that gets
projected onto a 1D curve. The last two dimensions are used to describe a
circle in time.
Args:
N_frames (`int`, default = 200)
Number of time frames
N_pixels_x (`int`, default = 1000)
Number of pixels of the curve
t_step (`float`, default = 0.1)
Time step
x_step (`float`, default = 0.01)
Spatial step in the x-direction
dtype (`type`, default = `numpy.double`)
Return type of the noise array elements. To reduce the memory
footprint one can change from the default `numpy.double` to e.g.
`numpy.float32`.
seed (`int`, default = 3)
Seed value for the OpenSimplex noise
verbose (`bool`, default = `True`)
Print 'Generating noise...' to the terminal? If the `numba_progress`
package is present a progress bar will also be shown.
Returns:
The 1D curve stack as 2D array [time, x-pixel] containing the
OpenSimplex noise values as floating points. The output is garantueed to
be in the range [-1, 1], but the exact extrema cannot be known a-priori
and are probably quite smaller than [-1, 1].
``tileable_2D_image(...)``
--------------------------
Generates a seamlessly-tileable 2D raster image drawn from 4D OpenSimplex
noise.
The first two OpenSimplex dimensions are used to describe a circle that gets
projected onto the x-axis of the 2D raster image. The last two dimensions
are used to describe another circle that gets projected onto the y-axis of
the 2D raster image.
Args:
N_pixels_x (`int`, default = 1000)
Number of pixels on the x-axis
N_pixels_y (`int` | `None`, default = `None`)
Number of pixels on the y-axis. When set to None `N_pixels_y` will
be set equal to `N_pixels_x`.
x_step (`float`, default = 0.01)
Spatial step in the x-direction
y_step (`float` | `None`, default = `None`)
Spatial step in the y-direction. When set to None `y_step` will be
set equal to `x_step`.
dtype (`type`, default = `numpy.double`)
Return type of the noise array elements. To reduce the memory
footprint one can change from the default `numpy.double` to e.g.
`numpy.float32`.
seed (`int`, default = 3)
Seed value for the OpenSimplex noise
verbose (`bool`, default = `True`)
Print 'Generating noise...' to the terminal? If the `numba_progress`
package is present a progress bar will also be shown.
Returns:
The 2D image as 2D array [y-pixel, x-pixel] containing the
OpenSimplex noise values as floating points. The output is garantueed to
be in the range [-1, 1], but the exact extrema cannot be known a-priori
and are probably quite smaller than [-1, 1].
Changelog
=========
1.0.1 (2024-08-12)
------------------
* Obtained a DOI from Zenodo
1.0.0 (2023-08-27)
------------------
* Stable release
* Added looping animated circle demo
0.1.3 (2023-01-27)
------------------
* Fixed wrong docstr description on the return value of `tileable_2D_image()`
* Generalized the internal functions
0.1.2 (2023-01-26)
------------------
* Using raw.githubusercontent.com for the images in README to show up in PyPi
0.1.0 (2023-01-26)
------------------
* First release on PyPI
Raw data
{
"_id": null,
"home_page": "https://github.com/Dennis-van-Gils/opensimplex-loops",
"name": "opensimplex-loops",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "opensimplex, noise, 4D, polar, loop, looping, seamless, tileable, textures, images, curves",
"author": "Dennis van Gils",
"author_email": "vangils.dennis@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d0/d2/1a31e2cccfbe6c57ae70e8aa30b8c6a4fb6c69adc02a59e707960d1c1662/opensimplex_loops-1.0.1.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/opensimplex-loops\r\n :target: https://pypi.org/project/opensimplex-loops\r\n.. image:: https://img.shields.io/pypi/pyversions/opensimplex-loops\r\n :target: https://pypi.org/project/opensimplex-loops\r\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\r\n :target: https://github.com/psf/black\r\n.. image:: https://img.shields.io/badge/License-MIT-purple.svg\r\n :target: https://github.com/Dennis-van-Gils/opensimplex-loops/blob/master/LICENSE.txt\r\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.13304280.svg\r\n :target: https://doi.org/10.5281/zenodo.13304280\r\n\r\nOpenSimplex Loops\r\n=================\r\n\r\nThis library provides higher-level functions that can generate seamlessly-looping\r\nanimated images and closed curves, and seamlessy-tileable images. It relies on 4D\r\nOpenSimplex noise, which is a type of\r\n`gradient noise <https://en.wikipedia.org/wiki/Gradient_noise>`_ that features\r\nspatial coherence.\r\n\r\n- Github: https://github.com/Dennis-van-Gils/opensimplex-loops\r\n- PyPI: https://pypi.org/project/opensimplex-loops\r\n\r\nThis library is an extension to the\r\n`OpenSimplex Python library by lmas <https://github.com/lmas/opensimplex>`_.\r\n\r\nInspiration taken from\r\n`Coding Challenge #137: 4D OpenSimplex Noise Loop <https://youtu.be/3_0Ax95jIrk>`_\r\nby `The Coding Train <https://www.youtube.com/c/TheCodingTrain>`_.\r\n\r\n\r\nDemos\r\n=====\r\n\r\n``looping_animated_2D_image()``\r\n-------------------------------\r\n\r\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_2D_image.gif\r\n :alt: looping_animated_2D_image\r\n\r\n Seamlessly-looping animated 2D images.\r\n\r\n Code: `<demos/demo_looping_animated_2D_image.py>`_\r\n\r\n``looping_animated_closed_1D_curve()``\r\n--------------------------------------\r\n\r\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_circle.gif\r\n :alt: looping_animated_circle\r\n\r\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_closed_1D_curve.gif\r\n :alt: looping_animated_closed_1D_curve\r\n\r\n Seamlessly-looping animated 1D curves, each curve in turn also closing up\r\n seamlessly back-to-front.\r\n\r\n Code: `<demos/demo_looping_animated_circle.py>`_\r\n\r\n Code: `<demos/demo_looping_animated_closed_1D_curve.py>`_\r\n\r\n``tileable_2D_image()``\r\n-----------------------\r\n\r\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_tileable_2D_image.png\r\n :alt: tileable_2D_image\r\n\r\n Seamlessly-tileable 2D image.\r\n\r\n Code: `<demos/demo_tileable_2D_image.py>`_\r\n\r\n\r\nInstallation\r\n============\r\n\r\n::\r\n\r\n pip install opensimplex-loops\r\n\r\nThis will install the following dependencies:\r\n\r\n- ``opensimplex``\r\n- ``numpy``\r\n- ``numba``\r\n- ``numba-progress``\r\n\r\nNotes:\r\n\r\n- The `OpenSimplex` library by lmas does not enforce the use of the\r\n `numba <https://numba.pydata.org/>`_ package, but is left optional instead.\r\n Here, I have set it as a requirement due to the heavy computation required\r\n by these highler-level functions. I have them optimized for `numba` which\r\n enables multi-core parallel processing within Python, resulting in major\r\n speed improvements compared to as running without. I have gotten computational\r\n speedups by a factor of ~200.\r\n\r\n- Note that the very first call of each of these OpenSimplex functions will take\r\n a longer time than later calls. This is because `numba` needs to compile this\r\n Python code to bytecode specific to your platform, once.\r\n\r\n- The ``numba-progress`` package is actually optional. When present, a progress\r\n bar will be shown during the noise generation.\r\n\r\n\r\nAPI\r\n===\r\n\r\n``looping_animated_2D_image(...)``\r\n----------------------------------\r\n\r\n Generates a stack of seamlessly-looping animated 2D raster images drawn\r\n from 4D OpenSimplex noise.\r\n\r\n The first two OpenSimplex dimensions are used to describe a plane that gets\r\n projected onto a 2D raster image. The last two dimensions are used to\r\n describe a circle in time.\r\n\r\n Args:\r\n N_frames (`int`, default = 200)\r\n Number of time frames\r\n\r\n N_pixels_x (`int`, default = 1000)\r\n Number of pixels on the x-axis\r\n\r\n N_pixels_y (`int` | `None`, default = `None`)\r\n Number of pixels on the y-axis. When set to None `N_pixels_y` will\r\n be set equal to `N_pixels_x`.\r\n\r\n t_step (`float`, default = 0.1)\r\n Time step\r\n\r\n x_step (`float`, default = 0.01)\r\n Spatial step in the x-direction\r\n\r\n y_step (`float` | `None`, default = `None`)\r\n Spatial step in the y-direction. When set to None `y_step` will be\r\n set equal to `x_step`.\r\n\r\n dtype (`type`, default = `numpy.double`)\r\n Return type of the noise array elements. To reduce the memory\r\n footprint one can change from the default `numpy.double` to e.g.\r\n `numpy.float32`.\r\n\r\n seed (`int`, default = 3)\r\n Seed value for the OpenSimplex noise\r\n\r\n verbose (`bool`, default = `True`)\r\n Print 'Generating noise...' to the terminal? If the `numba_progress`\r\n package is present a progress bar will also be shown.\r\n\r\n Returns:\r\n The 2D image stack as 3D array [time, y-pixel, x-pixel] containing the\r\n OpenSimplex noise values as floating points. The output is garantueed to\r\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\r\n and are probably quite smaller than [-1, 1].\r\n\r\n``looping_animated_closed_1D_curve(...)``\r\n-----------------------------------------\r\n\r\n Generates a stack of seamlessly-looping animated 1D curves, each curve in\r\n turn also closing up seamlessly back-to-front, drawn from 4D OpenSimplex\r\n noise.\r\n\r\n The first two OpenSimplex dimensions are used to describe a circle that gets\r\n projected onto a 1D curve. The last two dimensions are used to describe a\r\n circle in time.\r\n\r\n Args:\r\n N_frames (`int`, default = 200)\r\n Number of time frames\r\n\r\n N_pixels_x (`int`, default = 1000)\r\n Number of pixels of the curve\r\n\r\n t_step (`float`, default = 0.1)\r\n Time step\r\n\r\n x_step (`float`, default = 0.01)\r\n Spatial step in the x-direction\r\n\r\n dtype (`type`, default = `numpy.double`)\r\n Return type of the noise array elements. To reduce the memory\r\n footprint one can change from the default `numpy.double` to e.g.\r\n `numpy.float32`.\r\n\r\n seed (`int`, default = 3)\r\n Seed value for the OpenSimplex noise\r\n\r\n verbose (`bool`, default = `True`)\r\n Print 'Generating noise...' to the terminal? If the `numba_progress`\r\n package is present a progress bar will also be shown.\r\n\r\n Returns:\r\n The 1D curve stack as 2D array [time, x-pixel] containing the\r\n OpenSimplex noise values as floating points. The output is garantueed to\r\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\r\n and are probably quite smaller than [-1, 1].\r\n\r\n``tileable_2D_image(...)``\r\n--------------------------\r\n\r\n Generates a seamlessly-tileable 2D raster image drawn from 4D OpenSimplex\r\n noise.\r\n\r\n The first two OpenSimplex dimensions are used to describe a circle that gets\r\n projected onto the x-axis of the 2D raster image. The last two dimensions\r\n are used to describe another circle that gets projected onto the y-axis of\r\n the 2D raster image.\r\n\r\n Args:\r\n N_pixels_x (`int`, default = 1000)\r\n Number of pixels on the x-axis\r\n\r\n N_pixels_y (`int` | `None`, default = `None`)\r\n Number of pixels on the y-axis. When set to None `N_pixels_y` will\r\n be set equal to `N_pixels_x`.\r\n\r\n x_step (`float`, default = 0.01)\r\n Spatial step in the x-direction\r\n\r\n y_step (`float` | `None`, default = `None`)\r\n Spatial step in the y-direction. When set to None `y_step` will be\r\n set equal to `x_step`.\r\n\r\n dtype (`type`, default = `numpy.double`)\r\n Return type of the noise array elements. To reduce the memory\r\n footprint one can change from the default `numpy.double` to e.g.\r\n `numpy.float32`.\r\n\r\n seed (`int`, default = 3)\r\n Seed value for the OpenSimplex noise\r\n\r\n verbose (`bool`, default = `True`)\r\n Print 'Generating noise...' to the terminal? If the `numba_progress`\r\n package is present a progress bar will also be shown.\r\n\r\n Returns:\r\n The 2D image as 2D array [y-pixel, x-pixel] containing the\r\n OpenSimplex noise values as floating points. The output is garantueed to\r\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\r\n and are probably quite smaller than [-1, 1].\r\n\r\nChangelog\r\n=========\r\n\r\n1.0.1 (2024-08-12)\r\n------------------\r\n* Obtained a DOI from Zenodo\r\n\r\n1.0.0 (2023-08-27)\r\n------------------\r\n* Stable release\r\n* Added looping animated circle demo\r\n\r\n0.1.3 (2023-01-27)\r\n------------------\r\n* Fixed wrong docstr description on the return value of `tileable_2D_image()`\r\n* Generalized the internal functions\r\n\r\n0.1.2 (2023-01-26)\r\n------------------\r\n* Using raw.githubusercontent.com for the images in README to show up in PyPi\r\n\r\n0.1.0 (2023-01-26)\r\n------------------\r\n* First release on PyPI\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library to generate seamlessly-looping animated images and closed curves, and seamlessy-tileable images. Based on 4D OpenSimplex noise.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Dennis-van-Gils/opensimplex-loops",
"Issue Tracker": "https://github.com/Dennis-van-Gils/opensimplex-loops/issues"
},
"split_keywords": [
"opensimplex",
" noise",
" 4d",
" polar",
" loop",
" looping",
" seamless",
" tileable",
" textures",
" images",
" curves"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "104ee8981e0d8bf49ae1f06ba7b5d1611c7e58facb2143b2a658bdce0f9dde87",
"md5": "d5419bf060ca78df0e3df902c8eb2a05",
"sha256": "955e23ffde0933ff977b8f41219c97d6b0015dba390c4b970ecf9c011dc7925c"
},
"downloads": -1,
"filename": "opensimplex_loops-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5419bf060ca78df0e3df902c8eb2a05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8100,
"upload_time": "2024-08-12T13:35:21",
"upload_time_iso_8601": "2024-08-12T13:35:21.159953Z",
"url": "https://files.pythonhosted.org/packages/10/4e/e8981e0d8bf49ae1f06ba7b5d1611c7e58facb2143b2a658bdce0f9dde87/opensimplex_loops-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d0d21a31e2cccfbe6c57ae70e8aa30b8c6a4fb6c69adc02a59e707960d1c1662",
"md5": "bd73afe2dce998d6823a4ca4e4288f14",
"sha256": "70f49e79c2f1ac9451118f6145d01f340ea83137bfbec1ae29b800d036fc2801"
},
"downloads": -1,
"filename": "opensimplex_loops-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "bd73afe2dce998d6823a4ca4e4288f14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3663647,
"upload_time": "2024-08-12T13:35:23",
"upload_time_iso_8601": "2024-08-12T13:35:23.609871Z",
"url": "https://files.pythonhosted.org/packages/d0/d2/1a31e2cccfbe6c57ae70e8aa30b8c6a4fb6c69adc02a59e707960d1c1662/opensimplex_loops-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 13:35:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Dennis-van-Gils",
"github_project": "opensimplex-loops",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "opensimplex-loops"
}
JSON
