1
2
3 """
4 The Blender.Noise submodule.
5
6 Noise and Turbulence
7 ====================
8
9 This module can be used to generate noise of various types. This can be used
10 for terrain generation, to create textures, make animations more 'animated',
11 object deformation, etc. As an example, this code segment when scriptlinked
12 to a framechanged event, will make the camera sway randomly about, by changing
13 parameters this can look like anything from an earthquake to a very nervous or
14 maybe even drunk cameraman... (the camera needs an ipo with at least one Loc &
15 Rot key for this to work!):
16
17 Example::
18 from Blender import Get, Scene, Noise
19 ####################################################
20 # This controls jitter speed
21 sl = 0.025
22 # This controls the amount of position jitter
23 sp = 0.1
24 # This controls the amount of rotation jitter
25 sr = 0.25
26 ####################################################
27
28 time = Get('curtime')
29 ob = Scene.GetCurrent().getCurrentCamera()
30 ps = (sl*time, sl*time, sl*time)
31 # To add jitter only when the camera moves, use this next line instead
32 #ps = (sl*ob.LocX, sl*ob.LocY, sl*ob.LocZ)
33 rv = Noise.vTurbulence(ps, 3, 0, Noise.NoiseTypes.NEWPERLIN)
34 ob.dloc = (sp*rv[0], sp*rv[1], sp*rv[2])
35 ob.drot = (sr*rv[0], sr*rv[1], sr*rv[2])
36
37 @type NoiseTypes: readonly dictionary
38 @var NoiseTypes: The available noise types.
39 - BLENDER
40 - STDPERLIN
41 - NEWPERLIN
42 - VORONOI_F1
43 - VORONOI_F2
44 - VORONOI_F3
45 - VORONOI_F4
46 - VORONOI_F2F1
47 - VORONOI_CRACKLE
48 - CELLNOISE
49
50 @type DistanceMetrics: readonly dictionary
51 @var DistanceMetrics: The available distance metrics values for Voronoi.
52 - DISTANCE
53 - DISTANCE_SQUARED
54 - MANHATTAN
55 - CHEBYCHEV
56 - MINKOVSKY_HALF
57 - MINKOVSKY_FOUR
58 - MINKOVISKY
59 """
60
61 NoiseTypes = {'BLENDER':0, 'STDPERLIN':1}
62
63 DistanceMetrics = {'DISTANCE':0}
64
66 """
67 Returns a random floating point number."
68 @rtype: float
69 @return: a random number in [0, 1).
70 """
71
73 """
74 Returns a random unit vector.
75 @rtype: 3-float list
76 @return: a list of three floats.
77 """
78
80 """
81 Initializes the random number generator.
82 @type seed: int
83 @param seed: the seed for the random number generator. If seed = 0, the
84 current time will be used as seed, instead.
85 """
86
88 """
89 Returns general noise of the optional specified type.
90 @type xyz: tuple of 3 floats
91 @param xyz: (x,y,z) float values.
92 @type type: int
93 @param type: the type of noise to return. See L{NoiseTypes}.
94 @rtype: float
95 @return: the generated noise value.
96 """
97
99 """
100 Returns noise vector of the optional specified type.
101 @type xyz: tuple of 3 floats
102 @param xyz: (x,y,z) float values.
103 @type type: int
104 @param type: the type of noise to return. See L{NoiseTypes}.
105 @rtype: 3-float list
106 @return: the generated noise vector.
107 """
108
109 -def turbulence (xyz, octaves, hard, basis = NoiseTypes['STDPERLIN'],
110 ampscale = 0.5, freqscale = 2.0):
111 """
112 Returns general turbulence value using the optional specified noise 'basis'
113 function.
114 @type xyz: 3-float tuple
115 @param xyz: (x,y,z) float values.
116 @type octaves: int
117 @param octaves: number of noise values added.
118 @type hard: bool
119 @param hard: noise hardness: 0 - soft noise; 1 - hard noise. (Returned value
120 is always positive.)
121 @type basis: int
122 @param basis: type of noise used for turbulence, see L{NoiseTypes}.
123 @type ampscale: float
124 @param ampscale: amplitude scale value of the noise frequencies added.
125 @type freqscale: float
126 @param freqscale: frequency scale factor.
127 @rtype: float
128 @return: the generated turbulence value.
129 """
130
131 -def vTurbulence (xyz, octaves, hard, basis = NoiseTypes['STDPERLIN'],
132 ampscale = 0.5, freqscale = 2.0):
133 """
134 Returns general turbulence vector using the optional specified noise basis
135 function.
136 @type xyz: 3-float tuple
137 @param xyz: (x,y,z) float values.
138 @type octaves: int
139 @param octaves: number of noise values added.
140 @type hard: bool
141 @param hard: noise hardness: 0 - soft noise; 1 - hard noise. (Returned
142 vector is always positive.)
143 @type basis: int
144 @param basis: type of noise used for turbulence, see L{NoiseTypes}.
145 @type ampscale: float
146 @param ampscale: amplitude scale value of the noise frequencies added.
147 @type freqscale: float
148 @param freqscale: frequency scale factor.
149 @rtype: 3-float list
150 @return: the generated turbulence vector.
151 """
152
153 -def fBm (xyz, H, lacunarity, octaves, basis = NoiseTypes['STDPERLIN']):
154 """
155 Returns Fractal Brownian Motion noise value (fBm).
156 @type xyz: 3-float tuple
157 @param xyz: (x,y,z) float values.
158 @type H: float
159 @param H: the fractal increment parameter.
160 @type lacunarity: float
161 @param lacunarity: the gap between successive frequencies.
162 @type octaves: float
163 @param octaves: the number of frequencies in the fBm.
164 @type basis: int
165 @param basis: type of noise used for the turbulence, see L{NoiseTypes}.
166 @rtype: float
167 @return: the generated noise value.
168 """
169
171 """
172 Returns Multifractal noise value.
173 @type xyz: 3-float tuple
174 @param xyz: (x,y,z) float values.
175 @type H: float
176 @param H: the highest fractal dimension.
177 @type lacunarity: float
178 @param lacunarity: the gap between successive frequencies.
179 @type octaves: float
180 @param octaves: the number of frequencies in the fBm.
181 @type basis: int
182 @param basis: type of noise used for the turbulence, see L{NoiseTypes}.
183 @rtype: float
184 @return: the generated noise value.
185 """
186
189 """
190 Returns Variable Lacunarity Noise value, a distorted variety of noise.
191 @type xyz: 3-float tuple
192 @param xyz: (x,y,z) float values.
193 @type distortion: float
194 @param distortion: the amount of distortion.
195 @type type1: int
196 @type type2: int
197 @param type1: sets the noise type to distort.
198 @param type2: sets the noise type used for the distortion.
199 @rtype: float
200 @return: the generated noise value.
201 """
202
205 """
206 Returns Heterogeneous Terrain value.
207 @type xyz: 3-float tuple
208 @param xyz: (x,y,z) float values.
209 @type H: float
210 @param H: fractal dimension of the roughest areas.
211 @type lacunarity: float
212 @param lacunarity: gap between successive frequencies.
213 @type octaves: float
214 @param octaves: number of frequencies in the fBm.
215 @type offset: float
216 @param offset: it raises the terrain from 'sea level'.
217 @type basis: int
218 @param basis: noise basis determines the type of noise used for the
219 turbulence, see L{NoiseTypes}.
220 @rtype: float
221 @return: the generated value.
222 """
223
226 """
227 Returns Hybrid Multifractal value.
228 @type xyz: 3-float tuple
229 @param xyz: (x,y,z) float values.
230 @type H: float
231 @param H: fractal dimension of the roughest areas.
232 @type lacunarity: float
233 @param lacunarity: gap between successive frequencies.
234 @type octaves: float
235 @param octaves: number of frequencies in the fBm.
236 @type offset: float
237 @param offset: it raises the terrain from 'sea level'.
238 @type gain: float
239 @param gain: scale factor.
240 @type basis: int
241 @param basis: noise basis determines the type of noise used for the
242 turbulence, see L{NoiseTypes}.
243 @rtype: float
244 @return: the generated value.
245 """
246
249 """
250 Returns Ridged Multifractal value.
251 @type xyz: 3-float tuple
252 @param xyz: (x,y,z) float values.
253 @type H: float
254 @param H: fractal dimension of the roughest areas.
255 @type lacunarity: float
256 @param lacunarity: gap between successive frequencies.
257 @type octaves: float
258 @param octaves: number of frequencies in the fBm.
259 @type offset: float
260 @param offset: it raises the terrain from 'sea level'.
261 @type gain: float
262 @param gain: scale factor.
263 @type basis: int
264 @param basis: noise basis determines the type of noise used for the
265 turbulence, see L{NoiseTypes}.
266 @rtype: float
267 @return: the generated value.
268 """
269
271 """
272 Returns Voronoi diagrams-related data.
273 @type xyz: 3-float tuple
274 @param xyz: (x,y,z) float values.
275 @type distance_metric: int
276 @param distance_metric: see L{DistanceMetrics}
277 @type exponent: float
278 @param exponent: only used with MINKOVSKY, default is 2.5.
279 @rtype: list
280 @return: a list containing a list of distances in order of closest feature,
281 and a list containing the positions of the four closest features.
282 """
283
285 """
286 Returns cellnoise.
287 @type xyz: 3-float tuple
288 @param xyz: (x,y,z) float values.
289 @rtype: float
290 @return: the generated value.
291 """
292
294 """
295 Returns cellnoise vector/point/color.
296 @type xyz: 3-float tuple
297 @param xyz: (x,y,z) float values.
298 @rtype: 3-float list
299 @return: the generated vector.
300 """
301