VEGAS JS Namespace: maths

The core.maths package is a modular JavaScript library that provides extra mathematics methods and implementations.

Author:

Marc Alcaraz

License:

MPL 2.0 / GPL 2.0 / LGPL 2.1

Members

<constant> DEG2RAD

This constant change degrees to radians : Math.PI/180.

<constant> EARTH_RADIUS_IN_METERS

This constant defines the radius of the earth in meter : 6371 km.

<constant> EPSILON

Represents the smallest positive Single value greater than zero, EPSILON=0.000000001.

<constant> LAMBDA

This constant is the Euler-Mascheroni constant (lambda or C) :

( n )
lim( sigma 1/k - ln(n) )
n->oo ( k=1 )

<constant> littleEndian :boolean

This constant indicates if the device big or little endian and detected if the browser supports TypedArrays.

Type:

boolean

<constant> MILE_TO_METER

This constant change mile distance to meter : 1 mile = 1609 m.

<constant> PHI

The golden ratio (phi) : ( 1 + Math.sqrt(5) ) / 2.

<constant> PI2

This constant equal Math.PI*2.

Default Value:

Math.PI * 2

<constant> RAD2DEG

This constant change radians to degrees : 180/Math.PI.

Methods

acosD(ratio)

Returns the inverse cosine of a slope ratio and returns its angle in degrees.

Parameters:

Name	Type	Description
`ratio`	number	A value between -1 and 1 inclusive.

Returns:

the inverse cosine of a slope ratio and returns its angle in degrees.

acosHm(x)

Anti-hyperbolic cosine : acoshm = ln(x-√(x^2-1))

Parameters:

Name	Type	Description
`x`	number	A value to calculate the Anti-hyperbolic cosine.

acosHp()

Anti-hyperbolic cosine.

acoshp = ln(x+√(x^2-1))

angleOfLine(x1, y1, x2, y2)

Returns the angle in degrees between 2 points with this coordinates passed in argument.

Parameters:

Name	Type	Description
`x1`	number	The x coordinate of the first point.
`y1`	number	The y coordinate of the first point.
`x2`	number	The x coordinate of the second point.
`y2`	number	The y coordinate of the second point.

Returns:

the angle in degrees between 2 points with this coordinates passed in argument.

asinD(ratio)

Calculates the arcsine of the passed angle.

Parameters:

Name	Type	Description
`ratio`	number	A value between `-1` and `1` inclusive.

Returns:

the arcsine of the passed angle in degrees.

asinH()

Anti-hyperbolic sine.

atan2D(y, x)

Calculates the arctangent2 of the passed angle.

Parameters:

Name	Type	Description
`y`	number	A value representing y-axis of angle vector.
`x`	number	A value representing x-axis of angle vector.

Returns:

the arctangent2 of the passed angle.

atanD(angle)

Calculates the arctangent of the passed angle.

Parameters:

Name	Type	Description
`angle`	number	A real number

Returns:

the arctangent of the passed angle, a number between -Math.PI/2 and Math.PI/2 inclusive.

atanH(x)

Anti-hyperbolic tangent.

Parameters:

Name	Type	Description
`x`	number	A real number

Returns:

the Anti-hyperbolic tangent of the passed angle.

bearing(latitude1, longitude1, latitude2, longitude2)

Calculates the initial bearing (sometimes referred to as forward azimuth) which if followed in a straight line along a great-circle arc will take you from the start point to the end point (in degrees).

Parameters:

Name	Type	Description
`latitude1`	number	The first latitude coordinate.
`longitude1`	number	The first longitude coordinate.
`latitude2`	number	The second latitude coordinate.
`longitude2`	number	The second longitude coordinate.

Returns:

The bearing in degrees from North.

Example

var position1 = { x : 37.422045 , y : -122.084347 } ; // Google HQ
var position2 = { x :  37.77493 , y : -122.419416 } ; // San Francisco, CA
trace( bearing( position1.x , position1.y , position2.x , position2.y ) ) ; // 323.1477743368166

berp(start, end, amount)

Short for 'boing-like interpolation', this method will first overshoot, then waver back and forth around the end value before coming to a rest.

Parameters:

Name	Type	Description
`start`	number	The begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( berp( 0 , 100 , 0.5 ) ; // 105.1015801865505

bounce(amount)

Returns a value between 0 and 1 that can be used to easily make bouncing GUI items (a la OS X's Dock)

Parameters:

Name	Type	Description
`amount`	number	The amount to bounce a value between 0 and 1.

Returns:

a value between 0 and 1 that can be used to easily make bouncing GUI items (a la OS X's Dock)

Example

trace( bounce( 0.5 ) ) ;

cartesianToPolar(vector, degrees)

Converts a vector in cartesian in a polar vector. Return a generic object with the properties angle and radius.

Parameters:

Name	Type	Description
`vector`	graphics.geom.Vector2 \| graphics.geom.Point \| Objectj	The cartesian vector to transform.
`degrees`	boolean	Indicates if the angle attribute in the return polar object is in degrees or not (default this parameter is false).

Returns:

a vector in cartesian in a polar vector.

ceil(n [, floatCount])

Rounds and returns the ceiling of the specified number or expression. The ceiling of a number is the closest integer that is greater than or equal to the number.

Parameters:

Name	Type	Argument	Default	Description
`n`	number			The number to round.
`floatCount`	number	<optional>	0	the count of number after the point.

Returns:

the ceil value of a number by a count of floating points.

Example

trace(ceil(4.572525153, 2)) ; 4.58
trace(ceil(4.572525153, -1)) ; // 5

clamp(value, min, max)

Bounds a numeric value between 2 numbers.

Parameters:

Name	Type	Description
`value`	number	The value to clamp.
`min`	number	The min value of the range.
`max`	number	The max value of the range.

Returns:

a bound numeric value between 2 numbers.

Example

var n ;

n = core.maths.clamp(4, 5, 10) ;
trace ("n : " + n) ; // 5

n = core.maths.clamp(12, 5, 10) ;
trace ("n : " + n) ; // 10

n = core.maths.clamp(6, 5, 10) ;
trace ("n : " + n) ; // 5

n = core.maths.clamp(NaN, 5, 10) ;
trace ("n : " + n) ; // NaN

clerp(start, end, amount)

Circular Lerp is like lerp but handles the wraparound from 0 to 360. This is useful when interpolating eulerAngles and the object crosses the 0/360 boundary. The standard Lerp function causes the object to rotate in the wrong direction and looks stupid, clerp() fixes that.

Parameters:

Name	Type	Description
`start`	number	The begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( clerp( 0 , 180 , 0.5 ) ; // 90

cosD(angle)

Calculates the cosine of the passed angle.

Parameters:

Name	Type	Description
`angle`	number	A value representing angle in degrees.

Returns:

the cosine of the passed angle, a number between -1 and 1 inclusive.

coserp(start, end, amount)

Short for 'cosinusoidal interpolation', this method will interpolate while easing around the end, when value is near one.

Parameters:

Name	Type	Description
`start`	number	The begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( coserp( 0 , 100 , 0.5 ) ; // 29.28932188134524

cosH(x)

Hyperbolic cosine.

Parameters:

Name	Type	Description
`x`	number	A value to calculate the Hyperbolic cosine.

degreesToRadians(angle)

Converts degrees to radians.

Parameters:

Name	Type	Description
`angle`	number	Value, in degrees, to convert to radians.

Returns:

The angle in radians.

distance(x1, y1, x2, y2)

Calculates the distance between 2 points.

Parameters:

Name	Type	Description
`x1`	number	The x coordinate of the first point.
`y1`	number	The y coordinate of the first point.
`x2`	number	The x coordinate of the second point.
`y2`	number	The y coordinate of the second point.

Returns:

the length between 2 points.

distanceByObject(p1, p2)

Returns the distance between 2 points with the coordinates of the 2 points.

Parameters:

Name	Type	Description
`p1`	graphics.geom.Vector2 \| graphics.geom.Point \| Object	the first point to determinate the distance (defines with the x and y coordinates).
`p2`	graphics.geom.Vector2 \| graphics.geom.Point \| Object	the second point to determinate the distance (defines with the x and y coordinates).

Returns:

the length between 2 points.

factorial(value)

Calculates with the product of all positive integers less than or equal to value.

Parameters:

Name	Type	Description
`value`	number	The positive integer to limit the factorial equation.

Returns:

The product of all positive integers less than or equal to value.

Example

trace( factorial( 0 ) ) ; // 1
trace( factorial( 1 ) ) ; // 1
trace( factorial( 2 ) ) ; // 2
trace( factorial( 3 ) ) ; // 6
trace( factorial( 4 ) ) ; // 24

fibonacci()

Calculates with the fibonacci sequence the value with a specific level. By definition, the first two numbers in the Fibonacci sequence are 0 and 1, and each subsequent number is the sum of the previous two.

finalBearing(latitude1, longitude1, latitude2, longitude2)

Calculates the final bearing from a specific points to a supplied point, in degrees. For final bearing, simply take the initial bearing from the end point to the start point and reverse it (using θ = (θ+180) % 360).

Parameters:

Name	Type	Description
`latitude1`	number	The first latitude coordinate.
`longitude1`	number	The first longitude coordinate.
`latitude2`	number	The second latitude coordinate.
`longitude2`	number	The second longitude coordinate.

Returns:

The bearing in degrees from North.

Example

var position1 = new Point( 37.422045 , -122.084347 ) ; // Google HQ
var position2 = new Point( 37.77493  , -122.419416 ) ; // San Francisco, CA
trace( finalBearing( position1.x , position1.y , position2.x , position2.y ) ) ; // 143.1477743368166

fixAngle(angle)

Fixs an angle in degrees between 0 and 360 degrees.

Parameters:

Name	Type	Description
`angle`	number	The passed angle value.

Returns:

an angle fixed between 0 and 360 degrees.

floor(n [, floatCount])

Rounds and returns a number by a count of floating points.

Parameters:

Name	Type	Argument	Default	Description
`n`	number			The number to round.
`floatCount`	number	<optional>	0	the count of number after the point.

Returns:

the floor value of a number by a count of floating points.

Example

trace(floor(4.572525153, 2)) ; // 4.57
trace(floor(4.572525153, -1)) ; // 4

gcd(i1, i2)

Indicates the greatest common divisor of two values with the Euclidean algorithm.

Parameters:

Name	Type	Description
`i1`	number	The first integer value.
`i2`	number	The second integer value.

Returns:

the greatest common divisor with the Euclidean algorithm.

Example

trace("gcd(320,240) : " + gcd(320,240) ) ; // gcd(320,240) : 80

haversine(latitude1, longitude1, latitude2, longitude2 [, radius])

The haversine formula is an equation important in navigation, giving great-circle distances between two points on a sphere from their longitudes and latitudes. This algorithm is way faster than the Vincenty Formula but less accurate.

Parameters:

Name	Type	Argument	Default	Description
`latitude1`	number			The first latitude coordinate.
`longitude1`	number			The first longitude coordinate.
`latitude2`	number			The second latitude coordinate.
`longitude2`	number			The second longitude coordinate.
`radius`	number	<optional>	`core.maths.EARTH_RADIUS_IN_METERS`	The optional radius of the sphere (by default the function use the earth's radius, mean radius = 6,371km) .

See:

core.maths.EARTH_RADIUS_IN_METERS

Returns:

The distance between two points on a sphere from their longitudes and latitudes.

Example

var position1 = { x : 37.422045 , y : -122.084347  } ; // Google HQ
var position2 = { x : 37.77493  , y : -122.419416 } ; // San Francisco, CA
trace( haversine( position1.x , position1.y , position2.x , position2.y ) ) ; // 49 103.007 meters

hermite(start, end, amount)

This method will interpolate while easing in and out at the limits.

Parameters:

Name	Type	Description
`start`	number	the begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( hermite( 0 , 100 , 0.5 ) ; // 50

hypothenuse(x, y)

Computes square root of sum of two arguments (Computes hypotenuse).

A hypotenuse is the longest side of a right triangle (Right-angled triangle in British English), the side opposite the right angle. The length of the hypotenuse of a right triangle can be found using the Pythagorean theorem, which states that the square of the length of the hypotenuse equals the sum of the square of the lengths of the other two sides.

Parameters:

Name	Type	Description
`x`	number	Specifies the length of first side
`y`	number	Specifies the length of second side

Returns:

The length of the hypotenuse

Example

trace( hypothenuse(5,12) ) ; // 13

interpolate(value, min, max)

With a number value and a range this method returns the actual value for the interpolated value in that range.

Parameters:

Name	Type	Description
`value`	number	The normal number value to interpolate (value between min and max).
`min`	number	The minimum value of the interpolation.
`max`	number	The maximum value of the interpolation.

Returns:

the actual value for the interpolated value in that range.

Example

trace( interpolate( 0.5 , 0 , 100 ) ) ; // 50

isEven(value)

Indicates if an integer that is "evenly divisible" by 2.

Parameters:

Name	Type	Description
`value`	number	The value to check.

Returns:

true if the passed-in value is even.

Example

trace( isEven(0) ) ; // true
trace( isEven(2) ) ; // true
trace( isEven(3) ) ; // false

isOdd(value)

Indicates if an integer that is not "evenly divisible" by 2.

Parameters:

Name	Type	Description
`value`	number	The value to check.

Returns:

true if the passed-in value is odd.

Example

trace( isOdd(0) ) ; // false
trace( isOdd(2) ) ; // false
trace( isOdd(3) ) ; // true
trace( isOdd(5) ) ; // true

lerp(start, end, amount)

Calculates a number between two numbers at a specific increment. The lerp function is convenient for creating motion along a straight path and for drawing dotted lines.

Lerp is an abbreviation for linear interpolation, which can also be used as a verb (Raymond 2003).

Linear interpolation is a method of curve fitting using linear polynomials. It is heavily employed in mathematics (particularly numerical analysis), and numerous applications including computer graphics. It is a simple form of interpolation.

Parameters:

Name	Type	Description
`start`	number	the begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( lerp( 0 , 100 , 0.5 ) ; // 50

log10(value)

Calculates the log10 of the specified value.

Parameters:

Name	Type	Description
`value`	number	The value to calculate.

Returns:

The log10 of the specified value.

Example

trace( log10(10) ) ; // 1

log10(value, base)

Calculates the logN of the specified value.

Parameters:

Name	Type	Description
`value`	number	The value to calculate.
`base`	number	The base to calculate the log of the value.

Returns:

The logN of the specified value.

Example

trace( logN(10,10) ) ; // 1

map(value, min1, max1, min2, max2)

Takes a value in a given range (minimum1, maximum1) and finds the corresponding value in the next range(minimum2, maximum2).

Parameters:

Name	Type	Description
`value`	number	The number value to map.
`min1`	number	The minimum value of the first range of the value.
`max1`	number	The maximum value of the first range of the value.
`min2`	number	The minimum value of the second range of the value.
`max2`	number	The maximum value of the second range of the value.

Returns:

value in a given range (minimum1, maximum1) and finds the corresponding value in the next range(minimum2, maximum2).

Example

trace( map( 10,  0, 100, 20, 80  ) ) ; // 26
trace( map( 26, 20,  80,  0, 100 ) ) ; // 10

midPoint(latitude1, longitude1, latitude2, longitude2)

Calculates the midpoint along a great circle path between the two points.

Parameters:

Name	Type	Description
`latitude1`	number	The first latitude coordinate.
`longitude1`	number	The first longitude coordinate.
`latitude2`	number	The second latitude coordinate.
`longitude2`	number	The second longitude coordinate.

See:

"Latitude and Longitude of a Point Halfway between Two Points" question to calculate the derivation.

Returns:

The midpoint (Object) along a great circle path between the two points.

Example

var pos1 = { x : 34.122222   , y : 118.4111111 } ; // LA
var pos2 = { x : 40.66972222 , y : 73.94388889 } ; // NYC
var result = midPoint( pos1.x , pos1.y , pos2.x , pos2.y )  ;
trace( "midpt latitude:" + result.x + " longitude:" + result.y ) ;// midpt latitude:39.547078603870254 longitude:97.2015133919303

modulo(a, b)

The % operator in ECMASCript returns the remainder of a / b, but differs from some other languages in that the result will have the same sign as the dividend. For example, -1 % 8 == -1, whereas in some other languages (such as Python) the result would be 7. This function emulates the more correct modulo behavior, which is useful for certain applications such as calculating an offset index in a circular list.

Parameters:

Name	Type	Description
`a`	number	The dividend.
`b`	number	The divisor.

Returns:

The a % b where the result is between 0 and b (either 0 <= x < b or b < x <= 0, depending on the sign of b).

Example

trace( modulo(-1,8) ) ; // 7

nearlyEquals(value1, value2 [, tolerance])

Evaluates whether the two values are equal to each other, within a certain tolerance to adjust for floating pount errors.

Parameters:

Name	Type	Argument	Default	Description
`value1`	number			A number to evaluate.
`value2`	number			A number to evaluate.
`tolerance`	number	<optional>	0.000001	An optional tolerance range. If specified, should be greater than 0.

Returns:

true if value1 and value2 are nearly equal.

normalize(value, min, max)

Takes a value within a given range and converts it to a number between 0 and 1. Actually it can be outside that range if the original value is outside its range.

Parameters:

Name	Type	Description
`value`	number	The normal number value to interpolate (value between min and max).
`min`	number	The minimum value of the interpolation.
`max`	number	The maximum value of the interpolation.

Returns:

The normalized value between 0 and 1.

Example

trace( normalize( 10, 0 , 100 ) ) ; // 0.1

percentage(value, maximum)

Calculates a percentage value.

Parameters:

Name	Type	Description
`value`	number	The current value to calculates.
`maximum`	number	The max value.

Returns:

a percentage value or NaN.

Example

trace( percentage( 50 , 100 ) + "%" ) ; // 50%
trace( percentage( 68 , 425 ) + "%" ) ; // 16%

polarToCartesian(polar, degrees)

Converts a Polar object in a cartesian vector.

Parameters:

Name Type Description

polar

Object

The polar generic object to transform (with the attributes angle and radius).

Properties

Name	Type	Description
`angle`	number	The angle of the polar coordinates.
`radius`	number	The radius of the polar coordinates.

degrees

number

Indicates if the angle of the polar object is in degrees or radians.

Returns:

A generic Object with the cartesian representation of the specified Polar object (with the coordinates x and y).

radiansToDegrees(angle)

Converts radians to degrees.

Parameters:

Name	Type	Description
`angle`	number	Value, in radians, to convert to degrees.

Returns:

an angle in degrees.

replaceNaN(value [, defaultValue])

Replace the passed-in Number value, if the value is NaN the return value is the default value in second argument.

Parameters:

Name	Type	Argument	Default	Description
`value`	number			The `Number` value to replace, if this value is `NaN` the value is changed.
`defaultValue`	*	<optional>	0	The default value to apply over the specified value if this value is `NaN`.

Returns:

The replaced value.

Example

trace( replaceNaN(1,2) ) ; // 1
trace( replaceNaN(NaN) ) ; // 0
trace( replaceNaN(NaN,2) ) ; // 2
trace( replaceNaN(NaN,"foo") ) ; // "foo"

round(n [, floatCount])

Rounds and returns a number by a count of floating points.

Parameters:

Name	Type	Argument	Default	Description
`n`	number			The number to round.
`floatCount`	number	<optional>	0	The count of number after the point.

Returns:

The round of a number by a count of floating points.

Example

var n ;
n = core.maths.round(4.572525153, 2) ;
trace ("n : " + n) ; // 4.57

n = core.maths.round(4.572525153, -1) ;
trace ("n : " + n) ; // 5

sign(n)

Returns 1 if the value is positive or -1.

Parameters:

Name	Type	Description
`n`	number	The number to defined this sign.

Throws:

TypeError if the passed-in value is NaN.

Returns:

1 if the value is positive or -1.

Example

var n ;

n = core.maths.sign( -150 ) ;
trace ("n : " + n) ; // -1

n = core.maths.sign( 200 ) ;
trace ("n : " + n) ; // 1

n = core.maths.sign( 0 ) ;
trace ("n : " + n) ; // 1

sinD(angle)

Calculates the sine of the passed angle.

Parameters:

Name	Type	Description
`angle`	number	A value in degrees.

Returns:

The sine of the passed angle, a number between -1 and 1 inclusive.

sinerp(start, end, amount)

Short for 'cosinusoidal interpolation', this method will interpolate while easing around the end, when value is near one.

Parameters:

Name	Type	Description
`start`	number	the begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( sinerp( 0 , 100 , 0.5 ) ; // 70.71067811865474

sinH(x)

Calculates the Hyperbolic sine.

Parameters:

Name	Type	Description
`x`	number	A value to calculates.

Returns:

The Hyperbolic sine of the specified value.

smooth(start, end, amount)

Works like core.maths.Lerp, but has ease-in and ease-out of the values.

Parameters:

Name	Type	Description
`start`	number	the begining value.
`end`	number	The ending value.
`amount`	number	The amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc.

Returns:

The interpolated value between two numbers at a specific increment.

Example

trace( smooth( 0 , 100 , 0.5 ) ; // 50

tanD(angle)

Calculates the tangent of the passed angle.

Parameters:

Name	Type	Description
`angle`	number	The angle in degrees.

Returns:

The tangent of the passed angle.

tanH(x)

Calculates the Hyperbolic tangent.

Parameters:

Name	Type	Description
`x`	number	A value to calculates.

Returns:

The Hyperbolic tangent of the specified value.

vincenty(latitude1, longitude1, latitude2, longitude2)

Calculates geodesic distance in meter between two points specified by latitude and longitude (in numeric degrees) using the Vincenty inverse formula for ellipsoids. This algorithm is slow but very accurate (down to 0.5 mm).

See the original reference about this formula : Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations.

Parameters:

Name	Type	Description
`latitude1`	number	The first latitude coordinate.
`longitude1`	number	The first longitude coordinate.
`latitude2`	number	The second latitude coordinate.
`longitude2`	number	The second longitude coordinate.

Returns:

The distance between two points on a sphere from their longitudes and latitudes.

Example

var position1 = { x : 37.422045,  y : -122.084347 } ; // Google HQ
var position2 = { x : 37.77493  , y : -122.419416 } ; // San Francisco, CA

trace( vincenty( position1.x , position1.y , position2.x , position2.y ) ) ; // 49 087.066 meters

wrap(angle [, min] [, max])

Wrap an angle value between two values.

Parameters:

Name	Type	Argument	Default	Description
`angle`	number			The passed angle value.
`min`	number	<optional>	0	The minimum angle value.
`max`	number	<optional>	360	The maximum angle value.

Returns:

The wrapped angle value fixed between the min and max values.

Example

trace( wrap( 0 ) ) ; 0
trace( wrap( 360 ) ) ; 0
trace( wrap( -1 ) ) ; 359

trace( wrap( 0 , 0 , Math.PI ) ) ; // 0
trace( wrap( Math.PI , 0 , Math.PI ) ) ; // 0
trace( wrap( Math.PI / 2 , 0 , Math.PI ) ) ; // Math.PI / 2
trace( wrap( Math.PI - 1 , 0 , Math.PI ) === ( Math.PI - 1 ) ) ; // true
trace( wrap( Math.PI + 1 , 0 , Math.PI ) ) ; // 1