Echoview Command interface and command syntax

The Echoview Command interface enables access to Echoview's features via instructions given as lines of text. The interface can be accessed by the Console dialog box and the Console controls or by COM scripting and requires a licensed Automation module.

Commands can be typed or pasted into the Console dialog box at the '>' prompt. Batch commands may read in from an EC file, Python file or VB script file.

The commands specify objects, actions and arguments for the interface. Progress is determined by the values returned by Echoview. The interface is designed to minimize text input and minimize the in-depth knowledge needed to create commands. However a working knowledge of Echoview is helpful. The interface only supports the display of a single property for multiple objects or multiple properties for a single object.

Note that support for the Command interface is in a continuing state of development and that parts of the command syntax may change.

Command syntax

A command uses case insensitive text. Valid text characters include:

Press Enter to issue a command.

Elements of a command are separated by a vertical bar. Letter case, space, hyphen and underscore insensitivity simplifies the command text. However, these things can be used to improve the readability of input commands. Returned values are output in Camel case and commonly separated by a space, unless the item is an array value.

To distinguish general/specific references to elements within the discussion text, the <Elements> are bracketed. Examples show an interface command and the Echoview return.

Elements include: <ObjectName>, <ActionName>, <ActionOption>, <Argument>, <FilterAction>

A general example of a command:

<ObjectName> | ... | <ActionName> <ActionOption>| <Argument> | ...

Note: The symbol pair "=|" with a space is required before "=" assigns a <PropertyName> to a <Value>. For further information refer to Variables object Properties and Transducers object Properties.

Example display conventions

The depiction of command interface examples is similar to what you would see in the Console dialog box. Using your own EV file and variable names, you can enter an example command line and view the return.

An example shows:

  1. A '>' prompt followed by a command line. When no key press instructions are displayed next to the command line, a key press Enter is assumed. Some text completion examples include key press instructions enclosed in brackets.
  2. The immediate following text is the Echoview command interface return.

The following example is general enough to use with your EV file and variables with Sv in the variable name.

Console display

Command line description

> sv* (Press Enter)
Fileset 1: Sv raw pings T1 | Fileset 1: Sv raw pings T2
>

Lists all the Sv variables.

> sv* | GridXAxisSpacingInNauticalMiles
Fileset 1: Sv raw pings T1 | 0.5 |
Fileset 1: Sv raw pings T2 | 0.5
> sv* | GridXAxisSpacingInNauticalMiles =| 22
> sv* | GridXAxisSpacingInNauticalMiles
Fileset 1: Sv raw pings T1 | 22.0 |
Fileset 1: Sv raw pings T2 | 22.0
>

Lists the Grid page ping axis spacing in nautical miles, for all variables matched to Sv*.

For all the Sv* variable names change the Grid page ping axis spacing to a value of 22 nm.

List the Grid page ping axis values for all the Sv* variable names(as a visual check).

Text completion

The Console dialog box offers command interface text matching and text completion with prefix text followed by * and with the Tab and Shift+Tab key presses.

Press Enter to send a command line to the interface.

> sv* (Press Enter)
Fileset 1: Sv raw pings T1 | Fileset 1: Sv raw pings T2
>

Press Tab to complete object text.

> sv* (Press Tab)
> Fileset 1: SvrawpingsT*

Press Shift+Tab to use text-prefix matching.

> sv* (Shift+Tab)
'sv*' matches objects
Fileset 1: Sv raw pings T1
Fileset 1: Sv raw pings T2
> sv*

Press Shift+Up arrow or Shift+Down arrow to complete a command with a selection from the latest list or a selection from a list of associated matches.

> sv* (Shift+Tab)
"sv*" matches objects
Fileset 1: Sv raw pings T1
Fileset 1: Sv raw pings T2.
> Fileset 1: Sv raw pings T1(Shift+Up arrow twice)

> EV File | (Shift+Up arrow) returns >EvFile | Save

> EV File | (Shift+Up arrow twice) returns > Ev File | Properties

> EV File | (Shift+Up arrow thrice) returns > Ev File | Close

> EV File | (Shift+Up arrow four times) returns > Ev File | AppliedObjects

In this case, use a trailing space and Shift+Tab to match <Actions>.


> sv* | (Shift+Tab)
The following actions are available:
Transducers
Variables
VariablesAcoustic
VariablesGeopoint
VariablesImage
VariablesLine
VariablesLineEditable
VariablesMovement
VariablesMultibeam
VariablesRaw
VariablesUsable
VariablesVideo
VariablesVirtual.

The use of * on its own followed by Enter returns a running list of all objects.

The use of * on its own followed by Shift+Tab returns a list of all objects with an object per line.

Objects

<ObjectNames> represent key and unique parts of the Echoview interface. Some <ObjectNames> support <ActionNames>, other <ObjectNames> don't support <ActionNames> but may be considered when filtering. For further information refer to <ObjectTypes>.

The <Objects> list is made up of specific <ObjectNames>.

<ObjectNames> that support <ActionNames> include:

<Object> Instance of the <ObjectName> Details
<Echoview>

<Echoview>

An instance of Echoview.

<Ev File>

<Ev File>

The open EV file in Echoview.

<Properties> defined by <PropertyName> with <PropertiesOptions> allow read and write access to EV File Properties dialog box settings.

<Variables>

<svrawpingst1>
<VirtualVariableName>
<bottomline>
<positionGPSfixes>

An Echoview data variable.

<Properties> defined by <PropertyName> with <PropertiesOptions> allow read and write access to Variable Properties dialog box settings of raw and virtual variables.

For more information refer to <Variables> instances.

<Transducers>

<T1>

A Dataflow transducer in Echoview.

<Properties> defined by <PropertyName> with <PropertiesOptions> allow read and write access to Transducer Properties dialog box settings.

Object matching

The interface attempts to match partial text to known <ObjectNames>.

Examples

Refer to the Text completion section for examples.

The following is the syntax to save changes for the open EV file:

> Echoview | EVFile | Save | c:\YourFolder\YourFile

The following command can also be used to save changes for the open EV file:

> Save | c:\YourFolder\YourFile

Actions, Options and Arguments

ObjectName | ActionName ActionOption | Argument

Example

Request for prefix-matched "Sv" <Objects> followed by <Shift+Tab> <ActionName> matching for the partial text "gridxaxissp". The interface returns possible matching <ActionNames> and suggests new text.

> sv* | gridxaxissp (Shift+Tab)
"gridxaxissp" matches actions
Properties GridXAxisSpacingInMinutes
Properties GridXAxisSpacingInNauticalMiles
Properties GridXAxisSpacingInPings
> sv* | GridXAxisSpacingIn

Extended commands

A command that produces a list of objects can be extended with another action element and arguments list.

For example, <variablesvirtual | variablesacoustic | gridxaxis> command line lists the Grid Show time/distance value for all virtual acoustic variables as a <variablename | value |> ordered list. This extended command uses a logical AND arrangement and returns a list of virtual acoustic variables.

> variablesvirtual | variablesacoustic | gridxaxis
AAProcessed data 1 | GPSDistanceNmi |
Background noise removal 1 | GPSDistanceNmi |
Code 1 | GPSDistanceM |
Data range bitmap 1 | GPSDistanceM |
dB diff | PingNumber |
Formula 1 | GPSDistanceNmi |
Ping subset 1 | GPSDistanceM |
Processed data 3 | None |
STDM2 | None |
Target samples bitmap 1 | None

A similar command using a logical OR arrangement returns a list that includes virtual variables and acoustic variables.

> VariablesVirtual VariablesAcoustic | GridXAxis
0.2m | None |
AAProcessed data 1 | GPSDistanceNmi |
Background noise removal 1 | GPSDistanceNmi |
Code 1 | GPSDistanceM |
Data range bitmap 1 | GPSDistanceM |
dB diff | PingNumber |
Fileset 1: angular position raw pings T1 | None |
Fileset 1: angular position raw pings T2 | None |
Fileset 1: Power dB raw pings T1 | None |
Fileset 1: Power dB raw pings T2 | None |
Fileset 1: Sv raw pings T1 | GPSDistanceNmi |
Fileset 1: Sv raw pings T2 | None |
Fileset 1: TS raw pings T1 | None |
Fileset 1: TS raw pings T2 | None |
Formula 1 | GPSDistanceNmi |
Ping subset 1 | GPSDistanceM |
Processed data 3 | None |
STDM2 | None |
Target samples bitmap 1 | None |
Threshold offset 1 | None |
Vegetation? | None |
Veg from above | None

The addition of <| Value> returns just the <value> ordered list.

> VariablesVirtual | VariablesAcoustic | GridXAxis | Value
GPSDistanceM | GPSDistanceM | GPSDistanceM | GPSDistanceNmi | GPSDistanceNmi | GPSDistanceNmi | None | None | None | PingNumber

An extended command can be used to display operands up a virtual chain or change an operand.

The dataflow (right) for the virtual chain is from the Echoview tutorial: Introduction to Multibeam Target Data Processing. The virtual variable at the bottom of the chain is marked. The initial operand and new operand five variables up the chain are marked.

Displaying operands for a virtual variable, then displaying the first operand up the virtual dataflow.

> Target length across beams | operands
Single targets >20cm target length

> Target length across beams | operands 0 | operands 0
>20cm target length

> Target length across beams | operands 0 | operands 0 | operands 0
Multibeam target detection

Changing an operand that lays up a virtual dataflow.

The name of the operand for the Target length across beams variable.

> Target length across beams | operands 0
Single targets >20cm target length

The name of the operand five variables up the chain, assigning a different operand, displaying the changed operand.

> Target length across beams | operands 0| operands 0| operands 0| operands 0 | operands 0 | Operands 0
Fileset 1: Sv frames
> Target length across beams | operands 0| operands 0| operands 0| operands 0 | operands 0 | Operands 0| Name =| Fileset 1: unspecified dB frames
> Target length across beams | operands 0| operands 0| operands 0| operands 0 | operands 0 | Operands 0
Fileset 1: unspecified dB frames (1)

Filter

The interface can filter any list of objects using either logical AND or logical OR.

See also Ev File, Variable and Transducer <Properties> and <PropertiesOptions>.

<FilterActions>

FilterActionName Description
Count

Returns the number of objects in a list or returns the number of items for a <PropertyName>.

Syntax

> <ObjectList> | count

> Evfile | PropertyName count

> PropertyName count

Description

<count> may be used as an <ActionName> with respect to an <ObjectList>.

<count> may be used as an <ActionOption> with respect to a <PropertyName>. <VariablePropertyName Count> returns a count with respect to each variable. See also Ev File Properties, Variable Properties, Transducer Properties.

Note: <ActionName> matches are prioritized over <ActionOption> matches for an ambiguous wildcard <ObjectName>.

 

<ObjectList> examples

> SvrawpingsT* | count
2

> variables | count
33

<PropertyName> example

> Evfile | ExportAnalysisVariables count
Ev File | 61

Only
Syntax

<ObjectList> | only <FilterActionOption> <ObjectType>

<ObjectList> | <FilterActionOption> <ObjectType>

Description

Restricts filter to an <ObjectType>.

! is a <FilterActionOption> that applies a logical NOT so the <ObjectType> is filtered out from the returned list. The syntax is <!> followed by a space and then <ObjectType>.

Example

> only ! variablesacoustic | only ! variablesline | only ! variablesmovement | only ! transducers
Bottom classification 1 | Echoview | Ev File | Fileset 2: Video data | Fileset 2: Video data (1)
>

 

> STDM2 | operands
Fileset 1: angular position raw pings T1 | Processed data 3
> STDM2 | operands | only variablesvirtual
Processed data 3
> STDM2 | operands | only variablesraw
Fileset 1: angular position raw pings T1
>

A variation, to view unavailable variables. Under the Filesets dialog box, the Sv raw pings T1 checkbox is clear. The return lists all the subsequent unavailable variables.

> variables | ! VariablesUsable
AAProcessed data 1 | Background noise removal 1 | dB diff | Fileset 1: Sv raw pings T1 | Threshold offset 1 | Vegetation? | Veg from above

See also Example for SPACE+Shift+Tab.

<positive integer>

<positive integer>..<positive integer>

Syntax

<ObjectList> | <j>

<ObjectList> | <n..m>

Description

A single positive integer j specifies a list index and the interface returns the list element. The list index begins at 0.

An integer range, n..m, specifies a list index range and the interface returns the range of list elements.

Example

> variablesvirtual
0.2m | Background noise removal 1 | Code 1 | Data range bitmap 1 | dB diff | Ping subset 1 | Processed data 1 | Processed data 2 | Processed data 3 | STDM2 | Target samples bitmap 1 | Threshold offset 1 | Vegetation? | Veg from above
> virtual | 0
0.2m
> variablesvirtual | 0..4
0.2m | Background noise removal 1 | Code 1 | Data range bitmap 1 | dB diff
>

ObjectTypes

<ObjectTypes> can be used to filter an <Objects> list. <Objecttypes> may be used in logical AND and logical OR commands.

<ObjectTypes>

Description

Transducers

Transducers in the Dataflow window.

Variables

 


Variables in the Dataflow window.

Further <ObjectTypes> that are also <Variables> include:

  • VariablesAcoustic
  • Echoview acoustic variables includes raw and virtual variables.
  • VariablesMovement
  • Echoview attitude, distance, position variables includes raw and virtual variables.
  • VariablesLine
  • Echoview line variable includes all line types: raw, virtual and editable.
  • VariablesLineEditable
  • Echoview line variable created as an editable line.
  • VariablesRaw
  • Echoview derived raw variables.
  • VariablesVirtual
  • Echoview virtual variables.
  • VariablesMultibeam
  • Multibeam raw and virtual variables.
  • VariablesVideo
  • Echoview video media variable.
  • VariablesImage
  • Echoview image media variable.
  • VariablesGeoPoint
  • Echoview bottom classification variable created by a Classify Bottom.
  • VariablesUsable
  • Can be used with <Objects> to return a list of available variables. Conversely, <! VariablesUsable> returns <Objects> that are not <Variables> or are unavailable <Variables>.
Examples

Available acoustic variables

> variablesacoustic | variablesusable
Code 1 | Data range bitmap 1 | Fileset 1: angular position raw pings T1 | Fileset 1: angular position raw pings T2 | Fileset 1: Power dB raw pings T1 | Fileset 1: Power dB raw pings T2 | Fileset 1: Sv raw pings T2 | Fileset 1: TS raw pings T1 | Fileset 1: TS raw pings T2 | Ping subset 1 | Processed data 3 | STDM2 | Target samples bitmap 1

Unavailable acoustic variables (Sv raw pings T1 is unavailable on Fileset 1).

> variablesacoustic | only ! variablesusable
Background noise removal 1 | dB diff | Fileset 1: Sv raw pings T1 | Processed data 1

<Objects> that are not <Variables>.

> ! Variables
Echoview | Ev File | Fileset 1: T1 | Fileset 1: T2

<Objects> that are Echoview attitude, distance, position variables

> variablesmovement
Fileset 1: heading data GPVTG | Fileset 1: position GPS fixes | Fileset 1: position GPS fixes GPGGA | Fileset 1: position GPS fixes GPGLL | Fileset 1: position GPS fixes GPRMC

 

Logical AND

List objects that are not acoustic and not lines and not movement and not transducers. See also: Only example, Extended commands.

List objects that are virtual variables and lines.

> variablesvirtual | variablesline
0.2m | Threshold offset 1 | Vegetation? | Veg from above

Logical OR

List objects that are <lines> or <movement> objects. See also: Extended commands.

> variablesline variablesmovement
0.2m | Bottom | Fileset 1: heading data GPVTG | Fileset 1: line data depth GPGGA | Fileset 1: position GPS fixes | Fileset 1: position GPS fixes GPGGA | Fileset 1: position GPS fixes GPGLL | Fileset 1: position GPS fixes GPRMC | Threshold offset 1 | Threshold offset 1EchoviewEVL | Vegetation? | Veg from above

Error handling

The interface returns an ERROR message when it is unable to execute a command line.

Troubleshooting ideas include:

Python error handling

Console dialog box Export Commands As Python... includes Console command and Console error handling code.

Number handling

Properties that take integer values will truncate assigned real values.

COM Exec return handling

Echoview provides VB script code to handle the returns of the COM Exec method. The Console dialog box feature Export Commands As VBScript creates a VBS file containing successful command lines and Command interface return handling functions.

Example to export commands to a VBS file

Substitute your EV file in place of "C:\TEMP\YourEvFile.EV".

  1. Start Echoview.
  2. On the View menu select Console.
  3. In Console dialog box at >, type Open | "C:\TEMP\YourEvFile.EV", then press Enter.
  4. In Console dialog box at >, type Variables, then press Enter.
  5. Steps 3 and 4 are command lines sent to the Echoview Command interface. Step 3, opens YourEvFile.ev. Step 4 returns all the variable names in the EV file.
  6. In Console dialog box at >, type ExportCommandsAsVbs | C:\Temp\ExampleScript.vbs, then press Enter.
  7. Open C:\Temp\ExampleScript.vbs in a text editor, review and modify as required.
  8. The content of ExampleScript.vbs includes default functions created as part of ExportCommandsAsVbs, these include COM Exec content for the successful command lines from the Console export. Other content includes error and command interface return handling functions.

Output of properties for all variables via COM and the command interface

COM ExportSettings exports supported Variable Properties settings to a text file.

Command interface Export and its variations can export supported Variable Properties, EV File Properties and Transducer Properties to a text file. The Console dialog box and Command interface can display such settings.

Building upon the previous example, the following script includes the return and error handling functions, and COM content (red text) that sends commands to the command interface (via COM Exec) to request the properties for all the acoustic variables in the EV file. A Windows Message box displays a list of truncated properties for each acoustic variable.

''''''''''''''''''''''''''''''''''''''''''''''''''
' PropertyOutput.vbs
''''''''''''''''''''''''''''''''''''''''''''''''''

' Trim all strings in array
Function TrimArray(arr)
   ReDim result(UBound(arr))
   For i = 0 To UBound(arr)
      result(i) = Replace(Trim(arr(i)), vbCrLf, "")
   Next
   TrimArray = result
End Function

' Skip the first n elements of array
Function Skip(arr, n)
   ReDim result(UBound(arr) - n)
   For i = n To UBound(arr)
      result(i - n) = arr(i)
   Next
   Skip = result
End Function

' Take the first n elements of array
Function Take(arr, n)
   ReDim result(n - 1)
   For i = 0 To n - 1
      result(i) = arr(i)
   Next
   Take = result
End Function

' Convert reply string to the result, handling any message
Function GetResults(request, reply)
   Dim results: results = TrimArray(Split(reply, "|"))
   If UBound(results) >= 0 Then
      If StrComp("ERROR", results(0)) = 0 Then
         ' error message & exit
         MsgBox request & vbCrLf & "** " & Join(results, vbCrLf)
         WScript.Quit
      Elseif StrComp("WARNING", results(0)) = 0 Then
         ' script-formatted warning message & values
         MsgBox request & vbCrLf & "-- Warning" & vbCrLf & Skip(results, 1)(0)
         results = Skip(results, 2)
      Elseif StrComp("HELP", results(0)) = 0 Then
         ' script-formatted message, no values
         MsgBox request & vbCrLf & "Help" & vbCrLf & Join(Skip(results, 1), vbCrLf)
         results = Array()
      End If
   End If
   GetResults = results
End Function

Sub Ex(request)
   ev.Exec("Log | " & request)
   Dim results: results = GetResults(request, ev.Exec(request))
   If UBound(results) >= 0 Then
      MsgBox Join(results, vbCrLf)
   End If
End Sub

Function Exec(request)
   Exec = GetResults(request, ev.Exec(request))
End Function

Dim EvApp: Set EvApp = GetObject(, "EchoviewCom.EvApplication")
EvApp.Exec("Log | Starting PropertyOutput.vbs")
Exec "open | C:\TEMP\YourEvFile.EV "
Dim vars: vars = Exec("VariablesAcoustic")
Dim var
For Each var In vars
   Dim Props: Props = Join(Exec(var & " | Properties"), vbCrLf)
   MsgBox Props
Next
EvApp.Exec("Log | Finished PropertyOutput.vbs")

Variations on this example script include:

Another VBS script

Supported variable properties are accessible via the Command interface. The well annotated example code from the file (below) changes a Variable Properties setting which is not accessible to COM. The code could be expanded to work through multiple EV files and/or multiple variable properties.

EV script 016 - Combine COM and Command interface to change variable properties.vbs is available at: https://echoview.com/support/example-scripts/

See also

The Console dialog box
PropertiesOptions
COM Exec