Expression ProcessorExpression ProcessorThis page briefly describes the Expression Processor, which is a built-in component of VisualCommander that allows the user to enter and evaluate simple scripts in a single code editing window. The user may associate input Data Points with local variable names, and then use these names in the code. Using the expressions in the code, the user can then create new output data points.
To create a new Expression Processor, select Processors from the menu in the Tools window. You will see the built-in items "Basic", "Matrix", "Quaternion", and "Script". Click the triangle next to Script and drag "Expression Evaluator" to the window. It will open the Data Flow window.
Double click on the icon in the Data Flow window. The window has three tabs, corresponding to the three major tasks associated with setting up a processor. The first tab, "Inputs", is where you can set up the data points that the processor uses for input values. In addition to any inputs that are set up, a "time" input is always available within the script which will contain the current UNIX timestamp (seconds since Jan 1, 1970).
All input points are associated with an alias; that alias is the name by which the value of the input can be referenced within the script. To add an input, drag a data point from the Data window onto the Inputs table. Once the input is added, set the desired alias, which must be a valid matla variable name. Inputs can also be removed by clicking the "-" button below the table.
The inputs tab also contains the control for changing the update rate of the processor. Only a fixed rate is currently supported; use this field to specify how often the processor should run and produce new output values.
The outputs tab allows you to create the outputs to which you will assign values within your script. Clicking the small "+" button below the main table will open a sheet that allows you to specify the location that the new output should appear within the data hierarchy, and to give it a name. The output will initially be given an alias identical to the name you gave the output; this can be changed by double-clicking the name in the alias column.
Details of the currently selected output are found in the fields below the main table. It is important to note, first, the "Finalized" checkbox. When this is checked, the output is fully created and can no longer be substantially modified, so it is important to be certain of the output's setup before clicking this box. However, it must be checked before the output can be used in a script.
In addition to finalization, the detail allows the type, units, description and attributes of the output to be set. The Rows and Columns parameters are relevant only to matrices.
The Script tab is very simple: the top box provides space for the script to be entered; the bottom provides logged messages of warnings or errors. The "Check Syntax" button does a syntax check on the code; if the code passes the syntax check, the "Enabled" checkbox will become available to check. When that box is checked, the processor will be active and will produce data. When an error occurs, the processor will automatically disable and a description of the error will print in the bottom text box.
The acceptable syntax for the processor is described below. The important point relative to the processor is the presence of variables for each input and output alias set up in the Inputs and Outputs tab. All inputs are available via their alias, and and Output's value can be set simply by assigning to their alias. Any output not assigned to will not have its value set for that update period.
This section describes the language features of the Expression Processor.
The reserved words, built-in variables, data types, statements, operators, and built-in functions of this language are described next.
The following words are reserved, and cannot be used as variable names. break, case, catch, continue, else, elseif, end, for, function, global, if, otherwise, persistent, return, switch, try, and while.
The following reserved words are not currently supported. They will be recognized as tokens, but will not parse correctly: case, catch, elseif, function, global, otherwise, persistent, return, switch, and try.
Implementation notes:
Free-form syntax is implemented. Statement separators are usually optional (see below for exceptions), statements can span multiple lines, and one line can contain multiple statements. When defining matrices, either semicolons or line breaks can signify the start of new rows.
The following variable and value names are special, and cannot be assigned new values: ans, eps, intmax, intmin, realmax, realmin, pi, i, j, inf, nan, computer, version, false, and true.
The following variable and value names are not supported. They will also be recognized as tokens, but will not parse properly: ans, i, j, computer, and version.
The Expression Processor language currently supports real double (IEEE 754 floating point double precision values), one- and two-dimensional matrices of doubles, and boolean (true or false). Character strings, single-precision floating point values, and strictly integer values are not supported.
The following statement types are supported in the Expression Processor:
Operators that operate on doubles, matrices and booleans are implemented. The operators are listed in the following table.
Matrices can only have doubles as elements; because of this, embedded matrices (stacking rows or appending columns) are not supported.
| operator | description | class |
|---|---|---|
| ' | transpose | arithmetic |
| ^ | exponentiation | arithmetic |
| * | multiplication | arithmetic |
| / \ | division (and left division) | arithmetic |
| + - | addition, subtraction | arithmetic |
| : | sequence generation | arithmetic |
| & | | bitwise AND, OR | arithmetic |
| < <= > >= == ~= | comparison | comparison |
| ~ | unary negation | logical |
| && || | logical AND, OR (short-circuit) | logical |
The built-in functions that are available are based on the standard C math library math.h, and Princeton Satellite Systems, Inc. MatrixLib class library.
Matrix versions of functions (those that are implemented via MatrixLib) are prepended with the letter m. All functions return a single value.
The available functions are listed in the following table.
| function names | number of inputs | input argument type | return type |
|---|---|---|---|
| acos, asin, atan, cos, sin, tan | |||
| acosh, asinh, atanh, cosh, sinh, tanh | |||
| exp, exp2, expm1, log, log10, log2 | 1 | double | double |
| log1p, logb, fabs, cbrt, sqrt | |||
| erf, erfc, lgamma, tgamma | |||
| ceil, floor, nearbyint, rint, round, trunc | |||
| atan2, hypot, pow, fmod, remainder, fmax, fmin | 2 | double | double |
| mabs, mceil, mfloor, mround, mrint, msqrt | |||
| mexp, mexpm1, mlog, mlog10, mlog1p, mlog2, mlogb | |||
| msin, mcos, mtan, mcsc, msec, mcot | |||
| masin, macos, matan, macsc, masec, macot | 1 | matrix | matrix |
| msinh, mcosh, mtanh, mcsch, msech, mcoth | |||
| masinh, macosh, matanh, macsch, masech, macoth | |||
| msign, mtranspose, minv, mmag, mq_pose | |||
| matan2, mcross, msolve_ax_eq_b | 2 | matrix | matrix |
| mq_mult, mq_form, mq_tform |