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, offset=(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)[source]¶

Libtcod noise algorithms.

Added in version 12.2.

PERLIN = 1¶: Perlin noise.

SIMPLEX = 2¶: Simplex noise.

WAVELET = 4¶: Wavelet noise.

__repr__() → str[source]¶: Return the string representation for this algorithm.

class tcod.noise.Implementation(value)[source]¶

Noise implementations.

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

__repr__() → str[source]¶: Return the string representation for this implementation.

class tcod.noise.Noise(dimensions: int, algorithm: int = tcod.noise.Algorithm.SIMPLEX, implementation: int = tcod.noise.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

__repr__() → str[source]¶: Return the string representation of this noise instance.

property dimensions: int¶: Number of dimensions supported by this noise generator.

property algorithm: int¶: Current selected algorithm. Can be changed.

property implementation: int¶: Current selected implementation. Can be changed.

property hurst: float¶: Noise hurst exponent. Can be changed.

property lacunarity: float¶: Noise lacunarity. Can be changed.

property octaves: float¶: Level of detail on fBm and turbulence implementations. Can be changed.

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.

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

__getstate__() → dict[str, Any][source]¶: Support picking this instance.

__setstate__(state: dict[str, Any]) → None[source]¶: Unpickle this instance.

tcod.noise.grid(shape: tuple[int, ...], scale: tuple[float, ...] | float, origin: tuple[float, ...] | None = None, indexing: Literal['ij', 'xy'] = 'xy', *, offset: tuple[float, ...] | None = None) → tuple[NDArray[np.number], ...][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.
offset –
The offset into the shape to generate. Similar to origin but is scaled by the scale parameter. Can be multiples of shape to index noise samples by chunk.

Added in version 19.2.

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)

# Can sample noise by chunk using the offset keyword
>>> noise[tcod.noise.grid(shape=(3, 5), scale=0.25, indexing="ij", offset=(0, 0))]
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)
>>> noise[tcod.noise.grid(shape=(3, 5), scale=0.25, indexing="ij", offset=(3, 0))]
array([[-0.7088647 , -0.43919194,  0.12860827,  0.6390255 ,  0.80402255],
       [-0.68165785, -0.29195625,  0.2864191 ,  0.5922846 ,  0.52655405],
       [-0.7841389 , -0.46131462,  0.0159424 ,  0.17141782, -0.04198273]],
      dtype=float32)
>>> noise[tcod.noise.grid(shape=(3, 5), scale=0.25, indexing="ij", offset=(6, 0))]
array([[-0.779634  , -0.60696834, -0.27446985, -0.23233278, -0.5037453 ],
       [-0.5474089 , -0.54476213, -0.42235228, -0.49519652, -0.7101793 ],
       [-0.28291094, -0.4326369 , -0.5227732 , -0.69655263, -0.81221616]],
      dtype=float32)

Added in version 12.2.

Noise Map Generators tcod.noise¶

Noise Map Generators `tcod.noise`¶