3.7.9 math.inc

This file contains many general math functions and macros.

3.7.9.1 Float functions and macros

even(N). A function to test whether N is even, returns 1 when true, 0 when false.
Parameters

N = Input value

odd(N). A function to test whether N is odd, returns 1 when true, 0 when false.
Parameters

N = Input value

Interpolate(GC, GS, GE, TS, TE, Method). Interpolation macro, interpolates between the float values TS and TE. The method of interpolation is cosine, linear or exponential. The position where to evaluate the interpolation is determined by the position of GC in the range GS - GE. See example.
Parameters:

GC = global current, float value within the range GS - GE
GS = global start
GE = global end
TS = target start
TE = target end
Method = interpolation method, float value:
- Method < 0 : exponential, using the value of Method as exponent.
- Method = 0 : cosine interpolation.
- Method > 0 : exponential, using the value of Method as exponent.
  - Method = 1 : linear interpolation,

Example:

  #declare A = Interpolate(0.5, 0, 1, 0, 10, 1);
  #debug str(A,0,2)
  // result A = 5.00

  #declare A = Interpolate(0.0,-2, 2, 0, 10, 1);
  #debug str(A,0,2)
  // result A = 5.00

  #declare A = Interpolate(0.5, 0, 1, 0, 10, 2);
  #debug str(A,0,2)  
  // result A = 2.50

Mean(A). A macro to compute the average of an array of values.
Parameters:

A = An array of float or vector values.

Std_Dev(A, M). A macro to compute the standard deviation.
Parameters:

A = An array of float values.
M = Mean of the floats in the array.

GetStats(ValArr). This macro declares a global array named "StatisticsArray" containing: N, Mean, Min, Max, and Standard Deviation
Parameters:

A = An array of float values.

Histogram(ValArr, Intervals). This macro declares a global, 2D array named "HistogramArray". The first value in the array is the center of the interval/bin, the second the number of values in that interval.
Parameters:

ValArr = An array with values.
Intervals = The desired number of intervals/bins.

sind(v), cosd(v), tand(v), asind(v), acosd(v), atan2d(a, b). These functions are versions of the trigonometric functions using degrees, instead of radians, as the angle unit.
Parameters:
The same as for the analogous built-in trig function.

max3(a, b, c). A function to find the largest of three numbers.
Parameters:

a, b, c = Input values.

min3(a, b, c). A function to find the smallest of three numbers.
Parameters:

a, b, c = Input values.

f_sqr(v). A function to square a number.
Parameters:

v = Input value.

sgn(v). A function to show the sign of the number. Returns -1 or 1 depending on the sign of v.
Parameters:

v = Input value.

clip(V, Min, Max). A function that limits a value to a specific range, if it goes outside that range it is "clipped". Input values larger than Max will return Max, those less than Min will return Min.
Parameters:

V = Input value.
Min = Minimum of output range.
Max = Maximum of output range.

clamp(V, Min, Max). A function that limits a value to a specific range, if it goes outside that range it is "clamped" to this range, wrapping around. As the input increases or decreases outside the given range, the output will repeatedly sweep through that range, making a "sawtooth" waveform.
Parameters:

V = Input value.
Min = Minimum of output range.
Max = Maximum of output range.

adj_range(V, Min, Max). A function that adjusts input values in the range [0, 1] to a given range. An input value of 0 will return Min, 1 will return Max, and values outside the [0, 1] range will be linearly extrapolated (the graph will continue in a straight line).
Parameters:

V = Input value.
Min = Minimum of output range.
Max = Maximum of output range.

adj_range2(V, InMin, InMax, OutMin, OutMax). Like f_range(), but adjusts input values in the range [InMin, InMax] to the range [OutMin, OutMax].
Parameters:

V = Input value.
InMin = Minimum of input range.
InMax = Maximum of input range.
OutMin = Minimum of output range.
OutMax = Maximum of output range.

3.7.9.2 Vector functions and macros

These are all macros in the current version because functions can not take vector parameters, but this may change in the future.

VSqr(V). Square each individual component of a vector, equivalent to V*V.
Parameters:

V = Vector to be squared.

VPow(V, P), VPow5D(V, P). Raise each individual component of a vector to a given power.
Parameters:

V = Input vector.
P = Power.

VEq(V1, V2). Tests for equal vectors, returns true if all three components of V1equal the respective components of V2.
Parameters:

V1, V2 = The vectors to be compared.

VEq5D(V1, V2). A 5D version of VEq(). Tests for equal vectors, returns true if all 5 components of V1 equal the respective components of V2.
Parameters:

V1, V2 = The vectors to be compared.

VZero(V). Tests for a < 0, 0, 0> vector.
Parameters:

V = Input vector.

VZero5D(V). Tests for a < 0, 0, 0, 0, 0> vector.
Parameters:

V = Input vector.

VLength5D(V). Computes the length of a 5D vector.
Parameters:

V = Input vector.

VNormalize5D(V). Normalizes a 5D vector.
Parameters:

V = Input vector.

VDot5D(V1, V2). Computes the dot product of two 5D vectors. See vdot() for more information on dot products.
Parameters:

V = Input vector.

VCos_Angle(V1, V2). Compute the cosine of the angle between two vectors.
Parameters:

V1, V2 = Input vectors.

VAngle(V1, V2), VAngleD(V1, V2). Compute the angle between two vectors. VAngle() returns the angle in radians, VAngleD() in degrees.
Parameters:

V1, V2 = Input vectors.

VRotation(V1, V2, Axis), VRotationD(V1, V2, Axis).Compute the rotation angle from V1 to V2 around Axis. Axis should be perpendicular to both V1 and V2. The output will be in the range between -pi and pi radians or between -180 degrees and 180 degrees if you are using the degree version. However, if Axis is set to <0,0,0> the output will always be positive or zero, the same result you will get with the VAngle() macros.
Parameters:

V1, V2 = Input vectors.

VDist(V1, V2). Compute the distance between two points.
Parameters:

V1, V2 = Input vectors.

VPerp_To_Vector(V). Find a vector perpendicular to the given vector.
Parameters:

V = Input vector.

VPerp_To_Plane(V1, V2). Find a vector perpendicular to both given vectors. In other words, perpendicular to the plane defined by the two input vectors
Parameters:

V1, V2 = Input vectors.

VPerp_Adjust(V1, Axis). Find a vector perpendicular to Axis and in the plane of V1 and Axis. In other words, the new vector is a version of V1 adjusted to be perpendicular to Axis.
Parameters:

V1, Axis = Input vectors.

VProject_Plane(V1, Axis). Project vector V1 onto the plane defined by Axis.
Parameters:

V1 = Input vectors.
Axis = Normal of the plane.

VProject_Axis(V1, Axis). Project vector V1 onto the axis defined by Axis.
Parameters:

V1, Axis = Input vectors.

VMin(V), VMax(V). Find the smallest or largest component of a vector.
Parameters:

V = Input vector.

VWith_Len(V, Len). Create a vector parallel to a given vector but with a given length.
Parameters:

V = Direction vector.
Len = Length of desired vector.

3.7.9.3 Vector Analysis

SetGradientAccuracy(Value): all below macros make use of a constant named '__Gradient_Fn_Accuracy_' for numerical approximation of the derivatives. This constant can be changed with the macro, the default value is 0.001.

fn_Gradient(Fn): macro calculating the gradient of a function as a function.
Parameters:

Fn = function to calculate the gradient from.

Output: the length of the gradient as a function.

fn_Gradient_Directional(Fn, Dir): macro calculating the gradient of a function in one direction as a function.
Parameters:

Fn = function to calculate the gradient from.
Dir = direction to calculate the gradient.

Output: the gradient in that direction as a function.

fn_Divergence(Fnx, Fny, Fnz): macro calculating the divergence of a (vector) function as a function.
Parameters:

Fnx, Fny, Fnz= x, y and z components of a vector function.

Output: the divergence as a function.

vGradient(Fn, p0): macro calculating the gradient of a function as a vector expression.
Parameters:

Fn = function to calculate the gradient from.
p0 = point where to calculate the gradient.

Output: the gradient as a vector expression.

vCurl(Fnx, Fny, Fnz, p0): macro calculating the curl of a (vector) function as a vector expression
Parameters:

Fnx, Fny, Fnz = x, y and z components of a vector function.
p0 = point where to calculate the gradient.

Output: the curl as a vector expression

Divergence(Fnx, Fny, Fnz, p0): macro calculating the divergence of a (vector) function as a float expression
Parameters:

Fnx, Fny, Fnz = x, y and z components of a vector function.
p0 = point where to calculate the gradient.

Output: the divergence as a float expression.

Gradient_Length(Fn, p0): macro calculating the length of the gradient of a function as a float expression.
Parameters:

Fn = function to calculate the gradient from.
p0 = point where to calculate the gradient.

Output: the length of the gradient as a float expression.

Gradient_Directional(Fn, p0, Dir): macro calculating the gradient of a function in one direction as a float expression.
Parameters:

Fn = function to calculate the gradient from.
p0 = point where to calculate the gradient.
Dir = direction to calculate the gradient.

Output: the gradient in that direction as a float expression