:mod:`noise` --- Noise functions ================================ .. module:: cgkit.noise :synopsis: A set of basic noise functions .. function:: noise(x[, y[, z[,t]]]) Returns a noise value (Perlin) in the range from 0 to 1. The arguments can be up to four floating point values or a sequence with up to 4 floating point values (e.g. a :class:`vec3` or a :class:`vec4`) with an optional time value. The return value is a pseudo random number in the range from 0 to 1. Due to the nature of this noise implementation (gradient noise) the return value at integer lattice points is always 0.5. As an example, here is a 2D slice (the grid shows the integer lattice): .. image:: pics/noise.* :width: 8cm :align: center .. note:: The actual function call depends on the number of arguments, so calling noise(x,y) is not the same as calling noise(x,y,0). The former case is a true 2D noise whereas the latter is 3D. The same difference exists between 3D and 4D. .. function:: snoise(x[, y[, z[,t]]]) Returns a signed noise value (Perlin) in the range from -1 to 1. A call to ``snoise(args)`` is equivalent to ``2*noise(args)-1``. .. function:: pnoise(point[, t], period[, tperiod]) Periodic noise function. Basically this is the same as :func:`noise` but with a periodic return value: ``pnoise(point) = pnoise(point+period)``. The time value can be either part of the point or it can be specified separately. The point and period must always have the same dimension. The return value is in the range from 0 to 1. .. function:: spnoise(point[, t], period[, tperiod]) Signed periodic noise function. The return value is in the range from -1 to 1. A call to ``spnoise(args)`` is equivalent to ``2*pnoise(args)-1``. .. function:: cellnoise(x[, y[, z[,t]]]) Returns a pseudo random number which is constant between integer lattice points. The return value is in the range from 0 to 1. As an example, here is a 2D slice (the grid shows the integer lattice): .. image:: pics/cellnoise.* :width: 8cm :align: center .. function:: scellnoise(x[, y[, z[,t]]]) Signed cell noise. The return value is in the range from -1 to 1. A call to ``scellnoise(args)`` is equivalent to ``2*cellnoise(args)-1``. .. function:: fBm(point, octaves, lacunarity=2.0, gain=0.5) Fractional Brownian motion. The argument point must be a sequence of either 2 or 3 float values (e.g. a :class:`vec3`). This function is a sum of noise values with different frequencies and amplitudes and is equivalent to the following code:: # fBm sum = 0.0 amp = 1.0 for i in range(octaves): sum += amp*snoise(point) amp *= gain point *= lacunarity The return value is in the range from 0 to 1. As an example, here is a 2D slice (the grid shows the integer lattice): .. image:: pics/fbm.* :width: 8cm :align: center .. function:: turbulence(point, octaves, lacunarity=2.0, gain=0.5) The code of the turbulence function is very similar to :func:`fBm`. The difference is that it sums up ``abs(snoise())`` instead of ``noise()``. However, the return value is in the range from 0 to 1. As an example, here is a 2D slice (the grid shows the integer lattice): .. image:: pics/turbulence.* :width: 8cm :align: center All of the above functions have a vector version that take the same input parameters but return a vector as result. The output always has the same dimension than the input. If the time value is specified separately it does not count to the dimension. For example a call to ``vnoise((x,y,z))`` returns a :class:`vec3`, just as a call to ``vnoise((x,y,z),t)``. However, a call to ``vnoise((x,y,z,t))`` returns a :class:`vec4`. .. function:: vnoise(x[, y[, z[,t]]]) See :func:`noise`. .. function:: vsnoise(x[, y[, z[,t]]]) See :func:`snoise`. .. function:: vpnoise(point[, t], period[, tperiod]) See :func:`pnoise`. .. function:: vspnoise(point[, t], period[, tperiod]) See :func:`spnoise`. .. function:: vcellnoise(x[, y[, z[,t]]]) See :func:`cellnoise`. .. function:: vscellnoise(x[, y[, z[,t]]]) See :func:`scellnoise`. .. function:: vfBm(point, octaves, lacunarity=2.0, gain=0.5) See :func:`fBm`. .. function:: vturbulence(point, octaves, lacunarity=2.0, gain=0.5) See :func:`turbulence`.