0
# OpenSimplex
1

2
OpenSimplex is a noise generation function that provides 2D, 3D, and 4D gradient noise without the patent issues of Simplex noise or the directional artifacts of Perlin noise. It offers both single-value and high-performance array-based operations for procedural generation, computer graphics, and scientific applications.
3

4
## Package Information
5

6
- **Package Name**: opensimplex
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install opensimplex`
10
- **Dependencies**: `numpy>=1.22`
11
- **Python Version**: `>=3.8`
12

13
## Core Imports
14

15
```python
16
import opensimplex
17
```
18

19
For commonly used functions:
20

21
```python
22
from opensimplex import seed, noise2, noise3, noise4
23
```
24

25
For array operations:
26

27
```python
28
from opensimplex import noise2array, noise3array, noise4array
29
```
30

31
For class-based API:
32

33
```python
34
from opensimplex import OpenSimplex
35
```
36

37
## Basic Usage
38

39
```python
40
import opensimplex
41
import numpy as np
42

43
# Seed the noise generator for consistent results
44
opensimplex.seed(1234)
45

46
# Generate 2D noise
47
value_2d = opensimplex.noise2(x=10.0, y=10.0)
48
print(f"2D noise: {value_2d}")  # Output: -0.43906247097569345
49

50
# Generate 3D noise
51
value_3d = opensimplex.noise3(x=0.5, y=0.5, z=0.5)
52
print(f"3D noise: {value_3d}")  # Output: 0.39504955501618155
53

54
# Generate 4D noise
55
value_4d = opensimplex.noise4(x=0.5, y=0.5, z=0.5, w=0.5)
56
print(f"4D noise: {value_4d}")  # Output: 0.04520359600370195
57

58
# High-performance array operations
59
rng = np.random.default_rng(seed=0)
60
x_coords = rng.random(100)
61
y_coords = rng.random(100)
62
noise_array = opensimplex.noise2array(x_coords, y_coords)
63
print(f"Array shape: {noise_array.shape}")  # Output: (100, 100)
64
```
65

66
## Capabilities
67

68
### Seeding Functions
69

70
Control the random seed for deterministic noise generation.
71

72
```python { .api }
73
def seed(seed: int = 3) -> None:
74
    """
75
    Seeds the underlying permutation array using a 64-bit integer.
76
    If no value is provided, a static default (3) will be used.
77
    
78
    Args:
79
        seed: Integer seed value for deterministic noise generation
80
    """
81

82
def random_seed() -> None:
83
    """
84
    Seeds using system time in nanoseconds.
85
    Not guaranteed to be random, use at your own risk.
86
    """
87

88
def get_seed() -> int:
89
    """
90
    Return the value used to seed the initial state.
91
    
92
    Returns:
93
        Current seed as integer
94
    """
95
```
96

97
### 2D Noise Generation
98

99
Generate 2D OpenSimplex noise from X,Y coordinates.
100

101
```python { .api }  
102
def noise2(x: float, y: float) -> float:
103
    """
104
    Generate 2D OpenSimplex noise from X,Y coordinates.
105
    
106
    Args:
107
        x: x coordinate as float
108
        y: y coordinate as float
109
        
110
    Returns:
111
        Generated 2D noise as float, between -1.0 and 1.0
112
    """
113

114
def noise2array(x: np.ndarray, y: np.ndarray) -> np.ndarray:
115
    """
116
    Generates 2D OpenSimplex noise using NumPy arrays for increased performance.
117
    
118
    Args:
119
        x: numpy array of x-coords
120
        y: numpy array of y-coords
121
        
122
    Returns:
123
        2D numpy array of shape (y.size, x.size) with generated noise
124
        for the supplied coordinates
125
    """
126
```
127

128
### 3D Noise Generation
129

130
Generate 3D OpenSimplex noise from X,Y,Z coordinates.
131

132
```python { .api }
133
def noise3(x: float, y: float, z: float) -> float:
134
    """
135
    Generate 3D OpenSimplex noise from X,Y,Z coordinates.
136
    
137
    Args:
138
        x: x coordinate as float
139
        y: y coordinate as float
140
        z: z coordinate as float
141
        
142
    Returns:
143
        Generated 3D noise as float, between -1.0 and 1.0
144
    """
145

146
def noise3array(x: np.ndarray, y: np.ndarray, z: np.ndarray) -> np.ndarray:
147
    """
148
    Generates 3D OpenSimplex noise using NumPy arrays for increased performance.
149
    
150
    Args:
151
        x: numpy array of x-coords
152
        y: numpy array of y-coords
153
        z: numpy array of z-coords
154
        
155
    Returns:
156
        3D numpy array of shape (z.size, y.size, x.size) with generated 
157
        noise for the supplied coordinates
158
    """
159
```
160

161
### 4D Noise Generation
162

163
Generate 4D OpenSimplex noise from X,Y,Z,W coordinates.
164

165
```python { .api }
166
def noise4(x: float, y: float, z: float, w: float) -> float:
167
    """
168
    Generate 4D OpenSimplex noise from X,Y,Z,W coordinates.
169
    
170
    Args:
171
        x: x coordinate as float
172
        y: y coordinate as float
173
        z: z coordinate as float
174
        w: w coordinate as float
175
        
176
    Returns:
177
        Generated 4D noise as float, between -1.0 and 1.0
178
    """
179

180
def noise4array(x: np.ndarray, y: np.ndarray, z: np.ndarray, w: np.ndarray) -> np.ndarray:
181
    """
182
    Generates 4D OpenSimplex noise using NumPy arrays for increased performance.
183
    
184
    Args:
185
        x: numpy array of x-coords
186
        y: numpy array of y-coords
187
        z: numpy array of z-coords
188
        w: numpy array of w-coords
189
        
190
    Returns:
191
        4D numpy array of shape (w.size, z.size, y.size, x.size) with 
192
        generated noise for the supplied coordinates
193
    """
194
```
195

196
### Class-Based API
197

198
Backward-compatible class-based interface for multiple independent noise generators.
199

200
```python { .api }
201
class OpenSimplex:
202
    """
203
    OpenSimplex noise generator class. 
204
    Provided for backward compatibility - might disappear in future versions.
205
    """
206
    
207
    def __init__(self, seed: int) -> None:
208
        """
209
        Initialize OpenSimplex instance with specific seed.
210
        
211
        Args:
212
            seed: Integer seed for noise generation
213
        """
214
    
215
    def get_seed(self) -> int:
216
        """
217
        Return the seed value used to initialize this instance.
218
        
219
        Returns:
220
            Seed as integer
221
        """
222
    
223
    def noise2(self, x: float, y: float) -> float:
224
        """Generate 2D noise for this instance."""
225
    
226
    def noise2array(self, x: np.ndarray, y: np.ndarray) -> np.ndarray:
227
        """Generate 2D array noise for this instance."""
228
    
229
    def noise3(self, x: float, y: float, z: float) -> float:
230
        """Generate 3D noise for this instance."""
231
    
232
    def noise3array(self, x: np.ndarray, y: np.ndarray, z: np.ndarray) -> np.ndarray:
233
        """Generate 3D array noise for this instance."""
234
    
235
    def noise4(self, x: float, y: float, z: float, w: float) -> float:
236
        """Generate 4D noise for this instance."""
237
    
238
    def noise4array(self, x: np.ndarray, y: np.ndarray, z: np.ndarray, w: np.ndarray) -> np.ndarray:
239
        """Generate 4D array noise for this instance."""
240
```
241

242
## Constants
243

244
```python { .api }
245
DEFAULT_SEED = 3  # Default seed value used when no seed is provided
246
```
247

248
## Usage Examples
249

250
### Generating Terrain Heightmaps
251

252
```python
253
import opensimplex
254
import numpy as np
255
import matplotlib.pyplot as plt
256

257
# Set up parameters
258
opensimplex.seed(42)
259
width, height = 256, 256
260
scale = 0.05
261

262
# Create coordinate arrays
263
x = np.linspace(0, width * scale, width)
264
y = np.linspace(0, height * scale, height)
265

266
# Generate 2D noise array for terrain
267
terrain = opensimplex.noise2array(x, y)
268

269
# Normalize to 0-1 range for display
270
terrain_normalized = (terrain + 1) / 2
271

272
# Display the terrain
273
plt.imshow(terrain_normalized, cmap='terrain', origin='lower')
274
plt.colorbar(label='Height')
275
plt.title('Generated Terrain Heightmap')
276
plt.show()
277
```
278

279
### Animated 3D Noise
280

281
```python
282
import opensimplex
283
import numpy as np
284

285
# Initialize
286
opensimplex.seed(123)
287
frames = 100
288
resolution = 64
289

290
# Generate animated 3D noise
291
for frame in range(frames):
292
    time = frame * 0.1
293
    
294
    # Create coordinate grids
295
    x = np.linspace(0, 4, resolution)
296
    y = np.linspace(0, 4, resolution)
297
    z = np.full_like(x, time)  # Time as Z coordinate
298
    
299
    # Generate noise frame
300
    noise_frame = opensimplex.noise3array(x, y, z)
301
    
302
    # Process frame (save, display, etc.)
303
    print(f"Frame {frame}: noise range [{noise_frame.min():.3f}, {noise_frame.max():.3f}]")
304
```
305

306
### Multiple Independent Generators
307

308
```python
309
import opensimplex
310

311
# Create separate generators with different seeds
312
terrain_gen = opensimplex.OpenSimplex(seed=1001)
313
cloud_gen = opensimplex.OpenSimplex(seed=2002)
314
water_gen = opensimplex.OpenSimplex(seed=3003)
315

316
# Generate different types of noise independently
317
x, y = 10.5, 20.3
318
terrain_noise = terrain_gen.noise2(x, y)
319
cloud_noise = cloud_gen.noise2(x, y)
320
water_noise = water_gen.noise2(x, y)
321

322
print(f"Terrain: {terrain_noise:.3f}")
323
print(f"Clouds:  {cloud_noise:.3f}")
324
print(f"Water:   {water_noise:.3f}")
325
```