[Proc Gen] NoiseSource - Core class with point queries #207

New issue

Open

opened 2026-01-12 00:10:51 +00:00 by john · 0 comments

john commented

2026-01-12 00:10:51 +00:00

Owner

Parent Issue: #192

Overview

Implement NoiseSource as a configured noise generator function. Stateless and infinite - the same coordinates always produce the same value.

Specification

Constructor

NoiseSource(dimensions: int = 2,
            algorithm: str = "simplex",
            hurst: float = 0.5,
            lacunarity: float = 2.0,
            seed: int = None)

Parameter	Type	Description
`dimensions`	`int`	1-4. Number of input dimensions. Default: 2.
`algorithm`	`str`	`"simplex"`, `"perlin"`, or `"wavelet"`. Default: `"simplex"`.
`hurst`	`float`	Fractal Hurst exponent for fbm/turbulence. Default: 0.5.
`lacunarity`	`float`	Frequency multiplier between octaves. Default: 2.0.
`seed`	`int`	Random seed. None for random.

Properties

All properties are read-only.

Property	Type	Description
`dimensions`	`int`	Number of input dimensions.
`algorithm`	`str`	Noise algorithm name.
`hurst`	`float`	Hurst exponent.
`lacunarity`	`float`	Lacunarity value.
`seed`	`int`	Seed used (even if originally None).

Point Query Methods

def get(self, pos: tuple[float, ...]) -> float

Get flat noise value at coordinates. Tuple length must match dimensions. Returns -1.0 to 1.0.

def fbm(self, pos: tuple[float, ...], octaves: int = 4) -> float

Get fractal brownian motion value. Returns -1.0 to 1.0.

def turbulence(self, pos: tuple[float, ...], octaves: int = 4) -> float

Get turbulence (absolute fbm) value. Returns -1.0 to 1.0.

Example

noise = mcrfpy.NoiseSource(dimensions=2, algorithm="simplex", seed=42)

# Point queries
value = noise.get((10.5, 20.3))
fbm_value = noise.fbm((10.5, 20.3), octaves=6)
turb_value = noise.turbulence((10.5, 20.3), octaves=4)

# Same coordinates always give same result
assert noise.get((10.5, 20.3)) == value

Implementation Notes

Wrap TCODNoise internally
get maps to TCOD_noise_get
fbm maps to TCOD_noise_get_fbm
turbulence maps to TCOD_noise_get_turbulence
If seed is None, generate random seed and store it
pos accepts tuple, list, or appropriately-sized sequence

Acceptance Criteria

NoiseSource can be constructed with all parameters
All properties return correct values
get, fbm, turbulence return values in [-1, 1]
Same seed produces same results
Different seeds produce different results
Dimension mismatch raises ValueError
Unit tests for determinism and range

**Parent Issue:** #192 ## Overview Implement `NoiseSource` as a configured noise generator function. Stateless and infinite - the same coordinates always produce the same value. ## Specification ### Constructor ```python NoiseSource(dimensions: int = 2, algorithm: str = "simplex", hurst: float = 0.5, lacunarity: float = 2.0, seed: int = None) ``` | Parameter | Type | Description | |-----------|------|-------------| | `dimensions` | `int` | 1-4. Number of input dimensions. Default: 2. | | `algorithm` | `str` | `"simplex"`, `"perlin"`, or `"wavelet"`. Default: `"simplex"`. | | `hurst` | `float` | Fractal Hurst exponent for fbm/turbulence. Default: 0.5. | | `lacunarity` | `float` | Frequency multiplier between octaves. Default: 2.0. | | `seed` | `int` | Random seed. None for random. | ### Properties All properties are read-only. | Property | Type | Description | |----------|------|-------------| | `dimensions` | `int` | Number of input dimensions. | | `algorithm` | `str` | Noise algorithm name. | | `hurst` | `float` | Hurst exponent. | | `lacunarity` | `float` | Lacunarity value. | | `seed` | `int` | Seed used (even if originally None). | ### Point Query Methods ```python def get(self, pos: tuple[float, ...]) -> float ``` Get flat noise value at coordinates. Tuple length must match dimensions. Returns -1.0 to 1.0. ```python def fbm(self, pos: tuple[float, ...], octaves: int = 4) -> float ``` Get fractal brownian motion value. Returns -1.0 to 1.0. ```python def turbulence(self, pos: tuple[float, ...], octaves: int = 4) -> float ``` Get turbulence (absolute fbm) value. Returns -1.0 to 1.0. ### Example ```python noise = mcrfpy.NoiseSource(dimensions=2, algorithm="simplex", seed=42) # Point queries value = noise.get((10.5, 20.3)) fbm_value = noise.fbm((10.5, 20.3), octaves=6) turb_value = noise.turbulence((10.5, 20.3), octaves=4) # Same coordinates always give same result assert noise.get((10.5, 20.3)) == value ``` ## Implementation Notes - Wrap `TCODNoise` internally - `get` maps to `TCOD_noise_get` - `fbm` maps to `TCOD_noise_get_fbm` - `turbulence` maps to `TCOD_noise_get_turbulence` - If seed is None, generate random seed and store it - `pos` accepts tuple, list, or appropriately-sized sequence ## Acceptance Criteria - [ ] `NoiseSource` can be constructed with all parameters - [ ] All properties return correct values - [ ] `get`, `fbm`, `turbulence` return values in [-1, 1] - [ ] Same seed produces same results - [ ] Different seeds produce different results - [ ] Dimension mismatch raises `ValueError` - [ ] Unit tests for determinism and range