.. 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
OpenSimplex Loops
=================
Extension to the `OpenSimplex Python library by lmas <https://github.com/lmas/opensimplex>`_.
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.
- Github: https://github.com/Dennis-van-Gils/opensimplex-loops
- PyPI: https://pypi.org/project/opensimplex-loops
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.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": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"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/22/2a/6733177189c97a2dc88d5c2237abbfb45deea289e587085ff958fc4f4e31/opensimplex-loops-1.0.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/opensimplex-loops\n :target: https://pypi.org/project/opensimplex-loops\n.. image:: https://img.shields.io/pypi/pyversions/opensimplex-loops\n :target: https://pypi.org/project/opensimplex-loops\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n.. image:: https://img.shields.io/badge/License-MIT-purple.svg\n :target: https://github.com/Dennis-van-Gils/opensimplex-loops/blob/master/LICENSE.txt\n\nOpenSimplex Loops\n=================\n\nExtension to the `OpenSimplex Python library by lmas <https://github.com/lmas/opensimplex>`_.\nThis library provides higher-level functions that can generate seamlessly-looping\nanimated images and closed curves, and seamlessy-tileable images. It relies on 4D\nOpenSimplex noise.\n\n- Github: https://github.com/Dennis-van-Gils/opensimplex-loops\n- PyPI: https://pypi.org/project/opensimplex-loops\n\nInspiration taken from\n`Coding Challenge #137: 4D OpenSimplex Noise Loop <https://youtu.be/3_0Ax95jIrk>`_\nby `The Coding Train <https://www.youtube.com/c/TheCodingTrain>`_.\n\n\nDemos\n=====\n\n``looping_animated_2D_image()``\n-------------------------------\n\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_2D_image.gif\n :alt: looping_animated_2D_image\n\n Seamlessly-looping animated 2D images.\n\n Code: `<demos/demo_looping_animated_2D_image.py>`_\n\n``looping_animated_closed_1D_curve()``\n--------------------------------------\n\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_circle.gif\n :alt: looping_animated_circle\n\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_looping_animated_closed_1D_curve.gif\n :alt: looping_animated_closed_1D_curve\n\n Seamlessly-looping animated 1D curves, each curve in turn also closing up\n seamlessly back-to-front.\n\n Code: `<demos/demo_looping_animated_circle.py>`_\n\n Code: `<demos/demo_looping_animated_closed_1D_curve.py>`_\n\n``tileable_2D_image()``\n-----------------------\n\n .. image:: https://raw.githubusercontent.com/Dennis-van-Gils/opensimplex-loops/master/images/demo_tileable_2D_image.png\n :alt: tileable_2D_image\n\n Seamlessly-tileable 2D image.\n\n Code: `<demos/demo_tileable_2D_image.py>`_\n\n\nInstallation\n============\n\n::\n\n pip install opensimplex-loops\n\nThis will install the following dependencies:\n\n- ``opensimplex``\n- ``numpy``\n- ``numba``\n- ``numba-progress``\n\nNotes:\n\n- The `OpenSimplex` library by lmas does not enforce the use of the\n `numba <https://numba.pydata.org/>`_ package, but is left optional instead.\n Here, I have set it as a requirement due to the heavy computation required\n by these highler-level functions. I have them optimized for `numba` which\n enables multi-core parallel processing within Python, resulting in major\n speed improvements compared to as running without. I have gotten computational\n speedups by a factor of ~200.\n\n- Note that the very first call of each of these OpenSimplex functions will take\n a longer time than later calls. This is because `numba` needs to compile this\n Python code to bytecode specific to your platform, once.\n\n- The ``numba-progress`` package is actually optional. When present, a progress\n bar will be shown during the noise generation.\n\n\nAPI\n===\n\n``looping_animated_2D_image(...)``\n----------------------------------\n\n Generates a stack of seamlessly-looping animated 2D raster images drawn\n from 4D OpenSimplex noise.\n\n The first two OpenSimplex dimensions are used to describe a plane that gets\n projected onto a 2D raster image. The last two dimensions are used to\n describe a circle in time.\n\n Args:\n N_frames (`int`, default = 200)\n Number of time frames\n\n N_pixels_x (`int`, default = 1000)\n Number of pixels on the x-axis\n\n N_pixels_y (`int` | `None`, default = `None`)\n Number of pixels on the y-axis. When set to None `N_pixels_y` will\n be set equal to `N_pixels_x`.\n\n t_step (`float`, default = 0.1)\n Time step\n\n x_step (`float`, default = 0.01)\n Spatial step in the x-direction\n\n y_step (`float` | `None`, default = `None`)\n Spatial step in the y-direction. When set to None `y_step` will be\n set equal to `x_step`.\n\n dtype (`type`, default = `numpy.double`)\n Return type of the noise array elements. To reduce the memory\n footprint one can change from the default `numpy.double` to e.g.\n `numpy.float32`.\n\n seed (`int`, default = 3)\n Seed value for the OpenSimplex noise\n\n verbose (`bool`, default = `True`)\n Print 'Generating noise...' to the terminal? If the `numba_progress`\n package is present a progress bar will also be shown.\n\n Returns:\n The 2D image stack as 3D array [time, y-pixel, x-pixel] containing the\n OpenSimplex noise values as floating points. The output is garantueed to\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\n and are probably quite smaller than [-1, 1].\n\n``looping_animated_closed_1D_curve(...)``\n-----------------------------------------\n\n Generates a stack of seamlessly-looping animated 1D curves, each curve in\n turn also closing up seamlessly back-to-front, drawn from 4D OpenSimplex\n noise.\n\n The first two OpenSimplex dimensions are used to describe a circle that gets\n projected onto a 1D curve. The last two dimensions are used to describe a\n circle in time.\n\n Args:\n N_frames (`int`, default = 200)\n Number of time frames\n\n N_pixels_x (`int`, default = 1000)\n Number of pixels of the curve\n\n t_step (`float`, default = 0.1)\n Time step\n\n x_step (`float`, default = 0.01)\n Spatial step in the x-direction\n\n dtype (`type`, default = `numpy.double`)\n Return type of the noise array elements. To reduce the memory\n footprint one can change from the default `numpy.double` to e.g.\n `numpy.float32`.\n\n seed (`int`, default = 3)\n Seed value for the OpenSimplex noise\n\n verbose (`bool`, default = `True`)\n Print 'Generating noise...' to the terminal? If the `numba_progress`\n package is present a progress bar will also be shown.\n\n Returns:\n The 1D curve stack as 2D array [time, x-pixel] containing the\n OpenSimplex noise values as floating points. The output is garantueed to\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\n and are probably quite smaller than [-1, 1].\n\n``tileable_2D_image(...)``\n--------------------------\n\n Generates a seamlessly-tileable 2D raster image drawn from 4D OpenSimplex\n noise.\n\n The first two OpenSimplex dimensions are used to describe a circle that gets\n projected onto the x-axis of the 2D raster image. The last two dimensions\n are used to describe another circle that gets projected onto the y-axis of\n the 2D raster image.\n\n Args:\n N_pixels_x (`int`, default = 1000)\n Number of pixels on the x-axis\n\n N_pixels_y (`int` | `None`, default = `None`)\n Number of pixels on the y-axis. When set to None `N_pixels_y` will\n be set equal to `N_pixels_x`.\n\n x_step (`float`, default = 0.01)\n Spatial step in the x-direction\n\n y_step (`float` | `None`, default = `None`)\n Spatial step in the y-direction. When set to None `y_step` will be\n set equal to `x_step`.\n\n dtype (`type`, default = `numpy.double`)\n Return type of the noise array elements. To reduce the memory\n footprint one can change from the default `numpy.double` to e.g.\n `numpy.float32`.\n\n seed (`int`, default = 3)\n Seed value for the OpenSimplex noise\n\n verbose (`bool`, default = `True`)\n Print 'Generating noise...' to the terminal? If the `numba_progress`\n package is present a progress bar will also be shown.\n\n Returns:\n The 2D image as 2D array [y-pixel, x-pixel] containing the\n OpenSimplex noise values as floating points. The output is garantueed to\n be in the range [-1, 1], but the exact extrema cannot be known a-priori\n and are probably quite smaller than [-1, 1].\n\nChangelog\n=========\n\n1.0.0 (2023-08-27)\n------------------\n* Stable release\n* Added looping animated circle demo\n\n0.1.3 (2023-01-27)\n------------------\n* Fixed wrong docstr description on the return value of `tileable_2D_image()`\n* Generalized the internal functions\n\n0.1.2 (2023-01-26)\n------------------\n* Using raw.githubusercontent.com for the images in README to show up in PyPi\n\n0.1.0 (2023-01-26)\n------------------\n* First release on PyPI\n\n\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.0",
"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": "5f7a99f770bfd9837a01f2d7db67b6feefee8534ed6d7c917f3234026e2300b0",
"md5": "8fd98f94efbcac77c7444c415d00ac95",
"sha256": "5dacb401f799f98542d0f8908023c602a39b85dc2db3953341e392936a95361d"
},
"downloads": -1,
"filename": "opensimplex_loops-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fd98f94efbcac77c7444c415d00ac95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7947,
"upload_time": "2023-08-27T12:00:28",
"upload_time_iso_8601": "2023-08-27T12:00:28.954846Z",
"url": "https://files.pythonhosted.org/packages/5f/7a/99f770bfd9837a01f2d7db67b6feefee8534ed6d7c917f3234026e2300b0/opensimplex_loops-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "222a6733177189c97a2dc88d5c2237abbfb45deea289e587085ff958fc4f4e31",
"md5": "07df778604e9ac7a8051f9bc5fb80250",
"sha256": "c78cced4d5809de3c593d07dfdf4e57612fd6527cf3e255ef771582c25fd85fc"
},
"downloads": -1,
"filename": "opensimplex-loops-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "07df778604e9ac7a8051f9bc5fb80250",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3662982,
"upload_time": "2023-08-27T12:00:33",
"upload_time_iso_8601": "2023-08-27T12:00:33.155481Z",
"url": "https://files.pythonhosted.org/packages/22/2a/6733177189c97a2dc88d5c2237abbfb45deea289e587085ff958fc4f4e31/opensimplex-loops-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-27 12:00:33",
"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
