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

New issue

Closed

opened 2026-01-12 00:10:53 +00:00 by john · 1 comment

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

john added a new dependency

2026-01-12 00:13:12 +00:00

#193 [Proc Gen] HeightMap - Core class with scalar operations

john added a new dependency

2026-01-12 00:13:14 +00:00

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

john referenced this issue

2026-01-12 00:13:58 +00:00

[Leader Issue] 7DRL 2026 ProcGen Systems #192

john added the

system:procgen

label

2026-01-12 00:18:22 +00:00

john added this to the Procedural Generation for 7DRL 2026 project

2026-01-12 01:04:22 +00:00

john commented

2026-01-12 12:54:18 +00:00

Author

Owner

See #206 for comparison for HeightMap subclassing: the actual custom type has been deferred for the BSP system. We will probably do the same here. It's not hard to keep track of sampling parameters and manage our own re-sampling to fetch adjacent regions of noise.

See #206 for comparison for `HeightMap` subclassing: the actual custom type has been deferred for the BSP system. We will probably do the same here. It's not hard to keep track of sampling parameters and manage our own re-sampling to fetch adjacent regions of noise.

john referenced this issue from a commit

2026-01-13 00:01:25 +00:00

Noise, combination, and sampling: first pass at #207, #208, #194, #209

john closed this issue

2026-01-16 22:20:48 +00:00