cleanup epydoc errors
[blender.git] / source / blender / python / api2_2x / doc / Noise.py
1 # Blender.Noise submodule
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
65 def random ():
66   """
67   Returns a random floating point number."
68   @rtype: float
69   @return: a random number in [0, 1).
70   """
71
72 def randuvec ():
73   """
74   Returns a random unit vector.
75   @rtype: 3-float list
76   @return: a list of three floats.
77   """
78
79 def setRandomSeed (seed):
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
87 def noise (xyz, type = NoiseTypes['STDPERLIN']):
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
98 def vNoise (xyz, type = NoiseTypes['STDPERLIN']):
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'], ampscale = 0.5, freqscale = 2.0):
132   """
133   Returns general turbulence vector using the optional specified noise basis function.
134   @type xyz: 3-float tuple
135   @param xyz: (x,y,z) float values.
136   @type octaves: int
137   @param octaves: number of noise values added.
138   @type hard: bool
139   @param hard: noise hardness: 0 - soft noise; 1 - hard noise.  (Returned
140       vector is always positive.)
141   @type basis: int
142   @param basis: type of noise used for turbulence, see L{NoiseTypes}.
143   @type ampscale: float
144   @param ampscale: amplitude scale value of the noise frequencies added.
145   @type freqscale: float
146   @param freqscale: frequency scale factor.
147   @rtype: 3-float list
148   @return: the generated turbulence vector.
149   """
150
151 def fBm (xyz, H, lacunarity, octaves, basis = NoiseTypes['STDPERLIN']):
152   """
153   Returns Fractal Brownian Motion noise value (fBm).
154   @type xyz: 3-float tuple
155   @param xyz: (x,y,z) float values.
156   @type H: float
157   @param H: the fractal increment parameter.
158   @type lacunarity: float
159   @param lacunarity: the gap between successive frequencies.
160   @type octaves: float
161   @param octaves: the number of frequencies in the fBm.
162   @type basis: int
163   @param basis: type of noise used for the turbulence, see L{NoiseTypes}.
164   @rtype: float
165   @return: the generated noise value.
166   """
167
168 def multiFractal (xyz, H, lacunarity, octaves, basis = NoiseTypes['STDPERLIN']):
169   """
170   Returns Multifractal noise value.
171   @type xyz: 3-float tuple
172   @param xyz: (x,y,z) float values.
173   @type H: float
174   @param H: the highest fractal dimension.
175   @type lacunarity: float
176   @param lacunarity: the gap between successive frequencies.
177   @type octaves: float
178   @param octaves: the number of frequencies in the fBm.
179   @type basis: int
180   @param basis: type of noise used for the turbulence, see L{NoiseTypes}.
181   @rtype: float
182   @return: the generated noise value.
183   """
184
185 def vlNoise (xyz, distortion, type1 = NoiseTypes['STDPERLIN'],
186     type2 = NoiseTypes['STDPERLIN']):
187   """
188   Returns Variable Lacunarity Noise value, a distorted variety of noise.
189   @type xyz: 3-float tuple
190   @param xyz: (x,y,z) float values.
191   @type distortion: float
192   @param distortion: the amount of distortion.
193   @type type1: int
194   @type type2: int
195   @param type1: sets the noise type to distort.
196   @param type2: sets the noise type used for the distortion.
197   @rtype: float
198   @return: the generated noise value.
199   """
200
201 def heteroTerrain (xyz, H, lacunarity, octaves, offset,
202     basis = NoiseTypes['STDPERLIN']):
203   """
204   Returns Heterogeneous Terrain value.
205   @type xyz: 3-float tuple
206   @param xyz: (x,y,z) float values.
207   @type H: float
208   @param H: fractal dimension of the roughest areas.
209   @type lacunarity: float
210   @param lacunarity: gap between successive frequencies.
211   @type octaves: float
212   @param octaves: number of frequencies in the fBm.
213   @type offset: float
214   @param offset: it raises the terrain from 'sea level'.
215   @type basis: int
216   @param basis: noise basis determines the type of noise used for the
217       turbulence, see L{NoiseTypes}.
218   @rtype: float
219   @return: the generated value.
220   """
221
222 def hybridMFractal (xyz, H, lacunarity, octaves, offset, gain,
223     basis = NoiseTypes['STDPERLIN']):
224   """
225   Returns Hybrid Multifractal value.
226   @type xyz: 3-float tuple
227   @param xyz: (x,y,z) float values.
228   @type H: float
229   @param H: fractal dimension of the roughest areas.
230   @type lacunarity: float
231   @param lacunarity: gap between successive frequencies.
232   @type octaves: float
233   @param octaves: number of frequencies in the fBm.
234   @type offset: float
235   @param offset: it raises the terrain from 'sea level'.
236   @type gain: float
237   @param gain: scale factor.
238   @type basis: int
239   @param basis: noise basis determines the type of noise used for the
240       turbulence, see L{NoiseTypes}.
241   @rtype: float
242   @return: the generated value.
243   """
244
245 def ridgedMFractal (xyz, H, lacunarity, octaves, offset, gain,
246     basis = NoiseTypes['STDPERLIN']):
247   """
248   Returns Ridged Multifractal value.
249   @type xyz: 3-float tuple
250   @param xyz: (x,y,z) float values.
251   @type H: float
252   @param H: fractal dimension of the roughest areas.
253   @type lacunarity: float
254   @param lacunarity: gap between successive frequencies.
255   @type octaves: float
256   @param octaves: number of frequencies in the fBm.
257   @type offset: float
258   @param offset: it raises the terrain from 'sea level'.
259   @type gain: float
260   @param gain: scale factor.
261   @type basis: int
262   @param basis: noise basis determines the type of noise used for the
263       turbulence, see L{NoiseTypes}.
264   @rtype: float
265   @return: the generated value.
266   """
267
268 def voronoi(xyz, distance_metric = DistanceMetrics['DISTANCE'], exponent = 2.5):
269   """
270   Returns Voronoi diagrams-related data.
271   @type xyz: 3-float tuple
272   @param xyz: (x,y,z) float values.
273   @type distance_metric: int
274   @param distance_metric: see L{DistanceMetrics}
275   @type exponent: float
276   @param exponent: only used with MINKOVSKY, default is 2.5.
277   @rtype: list
278   @return: a list containing a list of distances in order of closest feature,
279   and a list containing the positions of the four closest features.
280   """
281
282 def cellNoise (xyz):
283   """
284   Returns cellnoise.
285   @type xyz: 3-float tuple
286   @param xyz: (x,y,z) float values.
287   @rtype: float
288   @return: the generated value.
289   """
290
291 def cellNoiseV (xyz):
292   """
293   Returns cellnoise vector/point/color.
294   @type xyz: 3-float tuple
295   @param xyz: (x,y,z) float values.
296   @rtype: 3-float list
297   @return: the generated vector.
298   """