Refactor noise module. Add enums for noise types.

Refactor noise related tests.

Author: HexDecimal

CHANGELOG.rst

@@ -8,6 +8,12 @@ v2.0.0
 
 Unreleased
 ------------------
+Added
+ - Added `tcod.noise.Algorithm` and `tcod.noise.Implementation` enums.
+
+Deprecated
+ - The non-enum noise implementation names have been deprecated.
+
 Fixed
  - Indexing Noise classes now works with the FBM implementation.
 

docs/tcod/noise.rst

@@ -3,3 +3,4 @@ tcod.noise - Noise Map Generators
 
 .. automodule:: tcod.noise
     :members:
+    :member-order: bysource

tcod/noise.py

@@ -10,8 +10,8 @@
 
     noise = tcod.noise.Noise(
         dimensions=2,
-        algorithm=tcod.NOISE_SIMPLEX,
-        implementation=tcod.noise.TURBULENCE,
+        algorithm=tcod.noise.Algorithm.SIMPLEX,
+        implementation=tcod.noise.Implementation.TURBULENCE,
         hurst=0.5,
         lacunarity=2.0,
         octaves=4,
@@ -31,7 +31,9 @@
     samples = noise.sample_ogrid(ogrid)
     print(samples)
 """
-from typing import Any, Optional
+import enum
+import warnings
+from typing import Any, Optional, Sequence, Union
 
 import numpy as np
 
@@ -40,10 +42,63 @@
 from tcod._internal import deprecate
 from tcod.loader import ffi, lib
 
-"""Noise implementation constants"""
-SIMPLE = 0
-FBM = 1
-TURBULENCE = 2
+try:
+    from numpy.typing import ArrayLike
+except ImportError:  # Python < 3.7, Numpy < 1.20
+    from typing import Any as ArrayLike
+
+
+class Algorithm(enum.IntEnum):
+    """Libtcod noise algorithms.
+
+    .. versionadded:: 12.2
+    """
+
+    PERLIN = 1
+    """Perlin noise."""
+
+    SIMPLEX = 2
+    """Simplex noise."""
+
+    WAVELET = 4
+    """Wavelet noise."""
+
+    def __repr__(self) -> str:
+        return f"tcod.noise.Algorithm.{self.name}"
+
+
+class Implementation(enum.IntEnum):
+    """Noise implementations.
+
+    .. versionadded:: 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."""
+
+    def __repr__(self) -> str:
+        return f"tcod.noise.Implementation.{self.name}"
+
+
+def __getattr__(name: str) -> Implementation:
+    if hasattr(Implementation, name):
+        warnings.warn(
+            f"'tcod.noise.{name}' is deprecated,"
+            f" use 'tcod.noise.Implementation.{name}' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return Implementation[name]
+    raise AttributeError(f"module {__name__} has no attribute {name}")
 
 
 class Noise(object):
@@ -59,8 +114,9 @@ class Noise(object):
 
     Args:
         dimensions (int): Must be from 1 to 4.
-        algorithm (int): Defaults to NOISE_SIMPLEX
-        implementation (int): Defaults to tcod.noise.SIMPLE
+        algorithm (int): Defaults to :any:`tcod.noise.Algorithm.SIMPLEX`
+        implementation (int):
+            Defaults to :any:`tcod.noise.Implementation.SIMPLE`
         hurst (float): The hurst exponent.  Should be in the 0.0-1.0 range.
         lacunarity (float): The noise lacunarity.
         octaves (float): The level of detail on fBm and turbulence
@@ -74,21 +130,21 @@ class Noise(object):
     def __init__(
         self,
         dimensions: int,
-        algorithm: int = 2,
-        implementation: int = SIMPLE,
+        algorithm: int = Algorithm.SIMPLEX,
+        implementation: int = Implementation.SIMPLE,
         hurst: float = 0.5,
         lacunarity: float = 2.0,
         octaves: float = 4,
-        seed: Optional[tcod.random.Random] = None,
+        seed: Optional[Union[int, tcod.random.Random]] = None,
     ):
         if not 0 < dimensions <= 4:
             raise ValueError(
                 "dimensions must be in range 0 < n <= 4, got %r"
                 % (dimensions,)
             )
-        self._random = seed
-        _random_c = seed.random_c if seed else ffi.NULL
-        self._algorithm = algorithm
+        self._seed = seed
+        self._random = self.__rng_from_seed(seed)
+        _random_c = self._random.random_c
         self.noise_c = ffi.gc(
             ffi.cast(
                 "struct TCOD_Noise*",
@@ -99,8 +155,35 @@ def __init__(
         self._tdl_noise_c = ffi.new(
             "TDLNoise*", (self.noise_c, dimensions, 0, octaves)
         )
+        self.algorithm = algorithm
         self.implementation = implementation  # sanity check
 
+    @staticmethod
+    def __rng_from_seed(
+        seed: Union[None, int, tcod.random.Random]
+    ) -> tcod.random.Random:
+        if seed is None or isinstance(seed, int):
+            return tcod.random.Random(
+                seed=seed, algorithm=tcod.random.MERSENNE_TWISTER
+            )
+        return seed
+
+    def __repr__(self) -> str:
+        parameters = [
+            f"dimensions={self.dimensions}",
+            f"algorithm={self.algorithm!r}",
+            f"implementation={Implementation(self.implementation)!r}",
+        ]
+        if self.hurst != 0.5:
+            parameters.append(f"hurst={self.hurst}")
+        if self.lacunarity != 2:
+            parameters.append(f"lacunarity={self.lacunarity}")
+        if self.octaves != 4:
+            parameters.append(f"octaves={self.octaves}")
+        if self._seed is not None:
+            parameters.append(f"seed={self._seed}")
+        return f"tcod.noise.Noise({', '.join(parameters)})"
+
     @property
     def dimensions(self) -> int:
         return int(self._tdl_noise_c.dimensions)
@@ -112,15 +195,16 @@ def dimentions(self) -> int:
 
     @property
     def algorithm(self) -> int:
-        return int(self.noise_c.noise_type)
+        noise_type = self.noise_c.noise_type
+        return Algorithm(noise_type) if noise_type else Algorithm.SIMPLEX
 
     @algorithm.setter
     def algorithm(self, value: int) -> None:
         lib.TCOD_noise_set_type(self.noise_c, value)
 
     @property
     def implementation(self) -> int:
-        return int(self._tdl_noise_c.implementation)
+        return Implementation(self._tdl_noise_c.implementation)
 
     @implementation.setter
     def implementation(self, value: int) -> None:
@@ -181,15 +265,15 @@ def __getitem__(self, indexes: Any) -> np.ndarray:
             c_input[i] = ffi.from_buffer("float*", indexes[i])
 
         out = np.empty(indexes[0].shape, dtype=np.float32)
-        if self.implementation == SIMPLE:
+        if self.implementation == Implementation.SIMPLE:
             lib.TCOD_noise_get_vectorized(
                 self.noise_c,
                 self.algorithm,
                 out.size,
                 *c_input,
                 ffi.from_buffer("float*", out),
             )
-        elif self.implementation == FBM:
+        elif self.implementation == Implementation.FBM:
             lib.TCOD_noise_get_fbm_vectorized(
                 self.noise_c,
                 self.algorithm,
@@ -198,7 +282,7 @@ def __getitem__(self, indexes: Any) -> np.ndarray:
                 *c_input,
                 ffi.from_buffer("float*", out),
             )
-        elif self.implementation == TURBULENCE:
+        elif self.implementation == Implementation.TURBULENCE:
             lib.TCOD_noise_get_turbulence_vectorized(
                 self.noise_c,
                 self.algorithm,
@@ -212,7 +296,7 @@ def __getitem__(self, indexes: Any) -> np.ndarray:
 
         return out
 
-    def sample_mgrid(self, mgrid: np.ndarray) -> np.ndarray:
+    def sample_mgrid(self, mgrid: ArrayLike) -> np.ndarray:
         """Sample a mesh-grid array and return the result.
 
         The :any:`sample_ogrid` method performs better as there is a lot of
@@ -248,7 +332,7 @@ def sample_mgrid(self, mgrid: np.ndarray) -> np.ndarray:
         )
         return out
 
-    def sample_ogrid(self, ogrid: np.ndarray) -> np.ndarray:
+    def sample_ogrid(self, ogrid: Sequence[ArrayLike]) -> np.ndarray:
         """Sample an open mesh-grid array and return the result.
 
         Args

tests/test_noise.py

@@ -1 +1,102 @@
-#!/usr/bin/env python
+import copy
+import pickle
+
+import numpy as np
+import pytest
+
+import tcod
+
+
+@pytest.mark.parametrize("implementation", tcod.noise.Implementation)
+@pytest.mark.parametrize("algorithm", tcod.noise.Algorithm)
+@pytest.mark.parametrize("hurst", [0.5, 0.75])
+@pytest.mark.parametrize("lacunarity", [2, 3])
+@pytest.mark.parametrize("octaves", [4, 6])
+def test_noise_class(
+    implementation: tcod.noise.Implementation,
+    algorithm: tcod.noise.Algorithm,
+    hurst: float,
+    lacunarity: float,
+    octaves: float,
+) -> None:
+    noise = tcod.noise.Noise(
+        2,
+        algorithm=algorithm,
+        implementation=implementation,
+        hurst=hurst,
+        lacunarity=lacunarity,
+        octaves=octaves,
+    )
+    # cover attributes
+    assert noise.dimensions == 2
+    noise.algorithm = noise.algorithm
+    noise.implementation = noise.implementation
+    noise.octaves = noise.octaves
+    assert noise.hurst
+    assert noise.lacunarity
+
+    assert noise.get_point(0, 0) == noise[0, 0]
+    assert noise[0] == noise[0, 0]
+    noise.sample_mgrid(np.mgrid[:2, :3])
+    noise.sample_ogrid(np.ogrid[:2, :3])
+
+    np.testing.assert_equal(
+        noise.sample_mgrid(np.mgrid[:2, :3]),
+        noise.sample_ogrid(np.ogrid[:2, :3]),
+    )
+    np.testing.assert_equal(
+        noise.sample_mgrid(np.mgrid[:2, :3]), noise[tuple(np.mgrid[:2, :3])]
+    )
+    repr(noise)
+
+
+def test_noise_samples() -> None:
+    noise = tcod.noise.Noise(
+        2, tcod.noise.Algorithm.SIMPLEX, tcod.noise.Implementation.SIMPLE
+    )
+    np.testing.assert_equal(
+        noise.sample_mgrid(np.mgrid[:32, :24]),
+        noise.sample_ogrid(np.ogrid[:32, :24]),
+    )
+
+
+def test_noise_errors() -> None:
+    with pytest.raises(ValueError):
+        tcod.noise.Noise(0)
+    with pytest.raises(ValueError):
+        tcod.noise.Noise(1, implementation=-1)
+    noise = tcod.noise.Noise(2)
+    with pytest.raises(ValueError):
+        noise.sample_mgrid(np.mgrid[:2, :2, :2])
+    with pytest.raises(ValueError):
+        noise.sample_ogrid(np.ogrid[:2, :2, :2])
+    with pytest.raises(IndexError):
+        noise[0, 0, 0, 0, 0]
+    with pytest.raises(TypeError):
+        noise[object]
+
+
+@pytest.mark.parametrize("implementation", tcod.noise.Implementation)
+def test_noise_pickle(implementation: tcod.noise.Implementation) -> None:
+    rand = tcod.random.Random(tcod.random.MERSENNE_TWISTER, 42)
+    noise = tcod.noise.Noise(2, implementation, seed=rand)
+    noise2 = copy.copy(noise)
+    np.testing.assert_equal(
+        noise.sample_ogrid(np.ogrid[:3, :1]),
+        noise2.sample_ogrid(np.ogrid[:3, :1]),
+    )
+
+
+def test_noise_copy() -> None:
+    rand = tcod.random.Random(tcod.random.MERSENNE_TWISTER, 42)
+    noise = tcod.noise.Noise(2, seed=rand)
+    noise2 = pickle.loads(pickle.dumps(noise))
+    np.testing.assert_equal(
+        noise.sample_ogrid(np.ogrid[:3, :1]),
+        noise2.sample_ogrid(np.ogrid[:3, :1]),
+    )
+
+    noise3 = tcod.noise.Noise(2, seed=None)
+    assert repr(noise3) == repr(pickle.loads(pickle.dumps(noise3)))
+    noise4 = tcod.noise.Noise(2, seed=42)
+    assert repr(noise4) == repr(pickle.loads(pickle.dumps(noise4)))