Namespace: utility

syngen.utility

A collection of useful utility methods.

Source:

Interfaces

bitree
euler
machine
octree
perlin1d
perlin2d
perlin3d
perlin4d
pubsub
quadtree
quaternion
simplex2d
simplex3d
simplex4d
vector2d
vector3d

Mixins

physical

Namespaces

random
timing

Methods

(static) addInterval(frequency, interval)

Adds a musical interval to a frequency, in Hertz.

Parameters:
Name Type Description
frequency Number
interval Number

Each integer multiple represents an octave. For example, 2 raises the frequency by two octaves. Likewise, -1/12 lowers by one half-step, whereas -1/100 lowers by one cent.
Source:

(static) between(value, min, max) → {Boolean}

Returns whether value is between min and max (inclusive).

Parameters:
Name Type Description
value Number
min Number
max Number
Source:
Returns:
Type
Boolean

(static) centroid(vectors) → {syngen.utility.vector3d}

Calculates the geometric center of variadic vectors or vector-likes.

Parameters:
Name Type Description
vectors Array.<syngen.utility.vector3d> | Array.<syngen.utility.vector2d> | Array.<Object>
Source:
Returns:
Type
syngen.utility.vector3d

(static) choose(options, valueopt) → {*}

Returns the element of options at the index determined by percentage value.

Parameters:
Name Type Attributes Default Description
options Array
value Number <optional>
 0

Float within [0, 1].
Source:
Returns:
Type
*

(static) chooseSplice(options, valueopt) → {*}

Splices and returns the element of options at the index determined by percentage value. Beward that this mutates the passed array.

Parameters:
Name Type Attributes Default Description
options Array
value Number <optional>
 0

Float within [0, 1].
Source:
Returns:
Type
*

(static) chooseWeighted(options, valueopt) → {*}

Returns the element of options at the index determined by weighted percentage value.

Parameters:
Name Type Attributes Default Description
options Array

Each element is expected to have a weight key which is a positive number. Higher weights are more likely to be chosen. Beware that elements are not sorted by weight before selection.
value Number <optional>
 0

Float within [0, 1].
Source:
Returns:
Type
*

(static) clamp(value, min, max) → {Number}

Returns value clamped between min and max.

Parameters:
Name Type Description
value Number
min Number
max Number
Source:
Returns:
Type
Number

(static) closer(x, a, b) → {Number}

Returns whichever value, a or b, that is closer to x.

Parameters:
Name Type Description
x Number
a Number
b Number
Source:
Returns:
Type
Number

(static) closest(x, values) → {Number}

Returns the closest value to x in the array values.

Parameters:
Name Type Description
x Number
values Array.<Number>
Source:
To Do:
  • Improve performance with a version for pre-sorted arrays
Returns:
Type
Number

(static) createNoiseWithOctaves(options) → {Object}

Instantiates octaves noise generators of type with seed and returns a wrapper object that calculates their combined values.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
octaves Number <optional>
 2
seed *
type syngen.utility.perlin1d | syngen.utility.perlin2d | syngen.utility.perlin3d | syngen.utility.perlin4d | syngen.utility.simplex2d | syngen.utility.simplex3d | syngen.utility.simplex4d

Must be reference to a noise utility, and not a factory method or an instance.
Source:
To Do:
  • Port into individual noise utilities for clarity and simplicity
Returns:
Type
Object

(static) createPerlinWithOctaves(type, seed, octavesopt) → {Object}

Instantiates octaves noise generators of type with seed and returns a wrapper object that calculates their combined values.

Parameters:
Name Type Attributes Default Description
type syngen.utility.perlin1d | syngen.utility.perlin2d | syngen.utility.perlin3d | syngen.utility.perlin4d | syngen.utility.simplex2d | syngen.utility.simplex3d | syngen.utility.simplex4d

Must be reference to a noise utility, and not a factory method or an instance.
seed *
octaves Number <optional>
 2
Deprecated:
Source:
Returns:
Type
Object

(static) degreesToRadians(degrees) → {Number}

Converts degrees to radians.

Parameters:
Name Type Description
degrees Number
Source:
Returns:
Type
Number

(static) detune(frequency, centsopt) → {Number}

Adds a musical interval to frequency in cents.

Parameters:
Name Type Attributes Default Description
frequency Number
cents Number <optional>
 0

Every 1200 represents an octave. For example, 2400 raises the frequency by two octaves. Likewise, -100 lowers by one half-step, whereas -1 lowers by one cent.
Source:
Returns:
Type
Number

(static) distance(a, b) → {Number}

Calculates the distance between two vectors or vector-likes.

Parameters:
Name Type Description
a syngen.utility.vector2d | syngen.utility.vector3d | Object
b syngen.utility.vector2d | syngen.utility.vector3d | Object
Source:
Returns:
Type
Number

(static) distance2(a, b) → {Number}

Calculates the squared distance between two vectors or vector-likes.

Parameters:
Name Type Description
a syngen.utility.vector2d | syngen.utility.vector3d | Object
b syngen.utility.vector2d | syngen.utility.vector3d | Object
Source:
Returns:
Type
Number

(static) distanceToPower(distanceopt) → {Number}

Calculated the gain for a sound source distance meters away, normalized to zero decibels. The distance model is determined by the values of several constants. Importantly, it is a combination of inverse-squared and linear functions.

Parameters:
Name Type Attributes Default Description
distance Number <optional>
 0
Source:
See:
To Do:
  • Move to dedicated distance models
Returns:
Type
Number

(static) frequencyToMidi(frequency) → {Number}

Converts frequency, in Hertz, to its corresponding MIDI note number. The returned value is not rounded.

Parameters:
Name Type Description
frequency Number
Source:
See:
Returns:
Type
Number

(static) fromDb(decibels) → {Number}

Converts decibels to its equivalent gain value.

Parameters:
Name Type Description
decibels Number
Source:
Returns:
Type
Number

(static) hash(value) → {Number}

Converts value to an integer via the Jenkins hash function.

Parameters:
Name Type Description
value String
Source:
Returns:
Type
Number

(static) humanize(baseValue, amount) → {Number}

Adds a random value to baseValue within the range of negative to positive amount.

Parameters:
Name Type Description
baseValue Number
amount Number
Source:
Returns:
Type
Number

(static) humanizeDb(baseGain, decibels) → {Number}

Adds a random gain to baseGain within the range of negative to positive decibels, first converted to gain.

Parameters:
Name Type Description
baseGain Number
decibels Number
Source:
Returns:
Type
Number

(static) intersects(a, b) → {Boolean}

Returns whether rectangular prisms a and b intersect. A rectangular prism has a bottom-left vertex with coordinates (x, y, z) and width, height, and depth along those axes respectively. An intersection occurs if their faces intersect, they share vertices, or one is contained within the other. This function works for one- and two-dimensional shapes as well.

Parameters:
Name Type Description
a Object
b Object
Source:
To Do:
  • Define a rectangular prism utility or type
Returns:
Type
Boolean

(static) lerp(min, max, valueopt) → {Number}

Linearly interpolates between min and max with value.

Parameters:
Name Type Attributes Default Description
min Number
max Number
value Number <optional>
 0

Float within [0, 1].
Source:
Returns:
Type
Number

(static) lerpExp(min, max, valueopt, poweropt) → {Number}

Linearly interpolates between min and max with value raised to power.

Parameters:
Name Type Attributes Default Description
min Number
max Number
value Number <optional>
 0

Float within [0, 1].
power Number <optional>
 2
Source:
Returns:
Type
Number

(static) lerpExpRandom(lowRange, highRange, valueopt, poweropt) → {Number}

Returns a random value within the range where the lower bound is the interpolated value within [lowMin, highMin], the upper bound is the interpolated value within [lowMax, highMax]. Values are interpolated with lerpExpRandom.

Parameters:
Name Type Attributes Description
lowRange Array.<Number>

Expects [lowMin, lowMax].
highRange Array.<Number>

Expects [highMin, highMax].
value Number <optional>
power Number <optional>
Source:
See:
Returns:
Type
Number

(static) lerpLog(min, max, valueopt, baseopt) → {Number}

Linearly interpolates between min and max with value logarithmically with base.

Parameters:
Name Type Attributes Default Description
min Number
max Number
value Number <optional>
 0

Float within [0, 1].
base Number <optional>
 2
Source:
Returns:
Type
Number

(static) lerpLogi(min, max, valueopt, baseopt) → {Number}

Linearly interpolates between min and max with value logarithmically with base. This function is shorthand for lerpLog(min, max, 1 - value, 1 / base) which results in curve that inversely favors larger values. This is similar to but distinct from lerpExp.

Parameters:
Name Type Attributes Default Description
min Number
max Number
value Number <optional>
 0

Float within [0, 1].
base Number <optional>
 2
Source:
See:
Returns:
Type
Number

(static) lerpLogiRandom(lowRange, highRange, valueopt, poweropt) → {Number}

Returns a random value within the range where the lower bound is the interpolated value within [lowMin, highMin], the upper bound is the interpolated value within [lowMax, highMax]. Values are interpolated with lerpLogi.

Parameters:
Name Type Attributes Description
lowRange Array.<Number>

Expects [lowMin, lowMax].
highRange Array.<Number>

Expects [highMin, highMax].
value Number <optional>
power Number <optional>
Source:
See:
Returns:
Type
Number

(static) lerpLogRandom(lowRange, highRange, valueopt, baseopt) → {Number}

Returns a random value within the range where the lower bound is the interpolated value within [lowMin, highMin], the upper bound is the interpolated value within [lowMax, highMax]. Values are interpolated with lerpLog.

Parameters:
Name Type Attributes Description
lowRange Array.<Number>

Expects [lowMin, lowMax].
highRange Array.<Number>

Expects [highMin, highMax].
value Number <optional>
base Number <optional>
Source:
See:
Returns:
Type
Number

(static) lerpRandom(lowRange, highRange, valueopt, baseopt) → {Number}

Returns a random value within the range where the lower bound is the interpolated value within [lowMin, highMin], the upper bound is the interpolated value within [lowMax, highMax]. Values are interpolated with lerp.

Parameters:
Name Type Attributes Description
lowRange Array.<Number>

Expects [lowMin, lowMax].
highRange Array.<Number>

Expects [highMin, highMax].
value Number <optional>
base Number <optional>
Source:
See:
Returns:
Type
Number

(static) midiToFrequency(note) → {Number}

Converts a MIDI note number to its frequency, in Hertz.

Parameters:
Name Type Description
note Number
Source:
See:
Returns:
Type
Number

(static) normalizeAngle(angle) → {Number}

Normalizes angle within therange of [0, 2π].

Parameters:
Name Type Description
angle Number
Source:
Returns:
Type
Number

(static) normalizeAngleSigned(angle) → {Number}

Normalizes angle within the range of [-π, +π].

Parameters:
Name Type Description
angle Number
Source:
Returns:
Type
Number

(static) quadratic(a, b, c) → {Array.<Number>}

Calculates the real solutions to the quadratic equation with coefficients a, b, and c.

Parameters:
Name Type Description
a Number
b Number
c Number
Source:
Returns:

Typically there are two real solutions; however, implementations must check for imaginary solutions with isNaN.

Type
Array.<Number>

(static) radiansToDegrees(radians) → {Number}

Converts radians to degrees.

Parameters:
Name Type Description
radians Number
Source:
Returns:
Type
Number

(static) regularPolygonInteriorAngle(sides) → {Number}

Calculates the interior angle of a regular polygon with sides.

Parameters:
Name Type Description
sides Number
Source:
Returns:
Type
Number

(static) round(value, precision) → {Number}

Rounds value to precision places. Beward that precision is an inverse power of ten. For example, 3 rounds to the nearest thousandth, whereas -3 rounds to the nearest thousand.

Parameters:
Name Type Description
value Number
precision Number
Source:
Returns:
Type
Number

(static) scale(value, min, max, a, b) → {Number}

Scales value within the range [min, max] to an equivalent value between [a, b].

Parameters:
Name Type Description
value Number
min Number
max Number
a Number
b Number
Source:
Returns:
Type
Number

(static) shuffle(array, randomopt)

Returns a shuffled shallow copy of array using random algorithm. For example, implementations could leverage srand() to produce the same results each time given the same seed value.

Parameters:
Name Type Attributes Default Description
array Array
random function <optional>
 Math.random
Source:

(static) sign(value) → {Number}

Returns the sign of value as positive or negative 1.

Parameters:
Name Type Description
value Number
Source:
Returns:
Type
Number

(static) srand() → {syngen.utility.srandGenerator}

Returns a pseudo-random, linear congruential, seeded random number generator with variadic seeds. Seeds are prepended with the global syngen.seed and concatenated with syngen.const.seedSeparator.

Parameters:
Name Type Attributes Description
...seeds String <optional>
<repeatable>
Source:
Returns:
Type
syngen.utility.srandGenerator

(static) toCents(a, b) → {Number}

Calculates the musical interval between two frequencies, in cents.

Parameters:
Name Type Description
a Number
b Number
Source:
Returns:
Type
Number

(static) toDb(gain) → {Number}

Converts gain to its equivalent decibel value.

Parameters:
Name Type Description
gain Number
Source:
Returns:
Type
Number

(static) toSubFrequency(frequency, subFrequencyopt, minFrequencyopt) → {Number}

Scales frequency by integer multiples so it's an audible frequency within the sub-bass range.

Parameters:
Name Type Attributes Default Description
frequency Number
subFrequency Number <optional>
 syngen.const.subFrequency
minFrequency Number <optional>
 syngen.const.minFrequency
Source:
Returns:
Type
Number

(static) uuid() → {String}

Generates a universally unique identifier.

Source:
Returns:
Type
String

(static) wrap(value, minopt, maxopt) → {Number}

Wraps value around the range [min, max) with modular arithmetic. Beware that min is congruent to max, so returned values will approach the limit of max before wrapping back to min. A way to visualize this operation is that the range repeats along the number line.

Parameters:
Name Type Attributes Default Description
value Number
min Number <optional>
 0
max Number <optional>
 1
Source:
Returns:
Type
Number

(static) wrapAlternate(value, minopt, maxopt) → {Number}

Maps value to an alternating oscillation of the range [min, max]. A way to visualize this operation is that the range repeats alternately along the number line, such that min goes to max back to min.

Parameters:
Name Type Attributes Default Description
value Number
min Number <optional>
 0
max Number <optional>
 1
Source:
Returns:
Type
Number

Type Definitions

srandGenerator(minopt, maxopt) → {Number}

A pseudo-random, linear congruential, seeded random number generator that returns a value within [min, max].

Parameters:
Name Type Attributes Default Description
min Number <optional>
 0
max Number <optional>
 1
Source:
Returns:
Type
Number