API
Using Column Names and Frame Numbers
To refer to the values in a column, use the column name and the frame number. If you do not state the frame number, then Harmony uses the value of the current frame. You can refer to the frame numbers in the following ways:
• | currentFrame: Refers to the current frame number. |
• | numFrames: refers to the total number of frames in a scene. |
Consider the expression: value ( ``peg_x”, currentFrame-1)
• | This expression says that the current frame value will be the same as the previous frame value of the element peg_x. |
Now consider this expression: value ( ``peg_angle”, currentFrame - 2] * 3
• | In this expression, Harmony is to look two frames before the current frame in the column "peg_angle" and multiply the value by 3 to derive the value for the current frame of the expression column. |
Predefined Functions
Most mathematic functions are obvious. They either take an angle or value or return an angle or a value. Angles are always specified in degrees. If the input argument is not valid, the function will log an error (which is visible in the script editor) and the Xsheet does not display anything.
The two variants of the function value() are used to get the value of 2D functions at the current frame or the specified frame. The first argument is always a string that identifies the function. The optional second argument is the frame to use.
For example: value( “myFavBezier”, currentFrame-1)
Function | Description |
sin (angle) | Returns the sinus from angle specified in degrees |
cos (cosine) | Returns the cosinus from the angle specified in degrees |
tan (angle) | Returns the tangent from the angle specified in degrees |
asin( v ) | Returns the arcsin in degrees |
acos( v ) | Returns the arccos in degrees |
atan( v ) | Returns arctan as an angle in degrees from the first quadrant. |
atan2( x, y ) |
Returns the arc tangent in degrees. |
int | Returns the integer value of the “v”. Undefined behaviour for negative number. |
ceil( v ) | Returns the next integer greater or equal than “v” |
floor( v ) | Returns the integer value of v. Remove the fractional part. |
abs( v ) | Return the absolute value. |
sqrt( v ) |
Returns the square root for v >= 0. |
exp( v ) | Returns the “e” exponent v. (see c library exp( f )) |
ln( v ) | Returns the natural logarithmic of v for v > 0 |
ln | Logarithm of a value |
value( columnName) | Value of the function specified by “columnName” at the current frame |
value(columnName,frame) | the value of the function specified by “columnName” at the frame specified by “frame” |
column( columnName ) |
Indentify the text wrapped by columnName to be renamed whenever the column named “columnName” is renamed. column() is a keyword that does nothing at runtime, but, it helps Harmony track which references to a function needs to be renamed in the script when a function is renamed. For example, if you have a function named “B” and this one gets renamed to “C” through some scripts or by the user, all expression script referencing “B” will automatically be updated to refer to “C” if their call was wrapped as column( “B” ). |
node( nodeName ) module( nodeName ) |
Identifies a module/node that is in the same group as another module which is using this expression column. node( nodeName) and module( nodeName ) are two functions that return a proxy to a module that must live in the same group as another module using that expression column. For this method to work, the expression must be connected to a module “A” and the script must refer to a module “B” in the same group as module “A”. The resulting object is a proxy to a module and cannot be converted to a number. This proxy object is only usable by an SDK plugin. |
numFrames | A constant that represents the number of frames in the current scene |
currentFrame | A constant that represents the current frame (1 based) |
Related Topics
• | Creating an Expression for an Effect |