nPerlinNoise

indexed on PyPI - nPerlinNoise

repo on GitHub - nPerlinNoise

docs on ReadTheDocs -

A robust open source implementation of Perlin Noise Algorithm for N-Dimensions in Python.

• 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:

---

Dependencies

• Python>=3.10.0

for production dependencies see Requirements
for development dependencies see Dev-Requirements

Installation

$ pip install nPerlinNoise

for detailed instruction on installation see INSTALLATION.

Usage

Setup

>>> import nPerlinNoise as nPN
>>> noise = nPN.Noise(seed=69420)

Basic usage

Get noise values at given n-dimensional coordinates by calling noise(...),
coordinates can be single value, or an iterable

• single value

  noise(..., l, m, n, ...)
  where l, m, n, ..., are single values

  >>> 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], ....)
  where ...., are iterable of homogeneous-dimensions and lx, mx, nx, ..., are single values the output will be of same shape of input homogeneous-dimensions

  >>> 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 same values with trailing dimensions having zero as coordinate

• n-dimensionality

  noise(..., l, m, n) = noise(..., l, m, n, 0) = noise(..., l, m, n, 0, 0) = noise(..., l, m, n, 0, 0, ...)

  >>> 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 coords
use noise(..., gridMode=True) gridMode is key-word only argument, default=False
the output will be of shape equal to the length(s) of coords in that order

• gridMode

  >>> 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

API

• docs pending

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 see Tests

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

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

Maintainer:

Amith M