A lightweight Java library for working with noise functions. Provides a collection of noise, distance and interpolation function classes for procedural content generation.
- Multiple noise function implementations
- Chainable noise wrappers for operating on noise functions
- Customizable distance functions
- Various interpolation methods
- Support for 1D, 2D, 3D and 4D noise generation
- Simple and flexible API
- Pure Java implementation with zero dependencies
An interface representing a noise function that has a set seed and can produce 1D, 2D, 3D and 4D noise values. The library provides the following NoiseFunction implementations:
ValueNoisePerlinNoiseSimplexNoiseVoronoiNoiseWorleyNoiseCellNoiseRandomNoise
An interface representing a function that wraps a noise function and operates on the values it provides. NoiseWrapper implementations provided by the library:
FractalNoiseTurbulentNoiseNoiseOperatorNoiseMapper
An interface which represents a distance function which is used by some noise functions (e.g. WorleyNoise, VoronoiNoise). Built-in DistanceFunction implementations:
EuclidianDistanceManhattanDistanceChebyshevDistanceMinkowskiDistanceQuadraticDistance
The library also provides a DistanceFunctions enumeration which contains immutable wrappers over each built-in distance function.
An interface representing an interpolation function which is used by some noise functions (e.g. ValueNoise, PerlinNoise). Built-in InterpolationFunction implementations:
LinearInterpolationCosineInterpolationQuadraticInterpolationSmoothstepInterpolationSmootherstepInterpolation
The library also provides a InteprolationFunctions enumeration which contains immutable wrappers over each built-in interpolation function.
A utility class providing methods for generating pseudo-random long and double numbers based on given values. This class is used by the built-in noise functions and can be used by the user implementing a custom NoiseFunction if needed.
Clone and build:
git clone https://github.com/kaba4cow/noise-functions.git
cd noise-functions
mvn clean installAdd to your pom.xml:
xml<dependency>
<groupId>com.kaba4cow</groupId>
<artifactId>noise-functions</artifactId>
<version>1.0.0</version>
</dependency>
Requirements:
- Java version 8 or higher.
The user may use noise functions provided by the library or create custom ones by implementing the NoiseFunction interface.
Here is an example of creating a WorleyNoise and setting its parameters:
WorleyFunction noise = new WorleyNoise();
noise.setRandomness(0.4);
noise.setDistance(DistanceFunctions.MINKOWSKI);The noise values can be computed using different getValue() overloads depenging on the desired dimensions:
double value1D = noise.getValue(7.81);
double value2D = noise.getValue(3.23, 2.0);
double value3D = noise.getValue(2.39, 0.65, 1.09);
double value4D = noise.getValue(3.14, 0.16, 21.3, 2.9);A NoiseFunction can be wrapped by a NoiseWrapper either by using the wrap() method:
FractalNoise noise = new PerlinNoise().wrap(FractalNoise::new);or by using the setNoise() method of the wrapper:
TurbulentNoise noise = new TurbulentNoise().setNoise(new ValueNoise());Chaining wrappers:
NoiseFunction noise = new WorleyNoise()
.wrap(NoiseOperator::new).setOperator(Math::abs)
.wrap(NoiseOperator::new).setOperator(value -> Math.pow(value, 1.5))
.wrap(NoiseMapper::new).setParameters(0.0, 1.0, -1.0, +1.0)
.wrap(FractalNoise::new).setOctaves(3);An UnsupportedDimensionsException is thrown when a class impements the NoiseFunction interface but does not support noise generation for a specific number of dimensions. When implementing a custom NoiseFunction the user has two options for handling unsupported dimensions:
- Strict (recommended): throw
UnsupportedDimensionsExceptionin each method that is not supported. This makes it explicit that the noise function does not handle certain dimensions and prevents unintended behavior.
@Override
public double getValue(double x, double y, double z) {
throw new UnsupportedDimensionsException(getClass(), 3);
}- Flexible: return a fallback value, e.g.
0.0. This can be useful if the user wants to allow calls to unsupported dimensions computation without causing exceptions but may lead to silent logical errors.
@Override
public double getValue(double x, double y, double z, double w) {
return 0.0;
}The recommended approach is to throw an exception unless a good reason to provide a fallback value is present.
All of the examples below use the following code to create images:
NoiseFunction noise;
// Noise initialization
int size = 256;
double frequency = 8.0;
BufferedImage image = new BufferedImage(size, size, BufferedImage.TYPE_INT_RGB);
for (int y = 0; y < size; y++)
for (int x = 0; x < size; x++) {
double nx = frequency * (x - 0.5 * size) / size;
double ny = frequency * (y - 0.5 * size) / size;
double value = noise.getValue(nx, ny);
int brightness = (int) ((0.5 + 0.5 * value) * 255);
int rgb = (brightness << 16) | (brightness << 8) | (brightness << 0);
image.setRGB(x, y, rgb);
}
ImageIO.write(image, "PNG", new File("output.png"));
noise = new PerlinNoise();
noise = new WorleyNoise();
noise = new VoronoiNoise();
noise = new SimplexNoise();
noise = noise.wrap(FractalNoise::new).setOctaves(8).setAmplitudeCoefficient(0.43);
noise = new CellNoise();
noise = noise.wrap(FractalNoise::new).setOctaves(8);
noise = new WorleyNoise().setDistance(DistanceFunctions.MINKOWSKI).setRandomness(0.73);
noise = noise.wrap(FractalNoise::new).setOctaves(3).setAmplitudeCoefficient(0.28);
noise = new ValueNoise().setInterpolation(InterpolationFunctions.COSINE);
noise = noise.wrap(TurbulentNoise::new).setLevels(4).setWarping(0.32);
noise = new SimplexNoise();
noise = noise.wrap(FractalNoise::new).setOctaves(3).setAmplitudeCoefficient(0.43);
noise = noise.wrap(TurbulentNoise::new).setLevels(7).setWarping(0.06);
noise = new WorleyNoise();
noise = noise.wrap(TurbulentNoise::new).setLevels(4).setWarping(0.13);
noise = noise.wrap(FractalNoise::new).setOctaves(4).setAmplitudeCoefficient(0.39);
noise = new WorleyNoise();
noise = noise.wrap(NoiseOperator::new).setOperator(Math::abs);
noise = noise.wrap(NoiseOperator::new).setOperator(value -> 1.0 - value);
noise = noise.wrap(NoiseOperator::new).setOperator(value -> value * value);
noise = noise.wrap(NoiseMapper::new).setParameters(0.0, 1.0, -1.0, +1.0);This project is licensed under the MIT License - see the LICENSE file for details.