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

Note: if the package is not being imported, try import NPerlinNoise as nPN refer #24

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

Contributors:

Shravan Revanna