Getting started

Learn how to use nPerlinNoise

• A powerful and fast API for n-dimensional noise.
• Easy hyper-parameters selection of octaves, lacunarity and persistence as well as complex and customizable hyper-parameters for n-dimension frequency, waveLength, warp(interpolation) and range.
• Includes various helpful tools for noise generation and for procedural generation tasks such as customizable Gradient, Color Gradients, Warp classes.
• Implements custom PRNG generator for n-dimension and can be easily tuned.

Details

• Technology stack:
  • Status: v0.1.4-alpha focusing on all issues Getting Involved, follows PEP440
  • All Packages: Releases
  • CHANGELOG

Tested on Python 3.10, Windows 10

• Future work:
  • Optimization for octave noise
  • Writing unit tests
  • Writing API docs
  • Writing pending docs
  • Writing ReadTheDocs
  • Blogging
  • Finishing left in-code docs
  • Dimensional octaves

Screenshots

Link to Gallery

Quick Start

If you're eager to get started with nPerlinNoise, follow these simple steps to set up and start using the library:

Dependencies

• Python>=3.10.0

For production dependencies

• numexpr>=2.8.3
• numpy>=1.23.3

For development dependencies

• matplotlib>=3.6.1
• plotly>=5.10.0
• PyQt5>=5.15.7
• PyQt5-stubs>=5.15.6.0
• build>=0.8.0
• twine>=4.0.1

Installation

Begin by installing nPerlinNoise using pip. Open your terminal or command prompt and run the following command:

pip install nPerlinNoise

For detailed instructions on installation, see Installation.

Setup

Import nPerlinNoise: In your Python script or interactive session, import nPerlinNoise as follows:

import nPerlinNoise as nPN

Create a Noise Instance: Next, create a Noise instance, specifying any desired parameters. For example:

noise = nPN.Noise(seed=69420)

Basic Usage

You're now ready to generate Perlin noise! You can use the noise instance to obtain noise values at specific n-dimensional coordinates. Here are some basic usage examples:

• Single Value

  • noise(..., l, m, n, ...)

    >>> noise(73)
    array(0.5207113, dtype=float32)
    >>> noise(73, 11, 7)
    array(0.5700986, dtype=float32)
    >>> noise(0, 73, 7, 11, 0, 3)
    array(0.5222712, dtype=float32)
    

• Iterable

  • noise(...., [l1, l2, ..., lx], [m1, m2, ..., mx], [n1, n2, ..., nx], ....)

    >>> noise([73, 49])
    array([0.52071124, 0.6402224 ], dtype=float32)
    >>> noise([73, 49], [2, 2])
    array([0.4563121 , 0.63378346], dtype=float32)
    >>> noise([[73], [49], [0]],
    ...       [[2 ], [2 ], [2]],
    ...       [[0 ], [1 ], [2]])
    array([[0.4563121 ],
           [0.6571784 ],
           [0.16369209]], dtype=float32)
    >>> noise([[1, 2], [2, 3]],
    ...       [[1, 1], [1, 1]],
    ...       [[2, 2], [2, 2]])
    array([[0.08666219, 0.09778494],
           [0.09778494, 0.14886124]], dtype=float32)
    

  noise(..., l, m, n, ...) has the same values with trailing dimensions having zero as coordinates.

• n-Dimensionality

  noise(..., l, m, n) is equivalent to noise(..., l, m, n, 0) and so on.

  >>> noise(73)
  array(0.5207113, dtype=float32)
  >>> noise(73, 0)
  array(0.5207113, dtype=float32)
  >>> noise(73, 0, 0)
  array(0.5207113, dtype=float32)
  >>> noise(73, 0, 0, 0, 0)
  array(0.5207113, dtype=float32)
  

Grid mode allows for computing noise for every combination of coordinates. Use noise(..., gridMode=True); gridMode is a keyword-only argument, default is False. The output will be of the same shape as the length(s) of coordinates in that order.

• Grid Mode

  >>> noise([73, 49], [2, 2], [0, 1], gridMode=True)
  array([[[0.4563121 , 0.63378346],
          [0.4563121 , 0.63378346]],
  
         [[0.44594935, 0.6571784 ],
          [0.44594935, 0.6571784 ]]], dtype=float32)
  >>> noise([1, 20, 32, 64], [1, 1, 2], 0, [1, 2], gridMode=True)
  array([[[[0.06459193, 0.5110498 , 0.669962  , 0.47636804],
           [0.06459193, 0.5110498 , 0.669962  , 0.47636804],
           [0.09864856, 0.5013973 , 0.62935597, 0.47954425]]],
  
         [[[0.07678645, 0.50853723, 0.6778991 , 0.4679888 ],
           [0.07678645, 0.50853723, 0.6778991 , 0.4679888 ],
           [0.14069612, 0.47582665, 0.6663638 , 0.48764956]]]],
        dtype=float32)
  

For detailed usage, see Example.

How to Test the Software

• To test Logical consistency, run testLogic
• To test Profile Benchmarking, run testProfile
• To test Visuals, run testVisuals
• To test Colors, run testCol

To see all tests, refer to Tests directory.

Known Issues

• No Known Bugs
• NPerlin.findBounds is bottleneck
• noise(a, b, c, d, e, f, ...) is slow for single value coordinates

Getting Help

• Check main.py for detailed usage
• Check docs for all documentations
• Check Usage Section
• Check Setup for all tests

If you have questions, concerns, bug reports, etc., please file an issue in this repository's Issue Tracker or open a discussion in this repository's Discussion section.

Getting involved

• Looking for Contributors for feature additions
• Looking for Contributors for optimization #11
• Looking for Contributors for unit testing #12
• Looking for Contributors for ReadTheDocs #13
• Looking for Contributors for WebApp #14
• Looking for Contributors for API docs #15
• Fork the repository and issue a PR to contribute

General instructions on how to contribute CONTRIBUTING and CODE OF CONDUCT

Open source licensing info

1. Terms
2. LICENSE
3. CFPB Source Code Policy

Credits and references

1. Inspired from The Coding Train -> perlin noise
2. hash function by xxhash inspired the rand3 algo and ultimately helped for O(1) time complexity n-dimensional random generator NPrng
3. StackOverflow for helping on various occasions throughout the development
4. vnoise and opensimplex for ideas for README.md
5. docs derivative from open-source-project-template
6. packaging help from realpython

Project Badges