Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/keinos/go-noise
Easy-to-use noise generator package in Golang for Perlin Noise and OpenSimplex Noise.
https://github.com/keinos/go-noise
go go-package golang golang-examples opensimplex-noise perlin-noise
Last synced: 7 days ago
JSON representation
Easy-to-use noise generator package in Golang for Perlin Noise and OpenSimplex Noise.
- Host: GitHub
- URL: https://github.com/keinos/go-noise
- Owner: KEINOS
- License: mit
- Created: 2022-05-24T06:18:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-07-06T08:09:34.000Z (about 2 years ago)
- Last Synced: 2024-09-28T21:21:38.689Z (7 days ago)
- Topics: go, go-package, golang, golang-examples, opensimplex-noise, perlin-noise
- Language: Go
- Homepage:
- Size: 5.29 MB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml "This package supports Go 1.17 or later")
[](https://pkg.go.dev/github.com/KEINOS/go-noise/ "View document and reference of this package")
# Go-Noise
[go-noise](https://github.com/KEINOS/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](https://github.com/aquilax/go-perlin) and [opensimplex-go](https://github.com/ojrac/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)`.
```go
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](./_example/2d)
## 2D Example
```go
// 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
```go
// 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](./_example/3d)
### OpenSimplex Noise Sample
```go
// 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](./_example/3d)
### 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
go get "github.com/KEINOS/go-noise"
// import "github.com/KEINOS/go-noise"
```
### Constructor
```go
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.
```go
const seed = 100
// Noise generator for Perlin noise
genNoise, err := noise.New(noise.Perlin, seed)
```
```go
const seed = 100
// Noise generator for OpenSimplex noise
genNoise, err := noise.New(noise.OpenSimplex, seed)
```
```go
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
```go
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.
```
```go
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
```go
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](./_example/3d)
## Contribute
[](https://pkg.go.dev/github.com/KEINOS/go-noise/ "View document and reference of this package")
[](https://github.com/KEINOS/go-noise/issues "Opened issues")
[](https://github.com/KEINOS/go-noise/pulls "Pull Requests")
- 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](https://github.blog/2019-02-14-introducing-draft-pull-requests/)" before the actual implementation if the fix is big. However, feel free to discard it as well!
- CI/CD: [Github Actions](./.github/workflows)
- `go test ./...`
- `golangci-lint run`
- `golint ./...`
- Code coverage check: 100% of coverage.
- Bug reports:
- [Issues](https://github.com/KEINOS/go-noise/issues)
- If possible, please attach a simple reproduction code sample of the error. PRs for the fixes are much appreciated. 🙏
### Statuses
[](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml "This package supports Go 1.17 or later")
[](https://github.com/KEINOS/go-noise/actions/workflows/platform-test.yml "Tests on Linux, macOS, Windows platforms")
[](https://github.com/KEINOS/go-noise/actions/workflows/golangci-lint.yml "Static analysis and lint check by golangci-lint")
[](https://github.com/KEINOS/go-noise/actions/workflows/codeQL-analysis.yml "Security and vulnerability analysis by CodeQL")
[](https://codecov.io/gh/KEINOS/go-noise "Code coverage")
[](https://goreportcard.com/report/github.com/KEINOS/go-noise "Code quality")
[](https://github.com/KEINOS/go-noise/actions/workflows/weekly-update.yml "Update go.mod to latest version")
### License
- [Go-Noise](https://github.com/KEINOS/go-noise): [MIT](https://github.com/KEINOS/go-noise/blob/main/LICENSE), Copyright 2022 [KEINOS and the Go-Noise Contributors](https://github.com/KEINOS/go-noise/graphs/contributors).
- [Go-Perlin](https://github.com/aquilax/go-perlin): [MIT](https://github.com/aquilax/go-perlin/blob/master/LICENSE), Copyright 2022 [Evgeniy Vasilev and his contributors](https://github.com/aquilax/go-perlin/graphs/contributors).
- [OpenSimplex-Go](https://github.com/ojrac/opensimplex-go): [The Unlicense](https://github.com/ojrac/opensimplex-go/blob/main/LICENSE), By [Owen Raccuglia and his contributors](https://github.com/ojrac/opensimplex-go/graphs/contributors). Port of [Java implementation of OpenSimplex Noise](https://gist.github.com/KdotJPG/b1270127455a94ac5d19).
- Other Go modules used in this package: [go.mod](https://github.com/KEINOS/go-noise/blob/main/go.mod)
- [Perlin Noise](https://en.wikipedia.org/wiki/Perlin_noise) and [Simplex Noise](https://en.wikipedia.org/wiki/Simplex_noise) are the algorithms developed by [Ken Perlin](https://en.wikipedia.org/wiki/Ken_Perlin). [OpenSimplex Noise](https://en.wikipedia.org/wiki/OpenSimplex_noise) is a [Kurt Spencer](https://github.com/KdotJPG/)'s [open sourced](https://gist.github.com/KdotJPG/b1270127455a94ac5d19#file-unlicense) [Java implementation](https://uniblock.tumblr.com/post/97868843242/noise).