noisy

README

Noisy

Noisy is a Go tool to generate textures and heightmaps with noises algorithm (up to 3 dimensions). This is useful for procedural generation, for example in game development. Using Perlin Noise (https://mrl.cs.nyu.edu/~perlin/noise/), it allows to combine different Sources (perlin noise, ridged multifractal) using Operators (e.g. add, multiply, clamps).

Basic Usage

Note that the returned values are always contained between [-1;1].

Sources

Multiple Sources are available, and you can create your own if you implement the SourceInterface.

Constant

Constant has a defined Value, and returns this value whatever is the position x,y,z.

source := noisy.Constant{1.0}

Sphere

Sphere has a Frequency setting the number of inner spheres, and an Offset to translate it.

source := noisy.Sphere{
	Frequency: 1.0,
	OffsetX: -0.5,
	OffsetY: -0.5,
	OffsetZ: -0.5,
}

White Noise

White Noise returns a completely random value between [-1;1].

source := noisy.WhiteNoise{}

Perlin Noise

Perlin Noise is a standard for noise generation.

source := noisy.Perlin{
    Frequency:   5.0,
    Lacunarity:  2.0,
    Persistence: 0.5,
    OctaveCount: 6,
    Seed:        42,
}

The parameters allow to custom the generated result:

• Frequency sets the first (biggest) Octave.
• Lacunarity sets the multiplier to the frequency for each successive Octave.
• Persistence sets the amplitude for each successive Octave.
• OctaveCount sets the number of Octaves to generate and blend.
• Seed sets the random seed, useful to regenerate the same image if required.

Billow

Billow Noise is similar to Perlin Noise, except it returns only absolute values. So the resulted content would be between [0;1].

source := noisy.Billow{
    Frequency:   5.0,
    Lacunarity:  2.0,
    Persistence: 0.5,
    OctaveCount: 6,
    Seed:        42,
}

Ridged Multifractal

Ridged Multifractal is based on the Perlin Noise, but allows visual effects similar to mountains.

source := noisy.RidgedMulti{
    Frequency:   5.0,
    Lacunarity:  2.0,
    Persistence: 0.5, 
    Offset:      0.4, 
    Gain:        0.6,
    OctaveCount: 6,
    Seed:        42,
}

The new parameters define the ridges:

• Offset is added for each successive Octave, enabling more ridges, a rougher result.
• Gain sets the factor for the high-frequency ridges, enabling more detailed noises in high Octaves.

Operators

Add

The Add operator sums two Sources.

Multiply

The Multiply operator multiply the values from two Sources.

Divide

The Divide operator divides the value from a Source A by the value from a Source B.

Invert

The Invert operator inverts the value. i.e. 1 => -1 and -1 => 1.

Max

The Max operator returns the highest value between two Sources.

Min

The Min operator returns the lowest value between two Sources.

Clamp

The Clamp operator returns the value from a Source, clamped between the Sources [Min;Max].

Abs

The Abs operator returns the absolute value from a Source, limiting it to [0;1].

Power

The Power operator returns the value from a Source A, powered by the value from a Source B.

Displace

The Displace operator uses the three input Sources to displace the coordinates of the Source, to compute the final value.

Turbulence

The Turbulence operator uses 3 internal Perlin Noise to generate random displacement. It takes a Source, and three properties used to generate the noise:

• Frequency
• Roughness, the number of Octaves of the 3 Perlin Noise
• Power, the scaling factor of the displacement

Turbulence1D

The Turbulence1D operator is similar to the Turbulence, except it uses only one Perlin Noise. This allows some different effect, more wave shaped.

Result

Once your generator is built, you can either fetch the value for one position:

value := generator.GetValue(0.0, 0.0, 0.0)

This value is contained between [-1;1].

You can also generate an image, stored on the filesystem:

err := RenderImg(generator, map[float64]color.RGBA{
-1.0: {0, 0, 0, 255},
1.0: {255, 255, 255, 255},
}, "noise.png", 1024, 1024)

if err != nil {
    fmt.Println(err.Error())
}

Complex Example

Let's create a volcanic island for a game. For the base of our island, we can use a circle (a Sphere source).

seed := 876310720398733142
generator := Multiply{
    Sphere{
        Frequency: 2.0,
        OffsetX:   -1.0,
        OffsetY:   -1.0,
        OffsetZ:   -1.0,
    },
    Clamp{
        SourceA: Add{
            Perlin{
                Frequency:   1.1,
                Lacunarity:  2.0,
                Persistence: 0.5,
                OctaveCount: 6,
                Seed:        seed,
            },
            RidgedMulti{
                Frequency:   3.0,
                Lacunarity:  2.0,
                Persistence: 0.5,
                Offset:      0.5,
                Gain:        0.8,
                OctaveCount: 5,
                Seed:        seed,
            },
        },
        Min: Constant{0.0},
        Max: Constant{1.0},
    },
}

What's next ?

Sources

• Checkboard source
• Cylinder source
• Sine source
• Voronoi source

Operators

• Terrace

Processes

• Gaussian Blur
• Erosion

Sources

• https://mrl.cs.nyu.edu/~perlin/noise/

Contributing Guidelines

See how to contribute.

Licence

This project is distributed under the Apache 2.0 licence.

Documentation

Index

• func RenderImg(source SourceInterface, gradient Gradient, filename string, width int, ...) error
• type Abs
  • func (abs Abs) GetValue(x, y, z float64) float64
• type Add
  • func (add Add) GetValue(x, y, z float64) float64
• type Billow
  • func (billow Billow) GetValue(x, y, z float64) float64
• type Clamp
  • func (clamp Clamp) GetValue(x, y, z float64) float64
• type Constant
  • func (constant Constant) GetValue(x, y, z float64) float64
• type Displace
  • func (displace Displace) GetValue(x, y, z float64) float64
• type Divide
  • func (divide Divide) GetValue(x, y, z float64) float64
• type Gradient
  • func (gradient Gradient) GetColor(position float64) (color.RGBA, error)
• type Invert
  • func (invert Invert) GetValue(x, y, z float64) float64
• type Max
  • func (max Max) GetValue(x, y, z float64) float64
• type Min
  • func (min Min) GetValue(x, y, z float64) float64
• type Multiply
  • func (multiply Multiply) GetValue(x, y, z float64) float64
• type Perlin
  • func (perlin Perlin) GetValue(x, y, z float64) float64
• type Power
  • func (power Power) GetValue(x, y, z float64) float64
• type RidgedMulti
  • func (ridgedMulti RidgedMulti) GetValue(x, y, z float64) float64
• type SourceInterface
• type Sphere
  • func (sphere Sphere) GetValue(x, y, z float64) float64
• type Turbulence
  • func (turbulence Turbulence) GetValue(x, y, z float64) float64
• type Turbulence1D
  • func (turbulence Turbulence1D) GetValue(x, y, z float64) float64
• type WhiteNoise
  • func (whiteNoise WhiteNoise) GetValue(x, y, z float64) float64

Functions

func RenderImg

func RenderImg(source SourceInterface, gradient Gradient, filename string, width int, height int) error

RenderImg generates an image from source, stored in filename.

The gradient parameter defines the colors to build the image. The parameters width & height defines the size. The image should be squared, to avoid deformations.

Types

type Abs

type Abs struct {
	Source SourceInterface
}

Abs takes 1 source on which to fetch the absolute values.

func (Abs) GetValue

func (abs Abs) GetValue(x, y, z float64) float64

GetValue returns the absolute value from Source.

type Add

type Add struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Add takes 2 sources to do the sum.

func (Add) GetValue

func (add Add) GetValue(x, y, z float64) float64

GetValue returns the sum of the values from the 2 sources.

type Billow

type Billow struct {
	Frequency, Lacunarity, Persistence float64
	OctaveCount, Seed                  int
}

Billow implements SourceInterface.

- Frequency sets the first (biggest) Octave. - Lacunarity sets the multiplier to the frequency for each successive Octave. - Persistence sets the amplitude for each successive Octave. - OctaveCount sets the number of Octaves to generate and blend. - Seed sets the random seed, useful to regenerate the same image if required.

func (Billow) GetValue

func (billow Billow) GetValue(x, y, z float64) float64

GetValue returns the value between [0;1] for a given 3D position.

It uses the Perlin Noise as a base, but returns the absolute values.

type Clamp

type Clamp struct {
	Source               SourceInterface
	SourceMin, SourceMax SourceInterface
}

Clamp takes 1 source and min/max values.

func (Clamp) GetValue

func (clamp Clamp) GetValue(x, y, z float64) float64

GetValue returns the value from Source, clamped between the values of SourceMin/SourceMax.

type Constant

type Constant struct {
	Value float64
}

Constant implements SourceInterface.

It stores a static Value.

func (Constant) GetValue

func (constant Constant) GetValue(x, y, z float64) float64

GetValue returns the static Constant.Value.

type Displace

type Displace struct {
	Source                    SourceInterface
	SourceX, SourceY, SourceZ SourceInterface
}

Displace takes 1 Source to which we modify the axis with the value of the three SourceX, SourceY, SourceZ.

func (Displace) GetValue

func (displace Displace) GetValue(x, y, z float64) float64

GetValue returns the value from Source, computed using the displacement of x,y,z with SourceX, SourceY and SourceZ values.

type Divide

type Divide struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Divide takes 2 sources to divide the value from the SourceA by the value of the SourceB.

func (Divide) GetValue

func (divide Divide) GetValue(x, y, z float64) float64

GetValue returns the division of the value from the SourceA by the value of the SourceB.

type Gradient

type Gradient map[float64]color.RGBA

Gradient is an unsorted map of colors, with positions [-1;1] as keys.

func (Gradient) GetColor

func (gradient Gradient) GetColor(position float64) (color.RGBA, error)

GetColor returns a color.RGBA for a given position.

The color is computed with lerp, to get the closest one from the Gradient map. An error is returned if the Gradient does not contain at least 2 colors.

type Invert

type Invert struct {
	Source SourceInterface
}

Invert takes 1 source from which to inverse the values.

func (Invert) GetValue

func (invert Invert) GetValue(x, y, z float64) float64

GetValue inverse (e.g. 1 => -1) the value from the Source.

type Max

type Max struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Max takes 1 source and a maximum value.

func (Max) GetValue

func (max Max) GetValue(x, y, z float64) float64

GetValue returns the value from SourceA, or the SourceB value if it is higher.

type Min

type Min struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Min takes 1 source and a minimum value.

func (Min) GetValue

func (min Min) GetValue(x, y, z float64) float64

GetValue returns the value from SourceA, or the SourceB value if it is lower.

type Multiply

type Multiply struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Multiply takes 2 sources to be multiplied.

func (Multiply) GetValue

func (multiply Multiply) GetValue(x, y, z float64) float64

GetValue returns the multiplication of the values from the 2 sources.

type Perlin

type Perlin struct {
	Frequency, Lacunarity, Persistence float64
	OctaveCount, Seed                  int
}

Perlin implements SourceInterface.

- Frequency sets the first (biggest) Octave. - Lacunarity sets the multiplier to the frequency for each successive Octave. - Persistence sets the amplitude for each successive Octave. - OctaveCount sets the number of Octaves to generate and blend. - Seed sets the random seed, useful to regenerate the same image if required.

func (Perlin) GetValue

func (perlin Perlin) GetValue(x, y, z float64) float64

GetValue returns the value between [-1;1] for a given 3D position.

type Power

type Power struct {
	SourceA SourceInterface
	SourceB SourceInterface
}

Power takes 2 sources.

func (Power) GetValue

func (power Power) GetValue(x, y, z float64) float64

GetValue returns the value from SourceA, powered by the value from SourceB.

type RidgedMulti

type RidgedMulti struct {
	Frequency, Lacunarity, Persistence, Offset, Gain float64
	OctaveCount, Seed                                int
}

RidgedMulti implements SourceInterface.

- Frequency sets the first (biggest) Octave. - Lacunarity sets the multiplier to the frequency for each successive Octave. - Persistence sets the amplitude for each successive Octave. - Offset is added for each successive Octave, enabling more ridges, a rougher result. - Gain sets the factor for the high-frequency ridges, enabling more detailed noises in high Octaves. - OctaveCount sets the number of Octaves to generate and blend. - Seed sets the random seed, useful to regenerate the same image if required.

func (RidgedMulti) GetValue

func (ridgedMulti RidgedMulti) GetValue(x, y, z float64) float64

GetValue returns the value between [-1;1] for a given 3D position.

type SourceInterface

type SourceInterface interface {
	GetValue(x, y, z float64) float64
}

SourceInterface defines a Source/Operator.

Its method GetValue returns a value between [-1;1], for a given 3 dimension position.

type Sphere

type Sphere struct {
	Frequency                 float64
	OffsetX, OffsetY, OffsetZ float64
}

Sphere is a SourceInterface.

Frequency is the quantity of inner spheres, and the Offsets allow a padding to center/move away the sphere(s).

func (Sphere) GetValue

func (sphere Sphere) GetValue(x, y, z float64) float64

GetValue returns the value between [-1;1] for a given 3D position.

type Turbulence

type Turbulence struct {
	Source           SourceInterface
	Frequency, Power float64
	Roughness, Seed  int
}

func (Turbulence) GetValue

func (turbulence Turbulence) GetValue(x, y, z float64) float64

GetValue returns the value from Source, computed using the displacement of x,y,z with SourceX, SourceY and SourceZ values.

type Turbulence1D

type Turbulence1D struct {
	Source           SourceInterface
	Frequency, Power float64
	Roughness, Seed  int
}

func (Turbulence1D) GetValue

func (turbulence Turbulence1D) GetValue(x, y, z float64) float64

GetValue returns the value from Source, computed using the displacement of x,y,z with SourceX, SourceY and SourceZ values.

type WhiteNoise

type WhiteNoise struct {
}

WhiteNoise implements SourceInterface.

It returns a completely random value.

func (WhiteNoise) GetValue

func (whiteNoise WhiteNoise) GetValue(x, y, z float64) float64

GetValue returns a random value between [-1;1] for a given 3D position.