[Proc Gen] NoiseSource.sample and NoiseSample class #208

New issue

Open

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

john commented

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

Owner

Parent Issue: #192
Depends On: #193 (HeightMap core), #207 (NoiseSource core)

Overview

Add batch sampling method to NoiseSource and implement the NoiseSample subclass.

Specification

NoiseSource.sample

def sample(self,
           size: tuple[int, int],
           world_origin: tuple[float, float] = (0.0, 0.0),
           world_size: tuple[float, float] = None,
           mode: str = "fbm",
           octaves: int = 4) -> NoiseSample

Parameter	Type	Description
`size`	`(int, int)`	Output dimensions in cells.
`world_origin`	`(float, float)`	World coordinates of top-left corner. Default: (0, 0).
`world_size`	`(float, float)`	World area to sample. Default: same as `size`.
`mode`	`str`	`"flat"`, `"fbm"`, or `"turbulence"`. Default: `"fbm"`.
`octaves`	`int`	Octaves for fbm/turbulence. Default: 4.

Note: Uses (origin, size) format consistent with McRogueFace conventions, not ((x1,y1), (x2,y2)).

NoiseSample Class

NoiseSample extends HeightMap with noise-specific context.

Properties

Property	Type	Description
`source`	`NoiseSource`	Read-only. The generator that created this sample.
`world_origin`	`(float, float)`	Read-only. World coordinates of top-left.
`world_size`	`(float, float)`	Read-only. World area sampled.
`mode`	`str`	Read-only. `"flat"`, `"fbm"`, or `"turbulence"`.
`octaves`	`int`	Read-only. Octaves used for sampling.

def next_left(self) -> NoiseSample
def next_right(self) -> NoiseSample
def next_up(self) -> NoiseSample
def next_down(self) -> NoiseSample

Sample the adjacent region in the specified direction. Returns a new NoiseSample with the same size, mode, and octaves, but shifted world_origin.

Example

noise = mcrfpy.NoiseSource(seed=42)

# Sample a region
sample = noise.sample(
    size=(100, 100),
    world_origin=(0, 0),
    world_size=(10, 10),  # 10x zoom for smooth features
    mode="fbm",
    octaves=4
)

# Get adjacent chunk when player moves
right_chunk = sample.next_right()  # world_origin shifted by world_size[0]

# Minimap: same world area, smaller output
minimap = noise.sample(
    size=(20, 20),
    world_origin=(0, 0),
    world_size=(100, 100),  # Large area, small output = overview
    mode="fbm",
    octaves=3
)

Implementation Notes

NoiseSample inherits all HeightMap methods
Sampling formula: For output cell (x, y), sample world coordinate:
- wx = world_origin[0] + (x / size[0]) * world_size[0]
- wy = world_origin[1] + (y / size[1]) * world_size[1]
Navigation shifts origin by world_size in that direction
Removed: resample() and zoom() - users can achieve these with direct sample() calls

Acceptance Criteria

sample() creates NoiseSample with correct values
world_size controls feature scale (larger = zoomed out)
Navigation methods produce contiguous samples
NoiseSample works with all HeightMap operations
Visual demo showing tiled noise

**Parent Issue:** #192 **Depends On:** #193 (HeightMap core), #207 (NoiseSource core) ## Overview Add batch sampling method to NoiseSource and implement the NoiseSample subclass. ## Specification ### NoiseSource.sample ```python def sample(self, size: tuple[int, int], world_origin: tuple[float, float] = (0.0, 0.0), world_size: tuple[float, float] = None, mode: str = "fbm", octaves: int = 4) -> NoiseSample ``` | Parameter | Type | Description | |-----------|------|-------------| | `size` | `(int, int)` | Output dimensions in cells. | | `world_origin` | `(float, float)` | World coordinates of top-left corner. Default: (0, 0). | | `world_size` | `(float, float)` | World area to sample. Default: same as `size`. | | `mode` | `str` | `"flat"`, `"fbm"`, or `"turbulence"`. Default: `"fbm"`. | | `octaves` | `int` | Octaves for fbm/turbulence. Default: 4. | **Note:** Uses `(origin, size)` format consistent with McRogueFace conventions, not `((x1,y1), (x2,y2))`. ### NoiseSample Class NoiseSample extends HeightMap with noise-specific context. #### Properties | Property | Type | Description | |----------|------|-------------| | `source` | `NoiseSource` | Read-only. The generator that created this sample. | | `world_origin` | `(float, float)` | Read-only. World coordinates of top-left. | | `world_size` | `(float, float)` | Read-only. World area sampled. | | `mode` | `str` | Read-only. `"flat"`, `"fbm"`, or `"turbulence"`. | | `octaves` | `int` | Read-only. Octaves used for sampling. | #### Navigation Methods ```python def next_left(self) -> NoiseSample def next_right(self) -> NoiseSample def next_up(self) -> NoiseSample def next_down(self) -> NoiseSample ``` Sample the adjacent region in the specified direction. Returns a new NoiseSample with the same size, mode, and octaves, but shifted world_origin. ### Example ```python noise = mcrfpy.NoiseSource(seed=42) # Sample a region sample = noise.sample( size=(100, 100), world_origin=(0, 0), world_size=(10, 10), # 10x zoom for smooth features mode="fbm", octaves=4 ) # Get adjacent chunk when player moves right_chunk = sample.next_right() # world_origin shifted by world_size[0] # Minimap: same world area, smaller output minimap = noise.sample( size=(20, 20), world_origin=(0, 0), world_size=(100, 100), # Large area, small output = overview mode="fbm", octaves=3 ) ``` ## Implementation Notes - NoiseSample inherits all HeightMap methods - Sampling formula: For output cell (x, y), sample world coordinate: - `wx = world_origin[0] + (x / size[0]) * world_size[0]` - `wy = world_origin[1] + (y / size[1]) * world_size[1]` - Navigation shifts origin by world_size in that direction - **Removed:** `resample()` and `zoom()` - users can achieve these with direct `sample()` calls ## Acceptance Criteria - [ ] `sample()` creates NoiseSample with correct values - [ ] `world_size` controls feature scale (larger = zoomed out) - [ ] Navigation methods produce contiguous samples - [ ] NoiseSample works with all HeightMap operations - [ ] Visual demo showing tiled noise