Namespace: maths

core. maths

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

Author:
License:

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