About the Formula editor window
The Formula editor window offers a way to create a mathematical formula or logical expression that operates on the data in one or more input operand variables.
To display the Formula editor window.
-
On the Variable Properties dialog box for the new variable, click the Operands tab and select your input operands.
-
On the Variable Properties dialog box for the new variable, click the Formula tab.
-
Click Edit Formula
Edit Formula is only available when data is available, and when pings from multiple operands have the same time and geometry. The pings from the selected operands must have the same start range, stop range and number of samples in order to generate a result. For multibeam pings, all the operands must have the same beam count and spread. The Match pings times and Match geometry operators can help you satisfy the ping-multiple-operand requirement.
Note: The formula operator does not account for data type when it evaluates operations on data values. As a consequence, you need to be aware of your data types and design your formulae with respect to linear domain and dB domain calculations accordingly. Refer to Input operands, pings, samples and data values for more information.
Example window
The example below shows the Formula editor window with a formula (in the Editor area).
Using the Formula editor window
See Creating a formula for guidelines on formula creation. This section describes the tools available on the Formula editor window:
Selecting formula elements
Use the Elements toolbar to choose formula elements to insert into the formula f(p,s). Click to select an element to use in the formula editor. The mouse cursor mirrors the chosen element. To clear the selected element from the mouse, click ESC or Select. Available insertion points are highlighted as you navigate in the editor window with the mouse. Click in the formula to insert the element. To clear the selected element from the mouse, click ESC or Select.
You can use the Selection tool 
on the Elements toolbar to highlight a selection within the formula. Such areas are also highlighted in the Structure panel, where you can see additional relationships and evaluation information. The selection is marked as illustrated in the figure above.
Use PAGE UP and PAGE DOWN to navigate up and down levels within the formula structure. Use the LEFT ARROW, RIGHT ARROW, UP ARROW and DOWN ARROW to navigate within formula elements.
Placeholders and insertion marker
A formula element can be:
-
placed in a placeholder (visible as a shaded green square, as illustrated in the figure above)
-
- OR -
-
inserted at an insertion marker (visible as a highlighted area with a position indicator, as illustrated in the figure above)
The insertion marker can completely surround an element if the element you are inserting only has a single place holder (e.g. brackets). Only elements which can contain other elements can be inserted using the insertion marker. See Formula elements.
Press CTRL to ignore placeholders (only the insertion marker is used). This can be useful if you need to insert something before or after a placeholder.
The CUT, COPY, PASTE and Manipulate functions on the Edit menu or the Shortcut menu are also useful in editing a formula. Especially when selecting the insertion position (Top side, Bottom side, Left side and Right side).
Elements toolbar
The Elements toolbar offers formula elements, a (text) search filter and a selection tool that changes to reflect the element you want to insert.
Six distinct categories of formula elements are available:
| Constants | elements for user specified constants and fixed constants |
| Basic | elements for basic algebraic, conversion and trigonometric functions |
| Echogram | elements which access echogram data and input operands |
| Exponents | elements for exponentiation and logarithms |
| Grid and Statistics | elements for creating matrices and vectors |
| Boolean | elements for creating logical expressions |
Note: The Elements toolbar can be docked at the top or bottom of the Formula Editor area.
Input operands, ping, samples and data values
In order to operate on echograms or the data in an echogram, Echoview identifies a data value in an echogram by its unique input operand, ping number, beam number and sample number. When you use the Formula operator:
-
The input operand is represented by the symbol Vn where n takes on the numeral assigned to a listed input operand.
-
The ping number is represented by the symbol p and can take a value from 0 upwards (the first ping in an echogram is ping 0).
-
The beam number is represented by the symbol b and can take a value from 0 upwards (the first beam in an echogram is beam 0).
-
The sample number is represented by the symbol s and can take a value from 0 upwards (the first sample in a ping is sample 0).
-
The data value of the sample s on ping p for input operand 1 is returned by the function value 1 (p, s).
-
The data value of the sample s on ping p for beam b for input operand 1 is returned by the function value 1 (p, b, s).
Note: It is essential to note that the value function takes no account of the underlying data type of the echogram. Irrespective of the data type the value is the number which is stored for sample s on ping p. For example, on an Sv echogram, the value of -30dB is stored as -30 and the value function will return -30. It does not return the linear value of 0.001 which -30dB represents. The consequence of this is that you need to be aware of your data types and design your formulae with respect to linear domain and dB domain calculations accordingly. You can use the dB and lin elements to manage your dB and linear data types.
Evaluation
Use the Evaluate button to evaluate the Formula elements with respect to the selection on the Structure panel. Note, the process of evaluation can be lengthy. The Formula elements are evaluated according to the following priorities (1 represents the first priority):
|
Precedence |
Toolbar |
Name |
|
1
|
Number | |
 |
Pi | |
 |
e | |
|
abs
|
Absolute Value | |
|
dB
|
Linear to dB | |
|
lin
|
dB to Linear | |
|
sin()
|
Sine | |
|
cos()
|
Cosine | |
|
tan()
|
Tangent | |
|
asin()
|
Arcsine | |
|
acos()
|
Arccosine | |
|
atan()
|
Arctangent | |
|
atan2()
|
Arctangent(y/x) | |
|
Rad
|
Degrees to Radians | |
|
Deg
|
Radians to Degrees | |
 |
Round | |
 |
Wrap | |
 |
Clamp | |
 |
Range | |
 |
Centered Range | |
|
Var
|
Variance | |
 |
Standard Deviation | |
 |
Min | |
 |
Max | |
 |
Median | |
|
( )
|
Brackets | |
| Data Value | ||
|
vpbs
|
Data Value | |
|
p
|
Ping Number | |
|
b
|
Beam Number | |
|
s
|
Sample Number | |
|
T/F
|
Constant Boolean | |
| Grid | ||
| Logarithm | ||
 |
Mean | |
|
Sample range | |
 |
Angular Position | |
 |
Minor-axis angle | |
 |
Major-axis angle | |
|
2
|
xy
|
Power |
|
3
|
x
|
Multiply |
 |
Divide | |
|
4
|
+
|
Plus |
|
-
|
Minus | |
|
5
|
Less Than | |
|
≤
|
Less Than or Equal To | |
|
>
|
Greater Than | |
|
≥
|
Greater Than or Equal To | |
|
=
|
Equal To | |
|
≠
|
Not Equal To | |
|
6
|
not
|
Not |
|
7
|
And | |
|
8
|
or
|
Or |
|
xor
|
Exclusive Or |
Notes:
The following conditions will return a no data value:
-
An illegal or erroneous operation e.g. division by zero or the square root of a negative number.
-
A sample beyond the limits of the operand echogram is referenced.
-
When b (the beam number) is not specified in vpbs.
-
A no data value in the operand. Alternative behavior occurs for formula elements that compare values.
-
When input values that are not angles are used with Angular Position, Minor-axis angle or Major-axis angle elements.
-
If a boolean element expects boolean values in an operand and the operand is not boolean (the boolean element is not evaluated).
Thresholded values are assigned a special value of -999 dB. Calculations in the linear domain handle the special value as zero. Other arithmetic calculations handle the special value such that the result is consistent with the thresholded nature of the value, as opposed to a pure numerical evaluation. For example -999 dB divided by a number returns -999 dB. Elements that support -999 dB are: Plus, Minus, Multiply, Divide, Absolute value, Round, Degrees to Radians, Radians to Degrees, Wrap, Clamp, Modulo, Logarithm, Power, Linear to dB, dB to Linear, Sine, Cosine, Tangent, Arcsine, Arccosine, Arctangent, Arctangent (y/x), Equal To, Less Than, Less than or Equal To, Greater than, Greater Than or and Equal To.
The Structure panel
The Structure panel displays an interactive structural view of the formula and evaluation information for formula elements. Zoom tools are also available.
One formula element can contain other elements, generally referred to as child elements or children. For example the element Plus (+) contains two elements which are added, and the element Minus (-) contains two elements which are subtracted. Each of those elements may in turn contain other elements.
The result is a structure which is illustrated in the structure panel. Each element has both a symbol and a name. The symbol is illustrated in the formula and the name is displayed in the structure panel.
To select an element, click on its name in the structure panel. The properties of the selected element are displayed at the bottom of the panel:
Type is the name of the element.
Evaluation Type is either Number (indicating a single value) or Set (indicating a group of values)
Evaluates to displays the value of that element if it is a Number, and if it can be calculated uniquely in the editor (that is, does not make reference to echogram data values).
The Input panel
The Input panel lists the (numbered) input operands that were selected on the Operands page of the Variable Properties dialog box. The numbered operand 1 corresponds to a Formula element V1. The settings Ping and Sample enable you to do a test evaluation of an expression in the Formula editor.
The menus
You can perform certain tasks on the Formula editor window by using the following commands on the:
Formula menu
|
Menu item |
Description |
|
Close Editor |
Save formula and close the Formula editor window. |
Edit menu
Some of these items have keyboard shortcuts. Refer to Formula editor keyboard shortcuts for more information.
|
Menu item |
Description |
||||||||
|
Undo |
Undo last action. Can undo multiple actions. |
||||||||
|
Redo |
Redo last action. Can redo multiple actions. |
||||||||
|
Cut |
Removes the selected element while keeping a copy of it in the Windows clipboard. |
||||||||
|
Copy |
Copies the selected element into the Windows clipboard. |
||||||||
|
Paste |
Removes the selected element replacing it with the contents of the Windows clipboard. |
||||||||
|
Paste Into Side |
With an element that contains multiple place holders selected the Paste into menu item is accessible. The further commands of Top side, Bottom side, Left side and Right side are displayed based on the positions of the available placeholders. |
||||||||
|
Delete |
Deletes the selected element. |
||||||||
|
Options |
Displays the Options dialog box where you can set the following appearance options:
|
Manipulate menu
Manipulate menu items can facilitate the editing of complex formulas. These items are also available on the Shortcut menu.
View menu
Shortcut menuThe following commands may be available on the Shortcut (right-click) menu for a selected formula element:
Note: Elements are copied to the Windows clipboard encoded in a plain text format. You can paste this text into any other Windows application, save it in a text file, share it with other people, and this same text can be pasted into the Formula editor window again later. We do not recommend changing this text however — the encoding format is not currently documented and we cannot provide support for its interpretation. See alsoAbout the Formula operator |