Merge pull request #1 from KEINOS/feat-custom-generator

Feat: custom generator ( enable user-defined function)

Author: KEINOS

.github/Dockerfile

@@ -10,7 +10,8 @@ ARG VARIANT="1.17-alpine"
 FROM golang:${VARIANT}
 
 RUN apk add --no-cache \
-    git \
+    mesa-dev \
+    pkgconfig \
     alpine-sdk \
     build-base
 

.github/go-mod-tidy.sh

@@ -13,7 +13,7 @@
 
 set -eu
 
-echo '* Current Go version:' $(go version)
+echo '* Current Go version:' "$(go version)"
 
 echo '* Backup modules ...'
 mv go.mod go.mod.bak
@@ -27,6 +27,7 @@ go get "github.com/aquilax/go-perlin"
 go get "github.com/ojrac/opensimplex-go"
 go get "github.com/pkg/errors"
 go get "github.com/stretchr/testify"
+go get "gonum.org/v1/plot/..."
 
 echo '* Run go tidy ...'
 go mod tidy

README.md

@@ -17,8 +17,10 @@ In the example below, 1 dimmentional method `noise.Generator.Eval64(x)` was used
 // const seed = 100       // noise pattern ID
 // const smoothness = 100 // noise smoothness
 //
+// // noiseType choises
 // noiseType := noise.Perlin
 // noiseType := noise.OpenSimplex
+// noiseType := noise.Custom
 n, err := noise.New(noiseType, seed)
 
 yy := n.Eval64(x / smoothness) // yy is between -1.0 and 1.0 of float64
@@ -27,6 +29,7 @@ y := (yy + 1) / 2 * 500        // y is between 0 and 500
 
 ![](./_example/2d/2d_perlin.png)
 ![](./_example/2d/2d_opensimplex.png)
+![](./_example/2d/2d_pseudorandom.png)
 
 - [Source](./_example/2d)
 
@@ -84,6 +87,10 @@ go get "github.com/KEINOS/go-noise"
 
 ### Constructor
 
+```go
+noise.New(noiseType noise.Algo, seed int64) (noise.Generator, error)
+```
+
 ```go
 import "github.com/KEINOS/go-noise"
 
@@ -204,8 +211,8 @@ for z := 0; z < frame; z++ {
 
 ### 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 2019- [Evgeniy Vasilev and his contributors](https://github.com/aquilax/go-perlin/graphs/contributors).
+- [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).
 - [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).
 - Go modules used in this package: [go.mod](https://github.com/KEINOS/go-noise/blob/main/go.mod)

_example/2d/2d_pseudorandom.png

@@ -2,6 +2,7 @@ package main
 
 import (
 	"log"
+	"math/rand"
 
 	"github.com/KEINOS/go-noise"
 	"gonum.org/v1/plot"
@@ -25,6 +26,13 @@ const (
 	smoothness = 100
 )
 
+// rnd is the rand.Rand used by PseudoRrandom() which is the Custom noise generator.
+var rnd *rand.Rand
+
+// ----------------------------------------------------------------------------
+//  Main
+// ----------------------------------------------------------------------------
+
 func main() {
 	{
 		// Create Perlin noise generator with seed 100.
@@ -53,11 +61,34 @@ func main() {
 			log.Fatal(err)
 		}
 	}
+
+	{
+		// Create user-defined Pseudorandom noise generator with seed 100.
+		gen, err := noise.New(noise.Custom, seed)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// Set user-defined noise function.
+		if err := gen.SetEval64(PseudoRrandom); err != nil {
+			log.Fatal(err)
+		}
+
+		pathFile := "./2d_pseudorandom.png"
+
+		if err := GenGraphImage(gen, "User Custom Noise (Pseudo Random)", pathFile); err != nil {
+			log.Fatal(err)
+		}
+	}
 }
 
+// ----------------------------------------------------------------------------
+//  Functions
+// ----------------------------------------------------------------------------
+
 // GenGraphImage generates a graph image with the specified generator and saves
 // it to the specified path.
-func GenGraphImage(gen noise.Noise, title string, pathFile string) error {
+func GenGraphImage(gen noise.Generator, title string, pathFile string) error {
 	// Create plotter.
 	pltr := GenPlotter(title)
 
@@ -103,3 +134,25 @@ func GenPlotter(titile string) *plot.Plot {
 func Normalize(v float64) float64 {
 	return (v + 1) / 2 * float64(height)
 }
+
+// PseudoRrandom is a pseudo-random noise function for use as a user-defined
+// noise generator for the Eval64 method.
+func PseudoRrandom(seed int64, dim ...float64) float64 {
+	if rnd == nil {
+		// Set the seed.
+		rnd = rand.New(rand.NewSource(seed))
+	}
+
+	for i := 0; i < len(dim); i++ {
+		v := int(dim[i])
+
+		for ii := 0; ii < v; ii++ {
+			//nolint:gosec // Use of weak random number generation is intended for simple examples.
+			_ = rnd.Float64()
+		}
+	}
+
+	s := rnd.Float64() // 0.0 - 0.9999...
+
+	return s*2 - 1 // Convert [0.0,1.0) to [-1.0,1.0]
+}

_example/2d/main.go

@@ -31,6 +31,56 @@ func ExampleNew() {
 	}
 }
 
+// ----------------------------------------------------------------------------
+//  Custom Noise (User-Defind Fucntion)
+// ----------------------------------------------------------------------------
+
+func ExampleNew_assign_user_defined_function() {
+	const seed = 100
+
+	// Create a noise generator.
+	gen, err := noise.New(noise.Custom, seed)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// rnd is a random number generator.
+	var rnd *rand.Rand
+
+	// Define user function to generate custom noise.
+	// Here we define a function that returns a pseudo-random value from the
+	// given seed and itereate 'dim' times.
+	myFunc := func(seed int64, dim ...float32) float32 {
+		if rnd == nil {
+			//nolint:gosec // Use of weak random number generation is intended here.
+			rnd = rand.New(rand.NewSource(seed))
+		}
+
+		for i := 0; i < len(dim); i++ {
+			max := int(dim[i])
+
+			for ii := 0; ii < max; ii++ {
+				_ = rnd.Float32()
+			}
+		}
+
+		// Generate a pseudo-random number.
+		v := rnd.Float32()
+
+		return v*2 - 1 // Convert [0.0,1.0] to [-1.0,1.0]
+	}
+
+	// Assign user-defined function
+	if err := gen.SetEval32(myFunc); err != nil {
+		log.Fatal(err)
+	}
+
+	// Get noise value at (1, 2, 3)
+	fmt.Println(gen.Eval32(1, 2, 3))
+
+	// Output: -0.1159181
+}
+
 // ----------------------------------------------------------------------------
 //  OpenSimplex Noise
 // ----------------------------------------------------------------------------

example_test.go

@@ -1,6 +1,7 @@
 package noise
 
 import (
+	"github.com/KEINOS/go-noise/pkg/custom"
 	"github.com/KEINOS/go-noise/pkg/opensimplex"
 	"github.com/KEINOS/go-noise/pkg/perlin"
 	"github.com/pkg/errors"
@@ -16,6 +17,8 @@ const (
 	Perlin
 	// OpenSimplex noise type.
 	OpenSimplex
+	// Custom uses the user-defined function to generate noise.
+	Custom
 )
 
 // ----------------------------------------------------------------------------
@@ -46,6 +49,8 @@ type Generator interface {
 	// Implementations of this method must return the same value if the seed
 	// value is the same.
 	Eval64(dim ...float64) float64
+	SetEval32(f func(seed int64, dim ...float32) float32) error
+	SetEval64(f func(seed int64, dim ...float64) float64) error
 }
 
 // ----------------------------------------------------------------------------
@@ -59,6 +64,8 @@ func New(noiseType Algo, seed int64) (Generator, error) {
 		return perlin.New(seed), nil
 	case OpenSimplex:
 		return opensimplex.New(seed), nil
+	case Custom:
+		return custom.New(seed), nil
 	}
 
 	return nil, errors.New("unknown noise type")

noise.go

@@ -0,0 +1,76 @@
+/*
+Package custom provides a noise generator using the user-defined function.
+Which implements github.com/KEINOS/go-noise/noise interface.
+
+You need to define the function before calling `Eval32` or `Eval64`.
+*/
+package custom
+
+import (
+	"math/rand"
+	"time"
+
+	"github.com/pkg/errors"
+)
+
+// Generator holds parameters of user-defined noise generator.
+type Generator struct {
+	// func32 is the user-defined function for float32.
+	func32 func(seed int64, dim ...float32) float32
+	// func64 is the user-defined function for float64.
+	func64 func(seed int64, dim ...float64) float64
+	// Seed holds the seed value for the noise.
+	Seed int64
+}
+
+// New returns a seeded Perlin noise instance.
+func New(seed int64) *Generator {
+	// Rand that uses random values from src to generate other random values.
+	return &Generator{
+		Seed: seed,
+	}
+}
+
+// Eval32 returns a float32 noise value using the user-defined function for the given coordinates.
+func (n *Generator) Eval32(dim ...float32) float32 {
+	return n.func32(n.Seed, dim...)
+}
+
+// Eval64 returns a float64 noise value using the user-defined function for the given coordinates.
+func (n *Generator) Eval64(dim ...float64) float64 {
+	return n.func64(n.Seed, dim...)
+}
+
+// SetEval32 sets the user-defined noise generator function for float32.
+func (n *Generator) SetEval32(f func(seed int64, dim ...float32) float32) error {
+	// Check the function.
+	rand.Seed(time.Now().UnixNano())
+
+	//nolint:gosec // Use of weak random number generation is intended here.
+	dummyInput := rand.Float32()
+
+	if v := f(n.Seed, dummyInput, dummyInput); v <= -1 || 1 < v {
+		return errors.New("the function must return a value between -1 and 1")
+	}
+
+	n.func32 = f
+
+	return nil
+}
+
+// SetEval64 sets the user-defined noise generator function for float64.
+func (n *Generator) SetEval64(f func(seed int64, dim ...float64) float64) error {
+	// Check the function.
+	rand.Seed(time.Now().UnixNano())
+
+	//nolint:gosec // Use of weak random number generation is intended here.
+	dummyInput := rand.Float64()
+
+	if v := f(n.Seed, dummyInput, dummyInput); v <= -1 || 1 < v {
+		return errors.New("the function must return a value between -1 and 1")
+	}
+
+	n.func64 = f
+
+	return nil
+}

pkg/custom/custom.go

@@ -0,0 +1,46 @@
+package custom
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEval32_no_function_assigned(t *testing.T) {
+	gen := New(12345)
+
+	require.Panics(t, func() {
+		_ = gen.Eval32(1.0, 2.0, 3.0)
+	}, "if the function is not assigned, it should panic")
+}
+
+func TestEval64_no_function_assigned(t *testing.T) {
+	gen := New(12345)
+
+	require.Panics(t, func() {
+		_ = gen.Eval64(1.0, 2.0, 3.0)
+	}, "if the function is not assigned, it should panic")
+}
+
+func TestSetEval32_function_returns_out_of_range(t *testing.T) {
+	gen := New(12345)
+
+	err := gen.SetEval32(func(seed int64, dim ...float32) float32 {
+		return -2.0
+	})
+
+	require.Error(t, err, "if the function returns a value out of range, an error should be returned")
+	assert.Contains(t, err.Error(), "the function must return a value between -1 and 1")
+}
+
+func TestSetEval64_function_returns_out_of_range(t *testing.T) {
+	gen := New(12345)
+
+	err := gen.SetEval64(func(seed int64, dim ...float64) float64 {
+		return -2.0
+	})
+
+	require.Error(t, err, "if the function returns a value out of range, an error should be returned")
+	assert.Contains(t, err.Error(), "the function must return a value between -1 and 1")
+}