Technical Director's Little Helper v1.0
© 2002, Carsten Kolve, carsten@kolve.com, www.kolve.com  - critics, bug reports, suggestions welcome!

float

vector

string

single

array

single

array

single

array

fDistance
frac
round
roundUnbiased
pulse
fit
modBlend
ease

fMean
fSortByFunction
fFindByFunction
fFilterByFunction

vDistance
setMag

vMean
vSortByFunction
vFindByFunction
vFilterByFunction

padZero

sSortByFunction 
sFindByFunction
sFilterByFunction

[ UP ]

 xDistance
 Script Name fDistance
vDistance
 Synopsis float fDistance(float $aX, float $aY, float $aZ, float $bX, float $bY, float $bZ)
float vDistance(vector $a, vector $b)
 Return Value float : Result as a single double
 Description Script returns the distance between two points whose positions are given through 2 * 3 = 6 single floats.
Script returns the distance between two points whose positions are given through 2 vectors.
 Arguments float $aX, float $aY, float $aZ : The coordinates of the first point to be used.
float $bX, float $bY, float $bZ : The coordinates of the second point to be used.
vector $a : The position vector of the first point to be used.
vector $b : The position vector of the second point to be used.
 Examples fDistance 0 1 0 0 3 0;
// Result: 2 //
vDistance <<0, 1, 0>> << 0, 3, 0>>;
// Result: 2 //

[ UP ]

 frac
 Script Name frac
 Synopsis float frac(float $num)
 Return Value float : Result as a single double
 Description Script returns the fraction part of a float.
 Arguments float $num : The float whose fraction part will be computed.
 Examples frac 2.3456;
// Result: 0.3456 //
frac -2.3456;
// Result: -0.3456 //

[ UP ]

 round
 Script Name round
 Synopsis float round(float $num, int $digit)
 Return Value float : Result as a single double
 Description Script returns a given float, rounded by a given precision. Traditional rounding is used in which a digit of 0-4 rounds down and 5-9 rounds up.
 Arguments float $num : The number which is to be rounded.
int $digit : The precicision to use - provide the digit after the dot to which the script should round. You can use negative values to round to digits before the dot.
 Examples

round (12345.6789 , 0);
// Result: 12346 //
round (12345.6789 , 1);
// Result: 12345.7 //
round (12345.6789 , 2);
// Result: 12345.68 //
round (12345.6789 , -1);
// Result: 12350 //
round (12345.6789 , -3);
// Result: 12000 //

[ UP ]

 roundUnbiased
 Script Name roundUnbiased
 Synopsis int roundUnbiased(float $num)
 Return Value int : Result as a single int
 Description Script returns a rounded float as an int. In contrast to traditional rounding, unbiased rounding has the the additional rule that half-integers (0.5 fraction) are always rounded to even numbers in order to avoid statistical biasing. Use this if you have to worry about these statistical effect.
 Arguments float $num : The Number which is to be rounded.
 Examples

roundUnbiased 1.5;
// Result: 2 //
roundUnbiased 2.3;
// Result: 2 //
roundUnbiased 2.5;
// Result: 2 //

[ UP ]

 pulse
 Script Name pulse
 Synopsis int pulse(float $num, float $min, float $max)
 Return Value int 1 : if $num is between $min and $max, else 0
 Description This script checks a float to determine if it is in the range of two other floats.
 Arguments float $num : The number which is to be checked.
float $min : The lower bound of the range.
float $max : The upper bound of the range
 Examples pulse(2,1,3);
// Result: 1 //
pulse(8,1,3);
// Result: 0 //

[ UP ]

 fit
 Script Name fit
 Synopsis float fit(float $num, float $oldMin, float $oldMax, float $newMin, float $newMax)
 Return Value float : Result as a single double
 Description Script returns a number between $newMin and $newMax that is relative to $num in the range between $oldMin and $oldMax.
 Arguments float $num : The number whose relative number is to be computed.
float $oldMin : The lower bound of the old range.
float $oldMax : The upper bound of the old range.
float $newMin : The lower bound of the new range.
float $newMax : The upper bound of the new range.
 Examples fit(3,1,4,5,20);
// Result: 15 //
fit(3,0,4,0,1);
// Result: 0.75 //

[ UP ]

 xMean
 Script Name fMean
vMean
 Synopsis float fMean(float $array[])
vector vMean(vector $array[])
 Return Value float : Result as a single double
vector : Result is a single vector
 Description Script returns the statistical mean of the elements in the array of floats.
Script returns the statistical mean of the elements in the array of vectors.
 Arguments float $array[] : The array of floats whose mean will be computed.
vector $array[] : The array of vectors whose mean will be computed.
 Examples fMean {0,1,2,3,4,5,6,7,8,9};
// Result: 4.5 //
vMean {<<2,2,2>>,<<2,0,0>>,<<0,18,0>>,<<0,0,4>>};
// Result: <<1, 5, 1.5>> //

[ UP ]

 xSortByFunction
 Script Name fSortByFunction
vSortByFunction
sSortByFunction
 Synopsis float[] fSortByFunction(float $array[], string $function)
vector[] vSortByFunction(vector $array[], string $function)
string[] sSortByFunction(string $array[], string $function)
 Return Value float[] : Result is a sorted Array of floats.
vector[] : Result is a sorted Array of vectors.
string[] : Result is a sorted Array of strings.
 Description The scripts sorts an array of floats by using a user-defined sorting function. The sorting function must have this form:
proc int mySortingFunction(float $elementA, float $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
The scripts sorts an array of vectors by using a user-defined sorting function. The sorting function must have this form:
proc int mySortingFunction(vector $elementA, vector $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
The scripts sorts an array of strings by using a user-defined sorting function. The sorting function must have this form:
proc int mySortingFunction(string $elementA, string $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
 Arguments float $array[] : The array of floats which is to be sorted.
string $function : The name of the sorting function.
vector $array[] : The array of vectors which is to be sorted.
string $function : The name of the sorting function.
string $array[] : The array of strings which is to be sorted.
string $function : The name of the sorting function.
 Examples

proc int descending(float $elementA, float $elementB)
{
  return ($elementA < $elementB);
};
fSortByFunction({1,5,3,6,7,4,2,9,8,0},"descending");
// Result: 9 8 7 6 5 4 3 2 1 0 //

proc int ascendingVectorLength(vector $elementA, vector $elementB)
{
  return ( mag($elementA) > mag($elementB) );
};
vector $a[] = {<<0,1,0>>,<<0,2,0>>,<<0,0,0.5>>,<<1,1,0>>};
$a = vSortByFunction($a,"ascendingVectorLength");
print $a;
// Result:
0 0 0.5
0 1 0
1 1 0
0 2 0 //
proc int descendingStringLength(string $elementA, string $elementB)
{
return (size($elementA) < size($elementB));
};
sSortByFunction({"walk","run","sprint","go","sneak"},"descendingStringLength");
// Result: sprint sneak walk run go //

[ UP ]

 setMag
 Script Name setMag
 Synopsis vector setMag(vector $v, float $mag)
 Return Value vector : Result is a single vector.
 Description This script returns a vector which points in the direction of the input vector and is of the length specified by the input magnitude.
 Arguments vector $v : The vector whose direction the output vector has.
float $mag : The magnitude (length) of the outpur vector.
 Examples setMag(<<1,0,0>>,4);
// Result: <<4, 0, 0>> //
setMag(<<1,2,3>>,4);
// Result: <<1.069045, 2.13809, 3.207135>> //

[ UP ]

 modBlend
 Script Name modBlend
 Synopsis float modBlend(float $val1, float $val2, float $length,float $weight)
 Return Value float : Result as a single double
 Description Blends the two modular values. This function can be used to correctly blend two cyclic values (eg. angles). Blending is always performed by increasing value1 to value2.
 Arguments float $val1 : The lower bound of the blending range.
float $val2 : The upper bound of the blending range.
float $length : The length of the cyclic range.
float $weight : The weight of the blend, must be in the range of [0..1]. Values will be clamped to this range.
 Examples modBlend(310,50,360,0.2);
// Result: 330 //
modBlend(310,50,360,0.5);
// Result: 0 //
modBlend(310,50,360,0.7);
// Result: 20 //

[ UP ]

 padZero
 Script Name padZero
 Synopsis string padZero(float $value, int $nr)
 Return Value string : Result as a single string.
 Description Returns a string containing value preceded by enough zeros to make up ‘number’ digits.
 Arguments float $value : The value which should be used to buidl the `number digit`.
int $nr : The number of digits the final string should have.
 Examples padZero(23,5);
// Result: 00023 //
padZero(234,2);
// Result: 234 //

[ UP ]

 xFindByFunction
 Script Name fFindByFunction
vFindByFunction
sFindByFunction
 Synopsis float fFindByFunction(float $array[], string $function)
vector vFindByFunction(vector $array[], string $function)
string sFindByFunction(string $array[], string $function)
 Return Value float : Result is a single double.
vector : Result is a single vector.
string : Result is a single string.
 Description Finds one element in an array of floats, which fulfills the criteria given in a function best. The function must have this form:
proc int myFindFunction(float $elementA, float $elementB)
 It must return a boolean value, TRUE if the first argument is to be chosen in favour of second argument, FALSE else.
Finds one element in an array of vectors, which fulfills the criteria given in a function best. The function must have this form:
proc int myFindFunction(vector $elementA, vector $elementB)
 It must return a boolean value, TRUE if the first argument is to be chosen in favour of second argument, FALSE else.
Finds one element in an array of strings, which fulfills the criteria given in a function best. The function must have this form:
proc int myFindFunction(string $elementA, string $elementB)
 It must return a boolean value, TRUE if the first argument is to be chosen in favour of second argument, FALSE else.
 Arguments float $array[] : The array of floats in which one element is to be found.
string $function : The name of the sorting function.
vector $array[] : The array of vectors in which one element is to be found.
string $function : The name of the sorting function.
string $array[] : The array of stringsin which one element is to be found.
string $function : The name of the sorting function.
 Examples global proc int minDifToX(float $x, float $eA, float $eB)
{
  return (abs($eA-$x) < abs($eB-$x));
}
fFindByFunction({1,34,56,18,67,41,9,53},"minDifToX 62");
// Result: 67 //
global proc int minYComponent(vector $eA, vector $eB)
{
  return ($eA.y < $eB.y);
}
vFindByFunction({<<1,0,2>>,<<0,5,3>>,<<7,-2,0>>,<<10,3,8>>},"minYComponent");
// Result: <<7, -2, 0>> //
global proc int maxStringLength(string $eA, string $eB)
{
  return (size($eA)>size($eB));
}
sFindByFunction({"run","walk","sneak","go","sprint"},"maxStringLength");
// Result: sprint //

[ UP ]

 xFilterByFunction (not implemented yet)
 Script Name fFilterByFunction
vFilterByFunction
sFilterByFunction
 Synopsis float[] fFilterByFunction(float $array[], string $function)
vector[] vFilterByFunction(vector $array[], string $function)
string[] sFilterByFunction(string $array[], string $function)
 Return Value float[] : Result is a filtered Array of floats.
vector[] : Result is a filtered Array of vectors.
string[] : Result is a filtered Array of strings.
 Description The scripts filters an array of floats by using a user-defined filter function. The filter function must have this form:
proc int myFilterFunction(float $elementA, float $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
The scripts filters an array of vectors by using a user-defined filter function. The filter function must have this form:
proc int myFilterFunction(vector $elementA, vector $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
The scripts filters an array of strings by using a user-defined filter function. The filter function must have this form:
proc int myFilterFunction(string $elementA, string $elementB)
 It must return a boolean value, TRUE if the first argument should be sorted behind the second argument, FALSE else.
 Arguments float $array[] : The array of floats which is to be filtered.
string $function : The name of the filter function.
vector $array[] : The array of vectors which is to befiltered.
string $function : The name of the filter function.
string $array[] : The array of strings which is to be filtered.
string $function : The name of the filter function.
 Examples

 

[ UP ]

 ease
 Script Name ease
 Synopsis float ease(float $weight, float $easeInEnd, float $easeOutStart)
 Return Value float : Result as a single double
 Description Perfoms a sinusdial ease between 0 and 1. Will perform a sinus ease-in from 0 tol $easeInEnd, will be linear from $easeInEnd to $easeOutStart, will perform a sinus ease-out from $easeOutStart to 1.
 Arguments float $weight : Value between 0 and 1 at which the ease function should be evaluated.
float $easeInEnd : Value between 0 and 1 at which the ease-in of the function should end.
float $easeOutStart : Value between 0 and 1 at which the ease-out of the function should start.
 Examples todo: