Perlin noise is the sum of several coherent-noise functions of ever-increasing frequencies and ever-decreasing amplitudes.
An important property of Perlin noise is that a small change in the input value will produce a small change in the output value, while a large change in the input value will produce a random change in the output value.
This noise module outputs Perlin-noise values that usually range from -1.0 to +1.0, but there are no guarantees that all output values will exist within that range.
For a better description of Perlin noise, see the links in the References and Acknowledgments section.
Octaves
The number of octaves control the amount of detail of the Perlin noise. Adding more octaves increases the detail of the Perlin noise, but with the drawback of increasing the calculation time.
An octave is one of the coherent-noise functions in a series of coherent-noise functions that are added together to form Perlin noise.
An application may specify the frequency of the first octave by
calling the setFrequency(double)
method.
An application may specify the number of octaves that generate Perlin
noise by calling the setOctaveCount(int)
method.
These coherent-noise functions are called octaves because each octave has, by default, double the frequency of the previous octave. Musical tones have this property as well; a musical C tone that is one octave higher than the previous C tone has double its frequency.
Frequency
An application may specify the frequency of the first octave by
calling the setFrequency(double)
method.
Persistence
The persistence value controls the roughness of the Perlin noise. Larger values produce rougher noise.
The persistence value determines how quickly the amplitudes diminish for successive octaves. The amplitude of the first octave is 1.0. The amplitude of each subsequent octave is equal to the product of the previous octave's amplitude and the persistence value. So a persistence value of 0.5 sets the amplitude of the first octave to 1.0; the second, 0.5; the third, 0.25; etc.
An application may specify the persistence value by calling the
setPersistence(double)
method.
Lacunarity
The lacunarity specifies the frequency multiplier between successive octaves.
The effect of modifying the lacunarity is subtle; you may need to play with the lacunarity value to determine the effects. For best results, set the lacunarity to a number between 1.5 and 3.5.
References & acknowledgments
The Noise Machine - From the master, Ken Perlin himself. This page contains a presentation that describes Perlin noise and some of its variants. He won an Oscar for creating the Perlin noise algorithm!
Perlin Noise - Hugo Elias's webpage contains a very good description of Perlin noise and describes its many applications. This page gave me the inspiration to create libnoise in the first place. Now that I know how to generate Perlin noise, I will never again use cheesy subdivision algorithms to create terrain (unless I absolutely need the speed).
The
Perlin noise math FAQ - A good page that describes Perlin noise in
plain English with only a minor amount of math. During development of
libnoise, I noticed that my coherent-noise function generated terrain
with some "regularity" to the terrain features. This page describes a
better coherent-noise function called gradient noise. This version of
Perlin
uses gradient coherent noise to generate Perlin noise.
- Source Modules
- This module does not require any source modules.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final double
Default frequency for thePerlin
noise module.static final double
Default lacunarity for thePerlin
noise module.static final int
Default number of octaves for thePerlin
noise module.static final double
Default persistence value for thePerlin
noise module.static final NoiseQuality
Default noise quality for thePerlin
noise module.static final int
Default noise seed for thePerlin
noise module.static final int
Maximum number of octaves for thePerlin
noise module.Fields inherited from class org.spongepowered.noise.module.NoiseModule
sourceModule
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptiondouble
Get the frequency of the first octave.double
get
(double x, double y, double z) Generates an output value given the coordinates of the specified input value.double
Get the lacunarity of the Perlin noise.double
maxValue()
Returns the maximum value the perlin module can output in its current configuration.Get the quality of the Perlin noise.int
Get the number of octaves that generate the Perlin noise.double
Get the persistence value of the Perlin noise.int
seed()
Get the seed value used by the Perlin noise function.void
setFrequency
(double frequency) Set the frequency of the first octave.void
setLacunarity
(double lacunarity) Sets the lacunarity of the Perlin noise.void
setNoiseQuality
(NoiseQuality noiseQuality) Sets the quality of the Perlin noise.void
setOctaveCount
(int octaveCount) Set the number of octaves that generate the Perlin noise.void
setPersistence
(double persistence) Sets the persistence value of the Perlin noise.void
setSeed
(int seed) Set the seed value used by the Perlin-noise function.Methods inherited from class org.spongepowered.noise.module.NoiseModule
setSourceModule, sourceModule, sourceModuleCount
-
Field Details
-
DEFAULT_PERLIN_FREQUENCY
public static final double DEFAULT_PERLIN_FREQUENCYDefault frequency for thePerlin
noise module.- See Also:
-
DEFAULT_PERLIN_LACUNARITY
public static final double DEFAULT_PERLIN_LACUNARITYDefault lacunarity for thePerlin
noise module.- See Also:
-
DEFAULT_PERLIN_OCTAVE_COUNT
public static final int DEFAULT_PERLIN_OCTAVE_COUNTDefault number of octaves for thePerlin
noise module.- See Also:
-
DEFAULT_PERLIN_PERSISTENCE
public static final double DEFAULT_PERLIN_PERSISTENCEDefault persistence value for thePerlin
noise module.- See Also:
-
DEFAULT_PERLIN_QUALITY
Default noise quality for thePerlin
noise module. -
DEFAULT_PERLIN_SEED
public static final int DEFAULT_PERLIN_SEEDDefault noise seed for thePerlin
noise module.- See Also:
-
PERLIN_MAX_OCTAVE
public static final int PERLIN_MAX_OCTAVEMaximum number of octaves for thePerlin
noise module.- See Also:
-
-
Constructor Details
-
Perlin
public Perlin()
-
-
Method Details
-
frequency
public double frequency()Get the frequency of the first octave.- Returns:
- the frequency of the first octave
- See Also:
-
setFrequency
public void setFrequency(double frequency) Set the frequency of the first octave.- Parameters:
frequency
- the frequency of the first octave
-
lacunarity
public double lacunarity()Get the lacunarity of the Perlin noise.The lacunarity is the frequency multiplier between successive octaves.
- Returns:
- the lacunarity of the Perlin noise
- See Also:
-
setLacunarity
public void setLacunarity(double lacunarity) Sets the lacunarity of the Perlin noise.The lacunarity is the frequency multiplier between successive octaves.
For best results, set the lacunarity to a number between 1.5 and 3.5.
- Parameters:
lacunarity
- the lacunarity of the Perlin noise
-
noiseQuality
Get the quality of the Perlin noise.See
NoiseQuality
for definitions of the various coherent-noise qualities.- Returns:
- the quality of the Perlin noise
- See Also:
-
setNoiseQuality
Sets the quality of the Perlin noise.See
NoiseQuality
for definitions of the various coherent-noise qualities.- Parameters:
noiseQuality
- the quality of the Perlin noise
-
octaveCount
public int octaveCount()Get the number of octaves that generate the Perlin noise.The number of octaves controls the amount of detail in the Perlin noise.
- Returns:
- the number of octaves that generate the Perlin noise
- See Also:
-
setOctaveCount
public void setOctaveCount(int octaveCount) Set the number of octaves that generate the Perlin noise.The octave count must be between 1 and
PERLIN_MAX_OCTAVE
, inclusive.The number of octaves controls the amount of detail in the Perlin noise.
The larger the number of octaves, the more time required to calculate the Perlin-noise value.
- Parameters:
octaveCount
- the number of octaves that generate the Perlin noise- Throws:
IllegalArgumentException
- if the octave count is out of bounds
-
persistence
public double persistence()Get the persistence value of the Perlin noise.The persistence value controls the roughness of the Perlin noise.
- Returns:
- the persistence value
- See Also:
-
setPersistence
public void setPersistence(double persistence) Sets the persistence value of the Perlin noise.The persistence value controls the roughness of the Perlin noise.
For best results, set the persistence to a number between 0.0 and 1.0.
- Parameters:
persistence
- the persistence value of the Perlin noise
-
seed
public int seed()Get the seed value used by the Perlin noise function.- Returns:
- the seed value
- See Also:
-
setSeed
public void setSeed(int seed) Set the seed value used by the Perlin-noise function.- Parameters:
seed
- the seed value
-
maxValue
public double maxValue()Returns the maximum value the perlin module can output in its current configuration.- Returns:
- The maximum possible value for
get(double, double, double)
to return
-
get
public double get(double x, double y, double z) Description copied from class:NoiseModule
Generates an output value given the coordinates of the specified input value.All source modules required by this module must have been connected with the
NoiseModule.setSourceModule(int, NoiseModule)
method. If these source modules are not connected, this method will throw aNoModuleException
.To determine the number of source modules required by this noise module, call the
NoiseModule.sourceModuleCount()
method.- Specified by:
get
in classNoiseModule
- Parameters:
x
- thex
coordinate of the input valuey
- they
coordinate of the input valuez
- thez
coordinate of the input value- Returns:
- the output value
-