#### <sup>:closed_book: [canvas-sketch-util](../README.md) → [Documentation](./README.md) → `random`</sup>

---

### `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

```js
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

- [createRandom](#createRandom)
- [value](#value)
- [setSeed](#setSeed)
- [getSeed](#getSeed)
- [getRandomSeed](#getRandomSeed)
- [valueNonZero](#valueNonZero)
- [noise1D](#noise1D)
- [noise2D](#noise2D)
- [noise3D](#noise3D)
- [noise4D](#noise4D)
- [permuteNoise](#permuteNoise)
- [sign](#sign)
- [boolean](#boolean)
- [chance](#chance)
- [range](#range)
- [rangeFloor](#rangeFloor)
- [gaussian](#gaussian)
- [pick](#pick)
- [shuffle](#shuffle)
- [onCircle](#onCircle)
- [insideCircle](#insideCircle)
- [onSphere](#onSphere)
- [insideSphere](#insideSphere)
- [quaternion](#quaternion)
- [weighted](#weighted)
- [weightedSet](#weightedSet)
- [weightedSetIndex](#weightedSetIndex)

<a name="createRandom"></a>

### `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.

<a name="value"></a>

### `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.

<a name="setSeed"></a>

### `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()`.

<a name="getSeed"></a>

### `seed = random.getSeed()`

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

<a name="getRandomSeed"></a>

### `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:

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

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

<a name="valueNonZero"></a>

### `v = random.valueNonZero()`

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

<a name="noise1D"></a>

### `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.

<a name="noise2D"></a>

### `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.

<a name="noise3D"></a>

### `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.

<a name="noise4D"></a>

### `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.

<a name="permuteNoise"></a>

### `random.permuteNoise()`

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

<a name="sign"></a>

### `random.sign()`

Uniformly produce either `1` or `-1` values.

<a name="boolean"></a>

### `random.boolean()`

Uniformly produce either `true` or `false` values.

<a name="chance"></a>

### `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()`.

<a name="range"></a>

### `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`.

<a name="rangeFloor"></a>

### `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`.

<a name="gaussian"></a>

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

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

<a name="pick"></a>

### `random.pick(array)`

Picks a random element from the specified array.

<a name="shuffle"></a>

### `shuffled = random.shuffle(array)`

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

<a name="onCircle"></a>

### `[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.

<a name="insideCircle"></a>

### `[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.

<a name="onSphere"></a>

### `[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.

<a name="insideSphere"></a>

### `[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.

<a name="quaternion"></a>

### `[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.

<a name="weighted"></a>

### `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.

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

<a name="weightedSet"></a>

### `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:

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

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

<a name="weightedSetIndex"></a>

### `index = random.weightedSetIndex(set)`

Similar to [weightedSet](#weightedSet), but returns the index of the element within the array, rather than the value.

## 

#### <sup>[← Back to Documentation](./README.md)