README.md

Go-Noise

go-noise is a Go package for generating a gradient noise between -1 and 1.

It is a wrapper to facilitate the use of go-perlin and opensimplex-go. And also to understand them better.

1D Example

In the example below, 1 dimmentional method noise.Generator.Eval64(x) was used to generate the noise value y at the position (x).

import "github.com/KEINOS/go-noise"

const seed = 100       // noise pattern ID
const smoothness = 100 // noise smoothness

// noiseType choises
//   noise.Perlin
//   noise.OpenSimplex
//   noise.Custom
n, err := noise.New(noise.Perlin, seed)

yy := n.Eval64(x / smoothness) // yy is between -1.0 and 1.0 of float64
y := (yy + 1) / 2 * 500        // y is between 0 and 500

• Source

2D Example

// Obtain the noise value at the position (x, y)
n, err := noise.New(noiseType, seed)
v := n.Eval64(x, y) // v is between -1.0 and 1.0 of float64

To create a 2D image, plot the v value at the position (x, y) in the 2D space. The 2D image example is equivalent to a frame of the 3D image example below.

3D Example

In the example below, three dimmentional method noise.Generator.Eval64(x, y, z) was used to generate the noise value at the position (x, y, z).

The x and y are the axes of 2D image and the z is the axis for "time", or animation frame, of the 3D noise sample.

Perlin Noise Sample

// Obtain the noise value at the position (x, y, z)
n, err := noise.New(noise.Perlin, seed)
v := n.Eval64(x, y, z) // v is between -1.0 and 1.0 of float64

• Source

OpenSimplex Noise Sample

// Obtain the noise value at the position (x, y, z)
n, err := noise.New(noise.OpenSimplex, seed)
v := n.Eval64(x, y, z) // v is between -1.0 and 1.0 of float64

• Source

Note

This package ONLY supports up to 3 dimensions. If more than 3 dimentions were given, such as noise.Generator.Eval64(w, x, y, z), it will retrun a 0 (zero) value.

Usage

Require module

go get "github.com/KEINOS/go-noise"

// import "github.com/KEINOS/go-noise"

Constructor

noise.New(noiseType noise.Algo, seed int64) (noise.Generator, error)

• Choises of noiseType
  • noise.Perlin: Uses the Perlin noise algorithm to generate the noise value.
  • noise.OpenSimplex: Uses the OpenSimplex noise algorithm to generate the noise value.
  • noise.Custom: Uses the user-defined function to generate noise value.
• seed
  • Seed is like pattern ID. If the seed values are the same, the noise pattern will also be the same.

const seed = 100

// Noise generator for Perlin noise
genNoise, err := noise.New(noise.Perlin, seed)

const seed = 100

// Noise generator for OpenSimplex noise
genNoise, err := noise.New(noise.OpenSimplex, seed)

const seed = 100

// Noise generator for Custom noise
genNoise, err := noise.New(noise.Custom, seed)

// User defined noise generator
myNoise32 := func(seed int64, dim ...float32) float32 {
    // ...
}

// Assign generator for float32 type
genNoise, err := genNoise.SetEval32(myNoise32)

Methods

a := genNoise.Eval32(x)       // 1D noise. Obtain noise value at x.
b := genNoise.Eval32(x, y)    // 2D noise. Obtain noise value at x, y.
c := genNoise.Eval32(x, y, z) // 3D noise. Obtain noise value at x, y, z.

// a, b, c, x, y, z are float32.
// Noises a, b, c are between -1.0 and 1.0.

a := genNoise.Eval64(x)       // 1D noise. Obtain noise value at x.
b := genNoise.Eval64(x, y)    // 2D noise. Obtain noise value at x, y.
c := genNoise.Eval64(x, y, z) // 3D noise. Obtain noise value at x, y, z.

// a, b, c, x, y, z are float64.
// Noises a, b, c are between -1.0 and 1.0.

Brief Example

import "github.com/KEINOS/go-noise"

const seed = 100
const frame = 50

// Create new noise generator of Perlin type
genNoise, err := noise.New(noise.Perlin, seed)

if err != nil {
    // error handle
}

for z := 0; z < frame; z++ {
    zz := float64(z) / 5 // smoothness between frames

    /* Here create a new image of a frame */

    for y := 0; y < height; y++ {
        yy := float64(y) / 25 // smoothness between plotting points

        for x := 0; x < width; x++ {
            xx := float64(x) / 25 // smoothness between plotting points

            // n is a float64 value between -1 and 1
            n := genNoise.Eval64(xx, yy, zz)

            // Convert n to 0-255 scale
            grayColor := ((1. - in) / 2.) * 255.

            pixelToPlot := color.Gray{Y: uint8(grayColor)}

            /* Here plot the pixel to the current image */
        }
    }

    /* Here save the current frame/image to a file */
}

/* Here animate the frames if you want */

• Complete Source

Contribute

• Pull Request:
  • Any PR for improvement is welcome! We will merge it as soon as it passes the CIs and not a prank-kind implementation. ;-)
  • PR Branch: main
    • It is recommended to do a "Draft-PR" before the actual implementation if the fix is big. However, feel free to discard it as well!
  • CI/CD: Github Actions
    • go test ./...
    • golangci-lint run
    • golint ./...
    • Code coverage check: 100% of coverage.
• Bug reports:
  • Issues
  • If possible, please attach a simple reproduction code sample of the error. PRs for the fixes are much appreciated. 🙏

Statuses

License

• Go-Noise: MIT, Copyright 2022 KEINOS and the Go-Noise Contributors.
  • Go-Perlin: MIT, Copyright 2022 Evgeniy Vasilev and his contributors.
  • OpenSimplex-Go: The Unlicense, By Owen Raccuglia and his contributors. Port of Java implementation of OpenSimplex Noise.
  • Other Go modules used in this package: go.mod
• Perlin Noise and Simplex Noise are the algorithms developed by Ken Perlin. OpenSimplex Noise is a Kurt Spencer's open sourced Java implementation.