Skip to content

Latest commit

 

History

History
259 lines (152 loc) · 8.4 KB

random.md

File metadata and controls

259 lines (152 loc) · 8.4 KB
Raw

📕 canvas-sketch-util → Documentation → random

canvas-sketch-util/random

A singleton utility to produce randomness; such as random numbers, vectors, rotations, etc.

By default, random values are not deterministic, but if you set a seed with setSeed, all values returned from these functions will be deterministic and reproducible.

Example

const random = require('canvas-sketch-util/random');

// Random betwee 0 (inclusive) and 1 (exclusive)
const r = random.value();

// Random 2D point on unit circle
const [ x, y ] = random.onCircle();

Functions

instance = random.createRandom(defaultSeed)

Instead of using the singleton (which may have its seed polluted by another module), you can create a self-contained instance of the random utility with createRandom, optionally passing a seed to produce deterministic randomness. If no seed is used, then the default Math.random() function will be used under the hood.

The return value has all the same functions as the random module.

v = random.value()

Produce a random value between 0 (inclusive) and 1 (exclusive). This is functionally equivalent to Math.random(), except in the case that a seed has been set on the singleton, in which case a detemrinistic result is produced.

All other utilities will use this function under the hood.

random.setSeed(n)

Forces this random generator instance to use the seed n, which can be a number or string type. After setting the seed, all future random numbers will have a deterministic result based on this seed.

If you specify a falsey value, the seed will be cleared from the instance and non-deterministic randomness will return via Math.random().

seed = random.getSeed()

Returns the current seed of this random generator instance, or undefined if none is set.

seed = random.getRandomSeed()

Produces a non-determinstic random seed, a floored integer between 0 and 1000000 which is then turned into a string. Unlike other functions, this always uses Math.random() and is never based on the internal seed.

Useful to set an initial random seed, like so:

// Set an initial random seed
random.setSeed(random.getRandomSeed());

// Log it for later reproducibility
console.log('Random seed: %s', random.getSeed());

v = random.valueNonZero()

Produce a random value between 0 (exlusive) and 1 (exclusive).

n = random.noise1D(x, frequency = 1, amplitude = 1)

Produces 1-dimensional random simplex noise with the simplex-noise module. This is equivalent to noise2D(x, 0).

Optionally you can specify the frequency (which multiplies all coordinates by that value) and amplitude (which multiplies the output result by that value) of the noise signal.

n = random.noise2D(x, y, frequency = 1, amplitude = 1)

Produces 2-dimensional random simplex noise with the simplex-noise module.

Optionally you can specify the frequency (which multiplies all coordinates by that value) and amplitude (which multiplies the output result by that value) of the noise signal.

n = random.noise3D(x, y, z, frequency = 1, amplitude = 1)

Produces 3-dimensional random simplex noise with the simplex-noise module.

Optionally you can specify the frequency (which multiplies all coordinates by that value) and amplitude (which multiplies the output result by that value) of the noise signal.

n = random.noise4D(x, y, z, w, frequency = 1, amplitude = 1)

Produces 4-dimensional random simplex noise with the simplex-noise module.

Optionally you can specify the frequency (which multiplies all coordinates by that value) and amplitude (which multiplies the output result by that value) of the noise signal.

random.permuteNoise()

Re-computes the noise tables so that future calls to noiseND() will have different values.

random.sign()

Uniformly produce either 1 or -1 values.

random.boolean()

Uniformly produce either true or false values.

random.chance(probability = 0.5)

Produce random true or false values based on the given probability, where the closer it is to 1 the more likely you will get true, and the closer to 0 the more likely you will get false. The default probability is 0.5, which is functionally equivalent to random.boolean().

random.range(min, max)

Produces a random float value between min (inclusive) and max (exclusive). If only one argument is provided, the min is defaulted to 0, and that argument is used as the max.

random.rangeFloor(min, max)

Produces a random integer value between min integer (inclusive) and max integer (exclusive). If only one argument is provided, the min is defaulted to 0, and that argument is used as the max.

v = random.gaussian(mean = 0, std = 1)

Produces a random Gaussian distribution using mean and std for standard deviation.

random.pick(array)

Picks a random element from the specified array.

shuffled = random.shuffle(array)

Shallow copies the array, returning a randomly shuffled result. Does not modify the array in place.

[x, y] = random.onCircle(radius = 1, out = [])

Produces a random 2D point around the perimiter of a unit circle, optionally scaled to radius. You can pass an existing out array to re-use, instead of creating a new array.

[x, y] = random.insideCircle(radius = 1, out = [])

Produces a random 2D point inside a unit circle, optionally scaled to radius. You can pass an existing out array to re-use, instead of creating a new array.

[x, y, z] = random.onSphere(radius = 1, out = [])

Produces a random 3D point on the surface of a unit sphere, optionally scaled to radius. You can pass an existing out array to re-use, instead of creating a new array.

[x, y, z] = random.insideSphere(radius = 1, out = [])

Produces a random 3D point within a unit sphere, optionally scaled to radius. You can pass an existing out array to re-use, instead of creating a new array.

[x, y, z, w] = random.quaternion(out = [])

Produces a random 4D quaternion rotation. You can pass an existing out array to re-use, instead of creating a new array.

index = random.weighted(weights)

Returns a random index, selected from an array of weights. This allows you to produce weighted randomness, for example weighing the results toward a specific element in an array. Higher numbers are more likely to get picked than lower numbers.

const weights = [ 0, 2500, 10 ];
const index = random.weighted(weights);
// likely to produce index=1

value = random.weightedSet(set)

A utility to produce a value from a "set" of weighted objects.

The objects must have the format { value, weight } like so:

const colors = [
  { value: 'red', weight: 200 },
  { value: '#ff0000', weight: 50 }
];

const color = random.weightedSet(colors);
element.style.background = color;

index = random.weightedSetIndex(set)

Similar to weightedSet, but returns the index of the element within the array, rather than the value.

← Back to Documentation