CommandFusion Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Math Expressions ======
iViewer embeds a powerful and versatile math expression engine. Math expressions can be inserted in commands and feedback items. The Math expression parser features:
  * Standard math operators
  * Parenthesis grouping
  * Logical (boolean) operators
  * Standard math functions
  * Conditional logic using the if() function (like if / then /else statements)
  * Local variables
  * Multiple math expressions in the same command
  * Flexible result output

==== Usage ====

Basic math expressions can be written in a standard way using numbers and operators. You can use tokens which are dynamically replaced by their actual value before the math evaluation begins. Multiple expressions can be separated by a comma. You will use this feature to declare local variables and reuse them in the other expressions. When multiple expressions are present, the final result is the value of the last expression.\\
\\
Within commands, math expressions must be enclosed in double curly braces, the result of the math evaluation is converted to a string (and can be optionally formatted the way you need it). Math expression can also be used in the transform field of 'capture group' feedback items (where the incoming data type is set to Analog), in which case you won't use the double curly braces to enclose the expression.

<WRAP center round important 90%>
Do NOT use the double curly braces in the ''capture group > transform'' property in your feedback parsing. They are not needed in the transform property because this field can **only** contain math expressions. Read the above paragraph for more details.
</WRAP>


<code>

Simple addition:       {{ 1 + [currentValue] }}

Math functions:        {{ round(1.5 * [currentValue]) }}

Multiple expressions:  {{ a=100, b=2*[inputValue], max(a, b) }}

Conditions:            {{ a=[currentValue]+[delta], if(a<5, a=0, a) }}

Boolean logic:         {{ above=([currentValue] > 100), below=([currentValue]  < 0), if (above or below, 0, [currentValue]) }}

</code>

==== Numbers and text output formatting ====

When using a math expression, you can specify an output format prefixed by a colon before the closing accolades. If you omit the format, the result will be formatted as an integer.
<code>
 {{math expression}} -> will output an integer without any decimal points

 {{math expression:}} -> will output a double with full decimal points

 {{math expression:N}} -> will output double with N decimals (can be 0, in this case this amounts to outputing an int)

 {{math expression::printf format}} -> will output a string using a full printf format string, with one argument (the math expression double result).
</code>

For more info on the printf format, see here: [[http://en.wikipedia.org/wiki/Printf|Printf Format on Wikipedia]]

Math expressions can also be used in feedback 'capture group' items, within the transform field. This works same as above, but you don't have to wrap the expression in curly braces.\\
\\
With transforms, one predefined constant is set ("value") which is the value extracted from the capture group, and can be used in the math computation.\\
<WRAP center round tip 80%>
Note that the 'value' constant does not support decimal values when using an Analog data type. The constant will always be rounded to a whole number before any transform can take place.\\
So you need to capture it into a serial join first, then use [[#referencing-other-groups|capture group name referencing]] to perform any math on this value if you need the initial captured value to support decimals.
</WRAP>


==== Hexadecimal output formatting ====

In addition to the various number formatting options shown above, math expression can generate a hexadecimal ASCII string, or even raw bytes that you can use to send to a remote system. The options should be appended to the math expression, separated by a colon, just before the closing curly braces.

=== Raw bytes output ===
<code>
 :h         Convert the result to an unsigned long value (4 bytes) then output as few raw bytes as possible to
            represent this number. Bytes are output in network order (big endian).
            Examples:
            {{12+1:h}}   -> result=0x0000000d, output = "\x0d" (1 byte)
            {{1005*2:h}} -> result=0x000007da, output="\x07\xda" (2 bytes)

 
 :h<count>  Convert the result to an unsigned long value (4 bytes) the output the requested number of bytes,
            regardless of the result value. count should be 1 to 4 inclusive.
            Examples:
            {{12+1:h3}} -> result=0x0000000d, output = "\x00\x00\x0d" (3 bytes)
            
</code>

=== ASCII output (Hex String) ===
<code>
 :hs        Convert the result to an unsigned long value (4 bytes) then output an ASCII representation, using as few
            characters as possible to represent the value, using lowercase letters when needed.

            {{12+1:hs}} -> result=0x0000000d, output = "0d" (2 characters)
            {{1005*2:hs}} -> result=0x000007da, output="07da" (4 characters)
 
 :hs<count> Convert the result to an unsigned long value (4 bytes) then output an ASCII representation,
            showing the <count> least significant bytes of the result, using lowercase letters when needed.

            {{12+1:hs3}} -> result=0x0000000d, output = "00000d" (6 characters)
            {{1005*2:hs4}} -> result=0x000007da, output="000007da" (8 characters)

 
 :Hs        Same as :hs but text is output using uppercase characters:

            {{12+1:Hs}} -> result=0x0000000d, output = "0D" (2 characters)
            {{1005*2:Hs}} -> result=0x000007da, output="07DA" (4 characters)

 
 :Hs<count> Same as :hs<count> but text is output using uppercase characters.

            {{12+1:Hs3}} -> result=0x0000000d, output = "00000D" (6 characters)
            {{1005*2:Hs4}} -> result=0x000007da, output="000007DA" (8 characters)
</code>


Finally, an additional 's' specifier asks the engine to output as few characters as possible by stripping the leading nibble (half-byte) if its value is 0:
<code>
 :hss       Same as :hs, stripping the leading nibble is possible:

            {{12+1:hss}} -> result=0x0000000d, output = "d" (2 characters)
            {{1005*2:hss}} -> result=0x000007da, output="7da" (4 characters)

 
 :Hss       Same as :Hs, stripping the leading nibble is possible:

            {{12+1:hss}} -> result=0x0000000d, output = "D" (2 characters)
            {{1005*2:hss}} -> result=0x000007da, output="7DA" (4 characters)
</code>

==== Operators ====

The math expression parser recognizes the following operators. They are listed in inverse priority order (lowest priority ones come first).

<code>
 =    assignment (creates or updates a local variable)

 and  logical AND
 or   logical OR
 xor  logical XOR
 <=   less than or equal
 >=   greater than or equal
 !=   not equal
 ==   equal
 >    greater than
 <    less than

 +    addition
 -    subtraction
 *    multiplication
 /    division
 %    modulo
 ^    power (raise x to the power of y)

</code>

==== Functions ====

The math parser provides several built-in functions. Let us know if the function you need is missing from this list! Trigonometric functions take an angle expressed in radians, use the dtor() and rtod() functions to convert between degrees and radians.

=== Trigonometry ===
<code>
 dtor(a)  convert angle from degrees to radians
 rtod(a)  convert angle from radians to degrees
 sin(a)   sine function
 cos(a)   cosine function
 tan(a)   tangent function
 asin(a)  arc sine function
 acos(a)  arc cosine function
 atan(a)  arc tangent function
 sinh(a)  hyperbolic sine function
 cosh(a)  hyperbolic cosine function
 tanh(a)  hyperbolic tangent function
 asinh(a) hyperbolic arc sine function
 acosh(a) hyperbolic arc cosine function
 atanh(a) hyperbolic arc tangent function
</code>

=== Math ===
<code>
 log(n)   natural logarithm
 log2(n)  logarithm to base 2
 log10(n) logarithm to base 10
 ln(n)    logarithm to base e (2.71828...)
 exp(n)   e raised to the power of x
 sqrt(n)  square root
 abs(n)   absolute value
 trunc(n) truncate to integral value
 rint(n)  round to integral value
 near(n)  same as rint(n)
 round(n) round to integral value, regardless of rounding direction
 ceil(n)  round to smallest integral value not less than n
 floor(n) round to largest integral value not greater than n
 sign(n)  sign function: -1 if n<0, 0 if n=0, 1 if n>0
</code>

=== Multiple arguments ===
<code>
 min(n1,n2,...) smallest of all arguments. Use as many arguments as needed.
 max(n1,n2,...) largest of all arguments. Use as many arguments as needed.
 sum(n1,n2,...) sum of all arguments. Use as many arguments as needed.
 avg(n1,n2,...) mean value of all arguments. Use as many arguments as needed.
</code>

=== Conditionals ===
<code>
 if(t,a,b) if t is > 0 then result is a, otherwise result is b.
</code>

==== Examples ====


Assuming the captured value of the feedback group = 125.266335454
<code>
 "value / 100:" -> "1.25266335454"

 "value / 100" -> "1"

 "value / 100:0" -> "1"

 "value / 100:3" -> "1.252"

 "value / 100::%03.1f" -> "001.2"

 "value / 100::your value is %.2f. Isn't it cool?" -> "your value is 1.25. Isn't it cool?"
</code>

==== Tokens ====

Token names can be used anywhere in the math expression, and will be replaced with their value before the math expression is evaluated.\\
\\
For example, if you had a global token named [level] defined with a value of 125.266335454, you could create the following examples:
<code>
 "[level] / 100:" -> "1.25266335454"

 "[level] / 100" -> "1"

 "[level] / 100:0" -> "1"

 "[level] / 100:3" -> "1.252"

 "[level] / 100::%03.1f" -> "001.2"

 "[level] / 100::your value is %.2f. Isn't it cool?" -> "your value is 1.25. Isn't it cool?"
</code>

==== Referencing other groups ====

Within feedback group transform expressions, you can also reference the value of any other capture group defined in the same feedback item.\\
\\
To reference a group, it must first be given a name, and must also be listed above the current group in the feedback processing order.\\
\\
Reference the group by surrounding the name of the group in dollar signs. So if we had another capture group named [temp], which captured the value 1.25266335454 we could reference it like so:

<code>
 "$[temp]$ / 100:3" -> "1.252"

 "$[temp]$ / 100::%03.1f" -> "001.2"

 "$[temp]$ / 100::your temp value before transform is $[temp]$ and after transform is %.2f. Isn't it cool?" -> "your value before transform is 1.25266335454 and after transform is 1.25. Isn't it
</code>

==== Text evaluation notes ====

Commands (and commands within macros), string join assignments and token assignments are being run through the math parser which looks for any math expression(s) enclosed in double curly braces within the text. Text can include multiple math blocks, each enclosed in double curly braces. When processing the text, all math local variables are reset at beginning, then kept accross multiple math blocks. This means that you can perfectly send text with intertwined math result values, and that each calculation can reuse local variables from the previous step. Here is an example:
<code>
 "Going from [currentValue] to {{a=min(1,max(100, [currentValue]+[delta]))}}. Final delta is {{abs(a - [currentValue])}} (was [delta])."
</code>

In the case above, we compute a new value from a current value and a delta, cap it to a minimum of 1 and a maximum of 100, and output text showing the new value, as well as the delta between the capped new value and the current value. Assuming that [currentValue] is 17 and [delta] is 100, the output text will be:
<code>
 "Going from 17 to 100. Final delta is 83 (was 100)."
</code>
CommandFusion Wiki

User Tools

Site Tools

Page Tools
