Echoview Command interface and command syntax

The Echoview Command interface enables access to Echoview. The interface can be accessed by the Console dialog box or by COM scripting and requires a licensed Automation module.

A line of text command can be typed into the Console dialog box at the '>' prompt or at the cursor position. Text or a command line may be pasted into the Console dialog box from the Windows clipboard. Batch commands may read in from an EC 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.

Note: Be aware 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:

The comma and double quote marks are invalid for variable names and the vertical bar "|" is reserved for interface command element separation. Press ENTER to send a command.

Elements of a command are separated by a vertical bar. To distinguish general/specific references to elements within the discussion text, the <Elements> are bracketed. Case insensitivity simplifies command text. However, the use of Camel case can improve the readability of commands. Examples show an interface command and the Echoview return.

Elements include: <ObjectName>, <Action>, <Option>, <Argument>, <FilterAction>

A general example of a command:

<ObjectName> | ... | <Action> <Option>| <Argument> | ...

Note: The symbol pair "=|" with a space is required before "=" assigns a <Property> 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)
> 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*

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

> sv* | only (SHIFT+TAB)
"only" matches action
Only.
sv* | only
The following Only options are available:
!
DataflowNotes
Filesets
Platforms
RegionClasses
Scenes
Species
TargetClasses
ThreeD
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

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

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

<Objects> that support <Actions> include:

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

<Echoview>

An instance of Echoview.

<EvFile>

<EvFile>

The open EV file in Echoview.

<Variables>

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

An Echoview data variable.

For more information refer to <Variables> instances.

<Transducers>

<T1>

A Dataflow transducer in Echoview.

Object matching

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

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 syntax has the same return as that above; note the omission of the Echoview and EvFile objects.

> Save | c:\YourFolder\YourFile

Actions, Options and Arguments

Object | Action Option | Argument

Example

Request for prefix-matched "Sv" <Objects> followed by <SHIFT+TAB> <Action> matching for the partial text "gridxaxissp". The interface returns possible matching <Actions> 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.

> variablesvirtual | variablesacoustic | gridxaxis
Background noise removal 1 | GPS distance (nmi) |
Code 1 | GPS distance (m) |
Data range bitmap 1 | GPS distance (m) |
dB diff | Ping number |
Ping subset 1 | GPS distance (m) |
Processed data 1 | GPS distance (nmi) |
Processed data 2 | None |
Processed data 3 | None |
STDM2 | None |
Target samples bitmap 1 | None
>

An extended command displays operands up a virtual chain.

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

Filter

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

<Actions>

Action Description
Count

Returns the number of objects in the list.

Example

> SvrawpingsT* | count
2

>

Only
Syntax

<ObjectList> | only <Option> <ObjectType>

<ObjectList> | <Option> <ObjectType>

Description

Restricts filter to an <ObjectType>.

! is an <Option> 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 | Echogram curtain 1 | Echoview | EV File | Fileset 1 | Fileset 2 | Fileset 2: Video data | Platform 1 | Region class 1 | Sticky note 1 | Sticky note 2 | Unassigned | Unclassified regions | Unclassified targets
>

 

> 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 check box 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

<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

Filesets

Filesets in the EV file.

Platforms

Platform in the Dataflow window.

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 Filest 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
Echogram curtain 1 | Echoview | EV File | Fileset 1 | Fileset 1: T1 | Fileset 1: T2 | Fileset 2 | Fixed depth 1 | Platform 1 | Region class 1 | Sticky note 1 | Sticky note 2 | Unassigned | Unclassified regions | Unclassified targets

<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

DataflowNotes

Echoview Dataflow notes.

Example

> dataflownotes
Sticky note 1 | Sticky note 2

RegionClasses Echoview Region classes.
TargetClasses Echoview Target classes.
Species Echoview Species classes.
Scenes Echoview scenes.
ThreeD Echoview 3D objects.

 

Logical AND

List objects that are not acoustic and not lines and not movement and not transducers. Refer to Only example.

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.

> 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:

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 10.
  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

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 ev: Set ev = GetObject(, "EchoviewCom.EvApplication")
ev.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
ev.Exec("Log | Finished PropertyOutput.vbs")

Variations on this example script include:

Another VBS script

All 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://www.echoview.com/technical-support/scripts

See also

The Console dialog box
COM Exec