{"id":15034971,"url":"https://github.com/keinos/go-noise","last_synced_at":"2025-04-09T23:06:30.966Z","repository":{"id":37861555,"uuid":"495693991","full_name":"KEINOS/go-noise","owner":"KEINOS","description":"Easy-to-use noise generator package in Golang for Perlin Noise and OpenSimplex Noise.","archived":false,"fork":false,"pushed_at":"2022-07-06T08:09:34.000Z","size":5547,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-02T15:03:36.627Z","etag":null,"topics":["go","go-package","golang","golang-examples","opensimplex-noise","perlin-noise"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KEINOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null}},"created_at":"2022-05-24T06:18:07.000Z","updated_at":"2025-01-13T20:29:11.000Z","dependencies_parsed_at":"2022-09-01T15:23:01.138Z","dependency_job_id":null,"html_url":"https://github.com/KEINOS/go-noise","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KEINOS%2Fgo-noise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KEINOS%2Fgo-noise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KEINOS%2Fgo-noise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KEINOS%2Fgo-noise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KEINOS","download_url":"https://codeload.github.com/KEINOS/go-noise/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239073968,"owners_count":19577123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","go-package","golang","golang-examples","opensimplex-noise","perlin-noise"],"created_at":"2024-09-24T20:27:02.920Z","updated_at":"2025-02-16T00:32:14.925Z","avatar_url":"https://github.com/KEINOS.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![go1.17+](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml \"This package supports Go 1.17 or later\")\n[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-noise.svg)](https://pkg.go.dev/github.com/KEINOS/go-noise/ \"View document and reference of this package\")\n\n# Go-Noise\n\n[go-noise](https://github.com/KEINOS/go-noise) is a Go package for generating a gradient noise between -1 and 1.\n\nIt 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.\n\n## 1D Example\n\nIn the example below, 1 dimmentional method `noise.Generator.Eval64(x)` was used to generate the noise value `y` at the position `(x)`.\n\n```go\nimport \"github.com/KEINOS/go-noise\"\n\nconst seed = 100       // noise pattern ID\nconst smoothness = 100 // noise smoothness\n\n// noiseType choises\n//   noise.Perlin\n//   noise.OpenSimplex\n//   noise.Custom\nn, err := noise.New(noise.Perlin, seed)\n\nyy := n.Eval64(x / smoothness) // yy is between -1.0 and 1.0 of float64\ny := (yy + 1) / 2 * 500        // y is between 0 and 500\n```\n\n![](./_example/2d/2d_perlin.png)\n![](./_example/2d/2d_opensimplex.png)\n![](./_example/2d/2d_pseudorandom.png)\n\n- [Source](./_example/2d)\n\n## 2D Example\n\n```go\n// Obtain the noise value at the position (x, y)\nn, err := noise.New(noiseType, seed)\nv := n.Eval64(x, y) // v is between -1.0 and 1.0 of float64\n```\n\nTo 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.\n\n## 3D Example\n\nIn 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)`.\n\nThe `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.\n\n### Perlin Noise Sample\n\n```go\n// Obtain the noise value at the position (x, y, z)\nn, err := noise.New(noise.Perlin, seed)\nv := n.Eval64(x, y, z) // v is between -1.0 and 1.0 of float64\n```\n\n![](./_example/3d/animation_perlin.gif)\n\n- [Source](./_example/3d)\n\n### OpenSimplex Noise Sample\n\n```go\n// Obtain the noise value at the position (x, y, z)\nn, err := noise.New(noise.OpenSimplex, seed)\nv := n.Eval64(x, y, z) // v is between -1.0 and 1.0 of float64\n```\n\n![](./_example/3d/animation_opensimplex.gif)\n\n- [Source](./_example/3d)\n\n### Note\n\nThis 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.\n\n## Usage\n\n### Require module\n\n```go\ngo get \"github.com/KEINOS/go-noise\"\n\n// import \"github.com/KEINOS/go-noise\"\n```\n\n### Constructor\n\n```go\nnoise.New(noiseType noise.Algo, seed int64) (noise.Generator, error)\n```\n\n- Choises of `noiseType`\n    - `noise.Perlin`: Uses the Perlin noise algorithm to generate the noise value.\n    - `noise.OpenSimplex`: Uses the OpenSimplex noise algorithm to generate the noise value.\n    - `noise.Custom`: Uses the user-defined function to generate noise value.\n- `seed`\n    - Seed is like pattern ID. If the seed values are the same, the noise pattern will also be the same.\n\n```go\nconst seed = 100\n\n// Noise generator for Perlin noise\ngenNoise, err := noise.New(noise.Perlin, seed)\n```\n```go\nconst seed = 100\n\n// Noise generator for OpenSimplex noise\ngenNoise, err := noise.New(noise.OpenSimplex, seed)\n```\n```go\nconst seed = 100\n\n// Noise generator for Custom noise\ngenNoise, err := noise.New(noise.Custom, seed)\n\n// User defined noise generator\nmyNoise32 := func(seed int64, dim ...float32) float32 {\n    // ...\n}\n\n// Assign generator for float32 type\ngenNoise, err := genNoise.SetEval32(myNoise32)\n```\n\n### Methods\n\n```go\na := genNoise.Eval32(x)       // 1D noise. Obtain noise value at x.\nb := genNoise.Eval32(x, y)    // 2D noise. Obtain noise value at x, y.\nc := genNoise.Eval32(x, y, z) // 3D noise. Obtain noise value at x, y, z.\n\n// a, b, c, x, y, z are float32.\n// Noises a, b, c are between -1.0 and 1.0.\n```\n```go\na := genNoise.Eval64(x)       // 1D noise. Obtain noise value at x.\nb := genNoise.Eval64(x, y)    // 2D noise. Obtain noise value at x, y.\nc := genNoise.Eval64(x, y, z) // 3D noise. Obtain noise value at x, y, z.\n\n// a, b, c, x, y, z are float64.\n// Noises a, b, c are between -1.0 and 1.0.\n```\n\n### Brief Example\n\n```go\nimport \"github.com/KEINOS/go-noise\"\n\nconst seed = 100\nconst frame = 50\n\n// Create new noise generator of Perlin type\ngenNoise, err := noise.New(noise.Perlin, seed)\n\nif err != nil {\n    // error handle\n}\n\nfor z := 0; z \u003c frame; z++ {\n    zz := float64(z) / 5 // smoothness between frames\n\n    /* Here create a new image of a frame */\n\n    for y := 0; y \u003c height; y++ {\n        yy := float64(y) / 25 // smoothness between plotting points\n\n        for x := 0; x \u003c width; x++ {\n            xx := float64(x) / 25 // smoothness between plotting points\n\n            // n is a float64 value between -1 and 1\n            n := genNoise.Eval64(xx, yy, zz)\n\n            // Convert n to 0-255 scale\n            grayColor := ((1. - in) / 2.) * 255.\n\n            pixelToPlot := color.Gray{Y: uint8(grayColor)}\n\n            /* Here plot the pixel to the current image */\n        }\n    }\n\n    /* Here save the current frame/image to a file */\n}\n\n/* Here animate the frames if you want */\n```\n\n- [Complete Source](./_example/3d)\n\n## Contribute\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-noise.svg)](https://pkg.go.dev/github.com/KEINOS/go-noise/ \"View document and reference of this package\")\n[![Opened Issues](https://img.shields.io/github/issues/KEINOS/go-noise?color=lightblue\u0026logo=github)](https://github.com/KEINOS/go-noise/issues \"Opened issues\")\n[![PR](https://img.shields.io/github/issues-pr/KEINOS/go-noise?color=lightblue\u0026logo=github)](https://github.com/KEINOS/go-noise/pulls \"Pull Requests\")\n\n- Pull Request:\n    - **Any PR for improvement is welcome!** We will merge it as soon as it passes the CIs and not a prank-kind implementation. ;-)\n    - PR Branch: `main`\n        - 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!\n    - CI/CD: [Github Actions](./.github/workflows)\n        - `go test ./...`\n        - `golangci-lint run`\n        - `golint ./...`\n        - Code coverage check: 100% of coverage.\n- Bug reports:\n    - [Issues](https://github.com/KEINOS/go-noise/issues)\n    - If possible, please attach a simple reproduction code sample of the error. PRs for the fixes are much appreciated. 🙏\n\n### Statuses\n\n[![go1.17+](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/go-versions.yml \"This package supports Go 1.17 or later\")\n[![PlatformTests](https://github.com/KEINOS/go-noise/actions/workflows/platform-test.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/platform-test.yml \"Tests on Linux, macOS, Windows platforms\")\n[![golangci-lint](https://github.com/KEINOS/go-noise/actions/workflows/golangci-lint.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/golangci-lint.yml \"Static analysis and lint check by golangci-lint\")\n[![CodeQL](https://github.com/KEINOS/go-noise/actions/workflows/codeQL-analysis.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/codeQL-analysis.yml \"Security and vulnerability analysis by CodeQL\")\n[![codecov](https://codecov.io/gh/KEINOS/go-noise/branch/main/graph/badge.svg?token=cFoXdcwtaj)](https://codecov.io/gh/KEINOS/go-noise \"Code coverage\")\n[![Go Report Card](https://goreportcard.com/badge/github.com/KEINOS/go-noise)](https://goreportcard.com/report/github.com/KEINOS/go-noise \"Code quality\")\n[![Weekly Update](https://github.com/KEINOS/go-noise/actions/workflows/weekly-update.yml/badge.svg)](https://github.com/KEINOS/go-noise/actions/workflows/weekly-update.yml \"Update go.mod to latest version\")\n\n### License\n\n- [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).\n    - [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).\n    - [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).\n    - Other Go modules used in this package: [go.mod](https://github.com/KEINOS/go-noise/blob/main/go.mod)\n- [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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeinos%2Fgo-noise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeinos%2Fgo-noise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeinos%2Fgo-noise/lists"}