Noise Map Generators tcod.noise#

Noise map generators are provided by this module.

The Noise.sample_mgrid and Noise.sample_ogrid methods perform much better than multiple calls to Noise.get_point.

Example:

>>> import numpy as np
>>> import tcod
>>> noise = tcod.noise.Noise(
...     dimensions=2,
...     algorithm=tcod.noise.Algorithm.SIMPLEX,
...     seed=42,
... )
>>> samples = noise[tcod.noise.grid(shape=(5, 4), scale=0.25, origin=(0, 0))]
>>> samples  # Samples are a grid of floats between -1.0 and 1.0
array([[ 0.        , -0.55046356, -0.76072866, -0.7088647 , -0.68165785],
       [-0.27523372, -0.7205134 , -0.74057037, -0.43919194, -0.29195625],
       [-0.40398532, -0.57662135, -0.33160293,  0.12860827,  0.2864191 ],
       [-0.50773406, -0.2643614 ,  0.24446318,  0.6390255 ,  0.5922846 ]],
      dtype=float32)
>>> (samples + 1.0) * 0.5  # You can normalize samples to 0.0 - 1.0
array([[0.5       , 0.22476822, 0.11963567, 0.14556766, 0.15917107],
       [0.36238313, 0.1397433 , 0.12971482, 0.28040403, 0.35402188],
       [0.29800734, 0.21168932, 0.33419853, 0.5643041 , 0.6432096 ],
       [0.24613297, 0.3678193 , 0.6222316 , 0.8195127 , 0.79614234]],
      dtype=float32)
>>> ((samples + 1.0) * (256 / 2)).astype(np.uint8)  # Or as 8-bit unsigned bytes.
array([[128,  57,  30,  37,  40],
       [ 92,  35,  33,  71,  90],
       [ 76,  54,  85, 144, 164],
       [ 63,  94, 159, 209, 203]], dtype=uint8)
class tcod.noise.Algorithm(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Libtcod noise algorithms.

New in version 12.2.

PERLIN = 1#

Perlin noise.

SIMPLEX = 2#

Simplex noise.

WAVELET = 4#

Wavelet noise.

class tcod.noise.Implementation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Noise implementations.

New in version 12.2.

SIMPLE = 0#

Generate plain noise.

FBM = 1#

Fractional Brownian motion.

https://en.wikipedia.org/wiki/Fractional_Brownian_motion

TURBULENCE = 2#

Turbulence noise implementation.

class tcod.noise.Noise(dimensions: int, algorithm: int = Algorithm.SIMPLEX, implementation: int = Implementation.SIMPLE, hurst: float = 0.5, lacunarity: float = 2.0, octaves: float = 4, seed: int | Random | None = None)[source]#

A configurable noise sampler.

The hurst exponent describes the raggedness of the resultant noise, with a higher value leading to a smoother noise. Not used with tcod.noise.SIMPLE.

lacunarity is a multiplier that determines how fast the noise frequency increases for each successive octave. Not used with tcod.noise.SIMPLE.

Parameters:
  • dimensions – Must be from 1 to 4.

  • algorithm – Defaults to tcod.noise.Algorithm.SIMPLEX

  • implementation – Defaults to tcod.noise.Implementation.SIMPLE

  • hurst – The hurst exponent. Should be in the 0.0-1.0 range.

  • lacunarity – The noise lacunarity.

  • octaves – The level of detail on fBm and turbulence implementations.

  • seed – A Random instance, or None.

noise_c#

A cffi pointer to a TCOD_noise_t object.

Type:

CData

get_point(x: float = 0, y: float = 0, z: float = 0, w: float = 0) float[source]#

Return the noise value at the (x, y, z, w) point.

Parameters:
  • x – The position on the 1st axis.

  • y – The position on the 2nd axis.

  • z – The position on the 3rd axis.

  • w – The position on the 4th axis.

__getitem__(indexes: Any) NDArray[np.float32][source]#

Sample a noise map through NumPy indexing.

This follows NumPy’s advanced indexing rules, but allows for floating point values.

New in version 11.16.

sample_mgrid(mgrid: ArrayLike) NDArray[np.float32][source]#

Sample a mesh-grid array and return the result.

The sample_ogrid method performs better as there is a lot of overhead when working with large mesh-grids.

Parameters:

mgrid – A mesh-grid array of points to sample. A contiguous array of type numpy.float32 is preferred.

Returns:

An array of sampled points.

This array has the shape: mgrid.shape[:-1]. The dtype is numpy.float32.

sample_ogrid(ogrid: Sequence[ArrayLike]) NDArray[np.float32][source]#

Sample an open mesh-grid array and return the result.

Parameters:

ogrid – An open mesh-grid.

Returns:

An array of sampled points.

The shape is based on the lengths of the open mesh-grid arrays. The dtype is numpy.float32.

tcod.noise.grid(shape: tuple[int, ...], scale: tuple[float, ...] | float, origin: tuple[int, ...] | None = None, indexing: Literal['ij', 'xy'] = 'xy') tuple[NDArray[Any], ...][source]#

Generate a mesh-grid of sample points to use with noise sampling.

Parameters:
  • shape – The shape of the grid. This can be any number of dimensions, but Noise classes only support up to 4.

  • scale – The step size between samples. This can be a single float, or it can be a tuple of floats with one float for each axis in shape. A lower scale gives smoother transitions between noise values.

  • origin – The position of the first sample. If None then the origin will be zero on each axis. origin is not scaled by the scale parameter.

  • indexing – Passed to numpy.meshgrid.

Returns:

A sparse mesh-grid to be passed into a Noise instance.

Example:

>>> noise = tcod.noise.Noise(dimensions=2, seed=42)

# Common case for ij-indexed arrays.
>>> noise[tcod.noise.grid(shape=(3, 5), scale=0.25, indexing="ij")]
array([[ 0.        , -0.27523372, -0.40398532, -0.50773406, -0.64945626],
       [-0.55046356, -0.7205134 , -0.57662135, -0.2643614 , -0.12529983],
       [-0.76072866, -0.74057037, -0.33160293,  0.24446318,  0.5346834 ]],
      dtype=float32)

# Transpose an xy-indexed array to get a standard order="F" result.
>>> noise[tcod.noise.grid(shape=(4, 5), scale=(0.5, 0.25), origin=(1.0, 1.0))].T
array([[ 0.52655405,  0.25038874, -0.03488023, -0.18455243, -0.16333057],
       [-0.5037453 , -0.75348294, -0.73630923, -0.35063767,  0.18149695],
       [-0.81221616, -0.6379566 , -0.12449139,  0.4495706 ,  0.7547447 ],
       [-0.7057655 , -0.5817767 , -0.22774395,  0.02399864, -0.07006818]],
      dtype=float32)

New in version 12.2.