noisey

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 27, 2016 License: BSD-2-Clause Imports: 5 Imported by: 4

README

Noisey v1.0.0

This library natively implements coherent noise algorithms in Go. No 3rd party libraries are required.

Currently it supports the following:

Sources
Generators and Modifiers
  • FBMGenerator2D - fractal Brownian Motion
  • Select2D - choose from source A or B depending on control source
  • Scale2D - modify output by multiplying by a scale and adding a bias constant

Additionally, noisey can load settings from a JSON configuration file and create sources and generators from that.

Installation

You can get the latest copy of the library using this command:

go get github.com/tbogdala/noisey

You can then use it in your code by importing it:

import "github.com/tbogdala/noisey"

Samples

Noisey comes with a couple examples to show how noise is built:

  • noise_text_image: outputs noise through a text gradient to terminal
  • noise_gl : makes a simple texture and draws it with OpenGL
  • noise_builder_gl: uses the noise builder to compose noise and displays the texture in OpenGL
  • noise_from_json_gl: creates the noise builder from JSON and then displays the texture in OpenGL

Below is a screen shot of what noise_from_json_gl outputs.

noise_from_json_gl

Usage

Full examples can be found in the examples folder, but this fragment will illustrate basic usage of Perlin noise:

import "github.com/tbogdala/noisey"

// ... yadda yadda yadda ...

// create a new RNG from Go's built in library with a seed of '1'
r := rand.New(rand.NewSource(int64(1)))

// create a new perlin noise generator using the RNG created above
perlin := noisey.NewPerlinGenerator(r)

// get the noise value at point (0.4, 0.2)
v := perlin.Get2D(0.4, 0.2)

If you want "smooth" noise, or fractal Brownian motion, then you use the noise generator with another structure:

import "github.com/tbogdala/noisey"

// ... yadda yadda yadda ...

// create a new RNG from Go's built in library with a seed of '1'
r := rand.New(rand.NewSource(int64(1)))

// create a new Perlin noise generator using the RNG created above
noiseGen := noisey.NewPerlinGenerator(r)

// create the fractal Brownian motion modifier based on Perlin
fbmPerlin := noisey.NewFBMGenerator2D(&noiseGen)
fbmPerlin.Octaves = 5
fbmPerlin.Persistence = 0.25
fbmPerlin.Lacunarity = 2.0
fbmPerlin.Frequency = 1.13

// get the noise value at point (0.4, 0.2)
v := fbmPerlin.Get2D(0.4, 0.2)

Samples that display noise to console or OpenGL windows are included. If the OpenGL examples are desired, you must also install the Go libraries github.com/go-gl/gl and github.com/go-gl/glfw3

Other noise generators like Open Simplex can be used in similar manner. Just create the noise generator with the constructor by passing a random number generator:

// create a new RNG from Go's built in library with a seed of '1'
r := rand.New(rand.NewSource(int64(1)))

// create a new OpenSimplex noise generator using the RNG created above
opensimplex := noisey.NewOpenSimplexGenerator(r)

Benchmarks

Benchmarks can be run with Go's built-in test tool by executing the following:

cd $GOPATH/src/github.com/tbogdala/noisey
go test -cpu 4 -bench .

The cpu flag can be adjusted accordingly, but shouldn't make a difference since the generators don't improve in parallel operation.

License

Noisey is released under the BSD license. See the LICENSE file for more details.

Documentation

Overview

Package noisey is a library that implements coherent noise algorithms.

The selection is currently:

  • 2D/3D Perlin noise (64bit)
  • 2D/3D OpenSimplex noise (64bit)

The sources above can be combined with different generators and modifiers like the following:

  • FBMGenerator2D - fractal Brownian Motion
  • Select2D - choose from source A or B depending on control source
  • Scale2D - modify output by multiplying by a scale and adding a bias constant

Once the noise generators have been set up, a Builder2D object can be created to map a region of noise into a float64 array.

An interface called 'RandomSource' is also exported so that a client can implement a different random number generator and pass it to the noise generators.

Sample programs can be found in the 'examples' directory.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Builder2D

type Builder2D struct {
	Source NoiseyGet2D
	Width  int
	Height int
	Bounds Builder2DBounds
	Values []float64
}

Builder2D contains the parameters and data for the noise 'map' generated with Build().

func NewBuilder2D

func NewBuilder2D(s NoiseyGet2D, width int, height int) (b Builder2D)

NewBuilder2D creates a new 2D noise 'map' builder of the given size

func (*Builder2D) Build

func (b *Builder2D) Build()

Build gets noise from Source for each spot in the data array. These steps are real numbers so that Bounds does not have to match Width/Height.

func (*Builder2D) GetMinMax

func (b *Builder2D) GetMinMax() (min float64, max float64)

GetMinMax returns the lowest and the highest Values

type Builder2DBounds

type Builder2DBounds struct {
	MinX, MinY, MaxX, MaxY float64
}

Builder2DBounds is a simple rectangle type.

type FBMGenerator2D

type FBMGenerator2D struct {
	NoiseMaker  NoiseyGet2D // the interface FBMGenerator2D uses gets noise values
	Octaves     int         // the number of octaves to calculate on each Get()
	Persistence float64     // a multiplier that determines how quickly the amplitudes diminish for each successive octave
	Lacunarity  float64     // a multiplier that determines how quickly the frequency increases for each successive octave
	Frequency   float64     // the number of cycles per unit length
}

FBMGenerator2D takes noise and makes fractal Brownian motion values.

func NewFBMGenerator2D

func NewFBMGenerator2D(noise NoiseyGet2D, octaves int, persistence float64, lacunarity float64, frequency float64) (fbm FBMGenerator2D)

NewFBMGenerator2D creates a new fractal Brownian motion generator state. A 'default' fBm would have 1 octave, 0.5 persistence, 2.0 lacunarity and 1.0 frequency.

func (*FBMGenerator2D) Get2D

func (fbm *FBMGenerator2D) Get2D(x float64, y float64) (v float64)

Get2D calculates the noise value over the number of Octaves and other parameters that scale the coordinates over each octave.

type FBMGenerator3D

type FBMGenerator3D struct {
	NoiseMaker  NoiseyGet3D // the interface FBMGenerator3D uses gets noise values
	Octaves     int         // the number of octaves to calculate on each Get()
	Persistence float64     // a multiplier that determines how quickly the amplitudes diminish for each successive octave
	Lacunarity  float64     // a multiplier that determines how quickly the frequency increases for each successive octave
	Frequency   float64     // the number of cycles per unit length
}

FBMGenerator3D takes noise and makes fractal Brownian motion values.

func NewFBMGenerator3D

func NewFBMGenerator3D(noise NoiseyGet3D, octaves int, persistence float64, lacunarity float64, frequency float64) (fbm FBMGenerator3D)

NewFBMGenerator3D creates a new fractal Brownian motion generator state. A 'default' fBm would have 1 octave, 0.5 persistence, 2.0 lacunarity and 1.0 frequency.

func (*FBMGenerator3D) Get3D

func (fbm *FBMGenerator3D) Get3D(x float64, y float64, z float64) (v float64)

Get3D calculates the noise value over the number of Octaves and other parameters that scale the coordinates over each octave.

type GeneratorJSON

type GeneratorJSON struct {
	// Name is the name of the generator that might be referenced by
	// other GeneratorJSON objects
	Name string

	// GeneratorType is a type string to identify what generator to create
	// on BuildGenerators()
	GeneratorType string

	// Sources is an array of strings that are names in the NoiseJSON.Sources
	// map that are to be used in this generator.
	Sources []string

	// Generators is an array of strings that are names in the NoiseJSON.Generators
	// map that are to be used in this generator.
	Generators []string

	Octaves     int     // Octaves is generator specific ...
	Persistence float64 // Persistence is generator specific ...
	Lacunarity  float64 // Lacunarity is generator specific ...
	Frequency   float64 // Frequency is generator specific ...
	LowerBound  float64 // LowerBound is generator specific ...
	UpperBound  float64 // LowerBound is generator specific ...
	EdgeFalloff float64 // EdgeFalloff is generator specific ...
	Scale       float64 // Scale is generator specific ...
	Bias        float64 // Scale is generator specific ...
	Min         float64 // Min is generator specific ...
	Max         float64 // Min is generator specific ...
}

GeneratorJSON is a generic data structure for noise generators in noisey. Something like a C union, not all of the fields may be applicable to every generator type.

type NoiseJSON

type NoiseJSON struct {
	// Seeds uses a name string as a key that can be referenced in SourceJSON
	// structures and can have predefined seed values. When calling BuildSources(),
	// a client may pass a function to build the actual RandomSource interface
	// and is therefore not bound to use this ...
	Seeds map[string]int64

	// Sources uses a name string as a key that can be referenced in other structures
	// and maps to a SoruceJSON structure that describes how the noise source
	// should be built.
	Sources map[string]SourceJSON

	// Generators is an ordered array of GeneratorJSON objects that define how
	// noise should be built.
	Generators []GeneratorJSON
	// contains filtered or unexported fields
}

NoiseJSON is a structure that facilities the saving and loading of JSON representations of a system of seeds, sources and generators of noise.

func LoadNoiseJSON

func LoadNoiseJSON(bytes []byte) (*NoiseJSON, error)

LoadNoiseJSON unmarshals the JSON from the byte array and returns a NoiseJSON object on success; error otherwise.

func NewNoiseJSON

func NewNoiseJSON() *NoiseJSON

NewNoiseJSON creates a new structure that can be used to save noise settings out to JSON or to load noise settings in from a JSON byte array.

func (*NoiseJSON) BuildGenerators

func (cfg *NoiseJSON) BuildGenerators() error

BuildGenerators creates NoiseyGet2D interface objects based off of the settings in the GeneratorJSON objects in NoiseJSON.Gnerators. This method should be called after BuildSources().

func (*NoiseJSON) BuildSources

func (cfg *NoiseJSON) BuildSources(seedBuilder RandomSeedBuilder) error

BuildSources takes a RandomSeedbuilder function as a parameter to create the actual random number generators from the seed provided and then creates the NoiseyGet2D interface objects based off of settings from SourceJSON structures in NoiseJSON.Sources. This method should be called before BuildGenerators().

func (*NoiseJSON) GetGenerator

func (cfg *NoiseJSON) GetGenerator(name string) NoiseyGet2D

GetGenerator returns a cached generator NoiseyGet2D object. This function Must be called after both BuildSources() and BuildGenerators().

func (*NoiseJSON) SaveNoiseJSON

func (cfg *NoiseJSON) SaveNoiseJSON() ([]byte, error)

SaveNoiseJSON marshals the structure into a JSON byte array that is indented nicely.

type NoiseyGet2D

type NoiseyGet2D interface {
	Get2D(float64, float64) float64
}

NoiseyGet2D is an interface defining how the modules types get noise from a source.

type NoiseyGet3D

type NoiseyGet3D interface {
	Get3D(float64, float64, float64) float64
}

NoiseyGet3D is an interface defining how the modules types get noise from a source.

type OpenSimplexGenerator

type OpenSimplexGenerator struct {
	Rng             RandomSource // random number generator interface
	Permutations    []int        // the random permutation table
	PermGradIndex3D []int
}

OpenSimplexGenerator stores the state information for generating opensimplex noise.

func NewOpenSimplexGenerator

func NewOpenSimplexGenerator(rng RandomSource) (osg OpenSimplexGenerator)

NewOpenSimplexGenerator creates a new state object for the open simplex noise generator

func (*OpenSimplexGenerator) Get2D

func (osg *OpenSimplexGenerator) Get2D(x float64, y float64) float64

Get2D calculates the noise at a given 2D coordinate

func (*OpenSimplexGenerator) Get3D

func (osg *OpenSimplexGenerator) Get3D(x float64, y float64, z float64) float64

Get3D calculates the noise at a given 3D coordinate

type PerlinGenerator

type PerlinGenerator struct {
	Rng             RandomSource // random number generator interface
	Permutations    []int        // the random permutation table
	RandomGradients []Vec4f      // the random gradient table
}

PerlinGenerator stores the state information for generating perlin noise.

func NewPerlinGenerator

func NewPerlinGenerator(rng RandomSource) (pg PerlinGenerator)

NewPerlinGenerator creates a new state object for the #D perlin noise generator

func (*PerlinGenerator) Get2D

func (pg *PerlinGenerator) Get2D(x, y float64) float64

Get2D calculates the perlin noise at a given 2D coordinate

func (*PerlinGenerator) Get3D

func (pg *PerlinGenerator) Get3D(x, y, z float64) float64

Get3D calculates the perlin noise at a given 3D coordinate

type RandomSeedBuilder

type RandomSeedBuilder func(s int64) RandomSource

RandomSeedBuilder is a type used to construct RandomSource interfaces from a seed listed in the configuration JSON

type RandomSource

type RandomSource interface {
	Float64() float64
	Perm(int) []int
}

RandomSource is a generic interface for a random number generator allowing the user to use the built-in RNG or a custom one that implements this interface.

type Scale2D

type Scale2D struct {
	// the noise that the select module uses
	Source NoiseyGet2D

	// what to scale the noise value from Source by
	Scale float64

	// the const value to add to the scaled noise value
	Bias float64

	// the minimum value to return
	Min float64

	// the maximum value to return
	Max float64
}

Scale2D is a module that uses gets the noise from Source, scales it and then adds a bias.

func NewScale2D

func NewScale2D(src NoiseyGet2D, scale float64, bias float64, min float64, max float64) (scales Scale2D)

Scale2D creates a new scale 2d module.

func (*Scale2D) Get2D

func (scales *Scale2D) Get2D(x float64, y float64) (v float64)

Get2D calculates the noise value scaling it by Scale and adding Bias

type Select2D

type Select2D struct {
	// the first channel of noise that the select module uses
	SourceA NoiseyGet2D

	// the second channel of noise that the select module uses
	SourceB NoiseyGet2D

	// a channel of noise that determines whether SourceA or SourceB gets
	// used as an output for a given coordinate
	Control NoiseyGet2D

	// if the value of Control is above LowerBound but below Upper Bound
	// then SourceB is output, otherwise SourceA is output
	LowerBound float64

	// if the value of Control is above LowerBound but below Upper Bound
	// then SourceB is output, otherwise SourceA is output
	UpperBound float64

	// the folloff value at the edge of a transition -- if <=0.0 there is an
	// abrupt transition from SourceA to SourceB, otherwise it specifies
	// the width of the transition range where values are blended between
	// the two sources
	EdgeFalloff float64
}

Select2D is a module that uses SourcesA or SourceB depending on the value coming from Control. If the value from control is between LowerBound and UpperBound then it uses SourceB, but otherwise it will use SourceA.

func NewSelect2D

func NewSelect2D(a, b, c NoiseyGet2D, lower float64, upper float64, edge float64) (selector Select2D)

NewSelect2D creates a new selector 2d module.

func (*Select2D) Get2D

func (selector *Select2D) Get2D(x float64, y float64) (v float64)

Get2D calculates the noise value using SourceA or SourceB depending on Control.

type Select3D

type Select3D struct {
	// the first channel of noise that the select module uses
	SourceA NoiseyGet3D

	// the second channel of noise that the select module uses
	SourceB NoiseyGet3D

	// a channel of noise that determines whether SourceA or SourceB gets
	// used as an output for a given coordinate
	Control NoiseyGet3D

	// if the value of Control is above LowerBound but below Upper Bound
	// then SourceB is output, otherwise SourceA is output
	LowerBound float64

	// if the value of Control is above LowerBound but below Upper Bound
	// then SourceB is output, otherwise SourceA is output
	UpperBound float64

	// the folloff value at the edge of a transition -- if <=0.0 there is an
	// abrupt transition from SourceA to SourceB, otherwise it specifies
	// the width of the transition range where values are blended between
	// the two sources
	EdgeFalloff float64
}

Select3D is a module that uses SourcesA or SourceB depending on the value coming from Control. If the value from control is between LowerBound and UpperBound then it uses SourceB, but otherwise it will use SourceA.

func NewSelect3D

func NewSelect3D(a, b, c NoiseyGet3D, lower float64, upper float64, edge float64) (selector Select3D)

NewSelect3D creates a new selector 3d module.

func (*Select3D) Get3D

func (selector *Select3D) Get3D(x, y, z float64) (v float64)

Get3D calculates the noise value using SourceA or SourceB depending on Control.

type SourceJSON

type SourceJSON struct {
	// SourceType is a type string used to identify what source module to create
	// on BuildSources().
	SourceType string

	// Seed is a string that needs to be a name in the NoiseJSON.Seeds map that
	// is to be used in this generator.
	Seed string
}

SourceJSON describes the source of the random information, like perlin2d.

type Vec2f

type Vec2f struct {
	X, Y float64
}

Vec2f is a simple 2D vector of 64 bit floats

type Vec2i

type Vec2i struct {
	X, Y int
}

Vec2i is a simple 3D vector of ints

type Vec3f

type Vec3f struct {
	X, Y, Z float64
}

Vec3f is a simple 3D vector of 64 bit floats

type Vec3i

type Vec3i struct {
	X, Y, Z int
}

Vec3i is a simple 3D vector of ints

type Vec4f

type Vec4f struct {
	X, Y, Z, W float64
}

Vec4f is a simple 4D vector of 64 bit floats

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL