Skip to content

Commit f544ea1

Browse files
HexDecimalHexDecimal
committed
Update noise docs.
1 parent 3c9da82 commit f544ea1

File tree

1 file changed

+54
-61
lines changed

1 file changed

+54
-61
lines changed

‎tcod/noise.py‎

Lines changed: 54 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,24 @@
1212
... algorithm=tcod.noise.Algorithm.SIMPLEX,
1313
... seed=42,
1414
... )
15-
>>> samples = noise[tcod.noise.grid(shape=(5, 5), scale=0.25, origin=(0, 0))]
15+
>>> samples = noise[tcod.noise.grid(shape=(5, 4), scale=0.25, origin=(0, 0))]
1616
>>> samples # Samples are a grid of floats between -1.0 and 1.0
1717
array([[ 0. , -0.55046356, -0.76072866, -0.7088647 , -0.68165785],
1818
[-0.27523372, -0.7205134 , -0.74057037, -0.43919194, -0.29195625],
1919
[-0.40398532, -0.57662135, -0.33160293, 0.12860827, 0.2864191 ],
20-
[-0.50773406, -0.2643614 , 0.24446318, 0.6390255 , 0.5922846 ],
21-
[-0.64945626, -0.12529983, 0.5346834 , 0.80402255, 0.52655405]],
20+
[-0.50773406, -0.2643614 , 0.24446318, 0.6390255 , 0.5922846 ]],
2221
dtype=float32)
2322
>>> (samples + 1.0) * 0.5 # You can normalize samples to 0.0 - 1.0
2423
array([[0.5 , 0.22476822, 0.11963567, 0.14556766, 0.15917107],
2524
[0.36238313, 0.1397433 , 0.12971482, 0.28040403, 0.35402188],
2625
[0.29800734, 0.21168932, 0.33419853, 0.5643041 , 0.6432096 ],
27-
[0.24613297, 0.3678193 , 0.6222316 , 0.8195127 , 0.79614234],
28-
[0.17527187, 0.4373501 , 0.76734173, 0.9020113 , 0.76327705]],
26+
[0.24613297, 0.3678193 , 0.6222316 , 0.8195127 , 0.79614234]],
2927
dtype=float32)
3028
>>> ((samples + 1.0) * (256 / 2)).astype(np.uint8) # Or as 8-bit unsigned bytes.
3129
array([[128, 57, 30, 37, 40],
3230
[ 92, 35, 33, 71, 90],
3331
[ 76, 54, 85, 144, 164],
34-
[ 63, 94, 159, 209, 203],
35-
[ 44, 111, 196, 230, 195]], dtype=uint8)
32+
[ 63, 94, 159, 209, 203]], dtype=uint8)
3633
""" # noqa: E501
3734
from __future__ import annotations
3835

@@ -103,26 +100,23 @@ def __getattr__(name: str) -> Implementation:
103100

104101

105102
class Noise(object):
106-
"""
103+
"""A configurable noise sampler.
107104
108105
The ``hurst`` exponent describes the raggedness of the resultant noise,
109106
with a higher value leading to a smoother noise.
110107
Not used with tcod.noise.SIMPLE.
111108
112-
``lacunarity`` is a multiplier that determines how fast the noise
113-
frequency increases for each successive octave.
109+
``lacunarity`` is a multiplier that determines how fast the noise frequency increases for each successive octave.
114110
Not used with tcod.noise.SIMPLE.
115111
116112
Args:
117-
dimensions (int): Must be from 1 to 4.
118-
algorithm (int): Defaults to :any:`tcod.noise.Algorithm.SIMPLEX`
119-
implementation (int):
120-
Defaults to :any:`tcod.noise.Implementation.SIMPLE`
121-
hurst (float): The hurst exponent. Should be in the 0.0-1.0 range.
122-
lacunarity (float): The noise lacunarity.
123-
octaves (float): The level of detail on fBm and turbulence
124-
implementations.
125-
seed (Optional[Random]): A Random instance, or None.
113+
dimensions: Must be from 1 to 4.
114+
algorithm: Defaults to :any:`tcod.noise.Algorithm.SIMPLEX`
115+
implementation: Defaults to :any:`tcod.noise.Implementation.SIMPLE`
116+
hurst: The hurst exponent. Should be in the 0.0-1.0 range.
117+
lacunarity: The noise lacunarity.
118+
octaves: The level of detail on fBm and turbulence implementations.
119+
seed: A Random instance, or None.
126120
127121
Attributes:
128122
noise_c (CData): A cffi pointer to a TCOD_noise_t object.
@@ -224,18 +218,17 @@ def get_point(self, x: float = 0, y: float = 0, z: float = 0, w: float = 0) -> f
224218
"""Return the noise value at the (x, y, z, w) point.
225219
226220
Args:
227-
x (float): The position on the 1st axis.
228-
y (float): The position on the 2nd axis.
229-
z (float): The position on the 3rd axis.
230-
w (float): The position on the 4th axis.
221+
x: The position on the 1st axis.
222+
y: The position on the 2nd axis.
223+
z: The position on the 3rd axis.
224+
w: The position on the 4th axis.
231225
"""
232226
return float(lib.NoiseGetSample(self._tdl_noise_c, (x, y, z, w)))
233227

234228
def __getitem__(self, indexes: Any) -> NDArray[np.float32]:
235229
"""Sample a noise map through NumPy indexing.
236230
237-
This follows NumPy's advanced indexing rules, but allows for floating
238-
point values.
231+
This follows NumPy's advanced indexing rules, but allows for floating point values.
239232
240233
.. versionadded:: 11.16
241234
"""
@@ -292,14 +285,14 @@ def sample_mgrid(self, mgrid: ArrayLike) -> NDArray[np.float32]:
292285
overhead when working with large mesh-grids.
293286
294287
Args:
295-
mgrid (numpy.ndarray): A mesh-grid array of points to sample.
288+
mgrid: A mesh-grid array of points to sample.
296289
A contiguous array of type `numpy.float32` is preferred.
297290
298291
Returns:
299-
numpy.ndarray: An array of sampled points.
292+
An array of sampled points.
300293
301-
This array has the shape: ``mgrid.shape[:-1]``.
302-
The ``dtype`` is `numpy.float32`.
294+
This array has the shape: ``mgrid.shape[:-1]``.
295+
The ``dtype`` is `numpy.float32`.
303296
"""
304297
mgrid = np.ascontiguousarray(mgrid, np.float32)
305298
if mgrid.shape[0] != self.dimensions:
@@ -320,15 +313,14 @@ def sample_mgrid(self, mgrid: ArrayLike) -> NDArray[np.float32]:
320313
def sample_ogrid(self, ogrid: Sequence[ArrayLike]) -> NDArray[np.float32]:
321314
"""Sample an open mesh-grid array and return the result.
322315
323-
Args
324-
ogrid (Sequence[ArrayLike]): An open mesh-grid.
316+
Args:
317+
ogrid: An open mesh-grid.
325318
326319
Returns:
327-
numpy.ndarray: An array of sampled points.
320+
An array of sampled points.
328321
329-
The ``shape`` is based on the lengths of the open mesh-grid
330-
arrays.
331-
The ``dtype`` is `numpy.float32`.
322+
The ``shape`` is based on the lengths of the open mesh-grid arrays.
323+
The ``dtype`` is `numpy.float32`.
332324
"""
333325
if len(ogrid) != self.dimensions:
334326
raise ValueError("len(ogrid) must equal self.dimensions, " "%r != %r" % (len(ogrid), self.dimensions))
@@ -416,38 +408,39 @@ def grid(
416408
origin: Optional[Tuple[int, ...]] = None,
417409
indexing: Literal["ij", "xy"] = "xy",
418410
) -> Tuple[NDArray[Any], ...]:
419-
"""Helper function for generating a grid of noise samples.
420-
421-
`shape` is the shape of the returned mesh grid. This can be any number of
422-
dimensions, but :class:`Noise` classes only support up to 4.
423-
424-
`scale` is the step size of indexes away from `origin`.
425-
This can be a single float, or it can be a tuple of floats with one float
426-
for each axis in `shape`. A lower scale gives smoother transitions
427-
between noise values.
411+
"""Generate a mesh-grid of sample points to use with noise sampling.
428412
429-
`origin` is the first sample of the grid.
430-
If `None` then the `origin` will be zero on each axis.
431-
`origin` is not scaled by the `scale` parameter.
432-
433-
`indexing` is passed to :any:`numpy.meshgrid`.
413+
Args:
414+
shape: The shape of the grid.
415+
This can be any number of dimensions, but :class:`Noise` classes only support up to 4.
416+
scale: The step size between samples.
417+
This can be a single float, or it can be a tuple of floats with one float for each axis in `shape`.
418+
A lower scale gives smoother transitions between noise values.
419+
origin: The position of the first sample.
420+
If `None` then the `origin` will be zero on each axis.
421+
`origin` is not scaled by the `scale` parameter.
422+
indexing: Passed to :any:`numpy.meshgrid`.
423+
424+
Returns:
425+
A sparse mesh-grid to be passed into a :class:`Noise` instance.
434426
435427
Example::
436428
437429
>>> noise = tcod.noise.Noise(dimensions=2, seed=42)
438-
>>> noise[tcod.noise.grid(shape=(5, 5), scale=0.25)]
439-
array([[ 0. , -0.55046356, -0.76072866, -0.7088647 , -0.68165785],
440-
[-0.27523372, -0.7205134 , -0.74057037, -0.43919194, -0.29195625],
441-
[-0.40398532, -0.57662135, -0.33160293, 0.12860827, 0.2864191 ],
442-
[-0.50773406, -0.2643614 , 0.24446318, 0.6390255 , 0.5922846 ],
443-
[-0.64945626, -0.12529983, 0.5346834 , 0.80402255, 0.52655405]],
430+
431+
# Common case for ij-indexed arrays.
432+
>>> noise[tcod.noise.grid(shape=(3, 5), scale=0.25, indexing="ij")]
433+
array([[ 0. , -0.27523372, -0.40398532, -0.50773406, -0.64945626],
434+
[-0.55046356, -0.7205134 , -0.57662135, -0.2643614 , -0.12529983],
435+
[-0.76072866, -0.74057037, -0.33160293, 0.24446318, 0.5346834 ]],
444436
dtype=float32)
445-
>>> noise[tcod.noise.grid(shape=(5, 5), scale=(0.5, 0.25), origin=(1, 1))]
446-
array([[ 0.52655405, -0.5037453 , -0.81221616, -0.7057655 , 0.24630858],
447-
[ 0.25038874, -0.75348294, -0.6379566 , -0.5817767 , -0.02789652],
448-
[-0.03488023, -0.73630923, -0.12449139, -0.22774395, -0.22243626],
449-
[-0.18455243, -0.35063767, 0.4495706 , 0.02399864, -0.42226675],
450-
[-0.16333057, 0.18149695, 0.7547447 , -0.07006818, -0.6546707 ]],
437+
438+
# Transpose an xy-indexed array to get a standard order="F" result.
439+
>>> noise[tcod.noise.grid(shape=(4, 5), scale=(0.5, 0.25), origin=(1.0, 1.0))].T
440+
array([[ 0.52655405, 0.25038874, -0.03488023, -0.18455243, -0.16333057],
441+
[-0.5037453 , -0.75348294, -0.73630923, -0.35063767, 0.18149695],
442+
[-0.81221616, -0.6379566 , -0.12449139, 0.4495706 , 0.7547447 ],
443+
[-0.7057655 , -0.5817767 , -0.22774395, 0.02399864, -0.07006818]],
451444
dtype=float32)
452445
453446
.. versionadded:: 12.2

0 commit comments

Comments
 (0)