About the command interface

Introduction

The command interface forms part of the automation and scripting features in Echoview.

Use the command interface to issue text-based instructions either via the console window in Echoview or through a script via the COM method Exec.

Here is a glimpse of what you can do.

Open an EV file.

Open | C:\path_to\echoview-analysis.EV

Close an EV file saving changes to a new file.

Close Save | C:\path_to\new-echoview-analysis.EV

Match the names of variables (in all filesets) or surfaces with starting with 'sv'.

sv*

List the raw line variables. (Refer to the Only Action.)

VariablesRaw | VariablesLines

Set the Grid X Axis spacing in pings of all the acoustic variables (in all filesets) with names starting with 'sv'.

sv* | GridXAxisSpacingInPings = | 100

Set the Grid X Axis distance in nautical miles of the first operand (in alphabetical order) of the Sv Mask virtual variable. (Refer to the Properties Action.)

Sv Mask | Operands | 0 | GridXAxisSpacingInPings = | 22

List the properties and values on the analysis page of the variable properties dialog box of the Sv Mask virtual variable.

Sv Mask | PageAnalysis

For more information on command interface commands, visit the using the command interface page.

Note that support for the command interface is in a continuing state of development. Hence, ensure the syntax in your existing COM scripts or exported commands are up to date before you execute them.

Anatomy of a command

A basic command interface command comprises these elements

ObjectsMatcher | Action Option(s) | Argument

The | is the Separator. It is part of the command and separates the elements. Refer to the sections below for more information on each element.

If the command returns an Objects or ObjectList, you can keep applying Actions. Refer to chaining commands.

The command interface can interpret shorthand versions of commands. When issuing a command in the console for example,

> * | Only VariablesRaw | Only VariablesAcoustic

is equivalent to

> VariablesRaw | VariablesAcoustic

Refer to issuing shorthand commands for details.

The ObjectsMatcher part

A command starts with an ObjectsMatcher which generates an ObjectList of matching Objects. For example, * matches all Objects

> *

Echoview | Ev File | Fileset 1: angular position raw pings T1 | Fileset 1: Power dB raw pings T1 | Fileset 1: TS raw pings T1 | Fileset 1: T1 | Fileset 1: vessel logs

If there is no following Action then this SeparatedList is the result of the command.

Refer to matching Objects by name for more examples.

The Object types

Type

Name

Description

Application

Echoview

The instance of the Echoview application. This Object is always available.

Document

EV File

The instance of the EV file. Available when you create a new EV file or load an existing one.

Exporter

The exporter name

An exporter object (e.g. Sv integration [Regions]).

Platform

The platform name

A platform object (e.g., Fileset 1: Platform 1, or without the fillset name (if the platform is name is unique) Platform 1).

Transducer

The transducer name

The transducer object (e.g., Fileset 1: T1).

Surface

The surface name

Any surface.

Variable

The variable name

Any raw or virtual variable (e.g., Fileset 1: Power dB raw pings T1).

It may be helpful to consider Console-supported objects with the associated objects on the Dataflow window Objects list.

See also: The filter action Only and its Options.

The Action part

If an Action follows the ObjectsMatcher then it applies to the resulting ObjectsList. The Action will ignore any Objects that do not support the Action.

For example, given all available Objects

> *

Echoview | Ev File | Fileset 1: angular position raw pings T1 | Fileset 1: Power dB raw pings T1 | Fileset 1: TS raw pings T1 | Fileset 1: T1 | Fileset 1: vessel logs

the Save Action only applies to the Document Object. Hence,

> * | Save | C:\Users\FileName.EV

only applies to the Ev File Object.

Filter and operational Actions

There are two kinds of Actions: filter and operational. For example, the Only filter with its VariablesRaw Option restricts the ObjectsList to raw variables.

> * | Only VariablesRaw

Fileset 1: Sv raw pings T1 | Fileset 1: TS raw pings T1

An operational Action performs an operation on the matched Objects, for example

> Sv raw pings T* | Properties MinimumDataThreshold

Fileset 1: Sv raw pings T1 | -70.0 |

Fileset 1: Sv raw pings T2 | -70.0

The result of a filter Action and some operational Actions is a List that can be the input for further Actions, for example

> * | Only VariablesRaw | Properties MinimumDataThreshold

Fileset 1: Sv raw pings T1 | -70.0 |

Fileset 1: TS raw pings T1 | -70.0

Command interface Actions

Here are all the command interface Actions. Specify an Action with its name or one of its Options if it is unique to that Action.

For more information on Actions, refer to Actions and Options.

The Option part

An Option specializes the Action. If the Option applies only to one Action, then you can omit the Action name. Actions can have a single, several or no Options.

In this example, PageEchogram is an Option of the Properties Action.

> Ev File | Properties PageEchogram

There are three kinds of Options

  • a preset token—typically the Option name, e.g., ClearErrors

    > Echoview | ClearConsole ClearErrors

  • a number (or sequence of numbers)—typically to indicate an index or range of indexes into a List, e.g.,

    > * | Only 4 5 -3

    Echoview | Ev File | Fileset 1: vessel logs

  • a value modifier—to accept an Argument for the Action, e.g.,

    > Fileset 1: Sv raw pings T1 | Properties CustomLineDisplayThickness += | 1

Refer to the Action pages for more details on their Options, or unpacking the properties Action for more examples.

Assignment and value modifier Options

The assignment character = can be a second Option followed by a Separator and an Argument. Refer to the Properties or Operands Actions for some examples.

The += or -= value modifier Options followed by a Separator and an Argument perform arithmetic operations or expand or shrink adjustable-sized arrays.

Refer to these examples,

as well as to the examples for the Properties Action, that utilize the assignment and value modifier Options.

The Argument part

The Argument part provides parameters for the Action.

Refer to some examples on these Action pages.

About Lists

The command interface uses Lists for inputting and reporting values. There are two types

  1. SeparatedLists

    Examples include ObjectLists and PairsLists. The items of a SeparatedLists are

    • separated by |—the Separator
    • typically of the same type
    • in alphanumeric (natural sort) order
    • indexed from zero
  2. SpaceLists

    The values are spaced and hence each item must be space-free or quoted (refer to the examples in the table below).

    SpaceLists are also indexed from zero.

This table provides further details on the different Lists supported by the command interface.

Type

Description

ObjectList

Every item is the name of an object.

Object 0 | Object 1 | Object 2 | ... | Object N

Refer to the ObjectsMatcher section for an example of an ObjectsList.

PairsList

A SeparatedList of Name-Value pairs. Each pair is displayed on a new line. The Name can be the name of an object or a property. Value can be an integer, a float, presets (e.g., the Options of the Only Action), a Boolean, or a SpacedList.

Name 0 | Value 0 |

Name 1 | Value 1 |

...

Name N | Value N

PairsLists

Here are some example PairsLists with a single pair of elements.

Ev File | VesselLogDistance

Sv pulse compressed wideband pings T1 | 90.0

Ev File | (255,127,0)

Also refer to the examples

SpacedList

These include sets, fixed sized arrays, variable sized arrays, values from a PairsList etc.

Unlike other Lists, the items in a SpacedLists are separated by a space instead of the Separator.

Value0 Value1 Value2 ... ValueN

Hence each item must be space-free or quoted, e.g.,

BlueDark CyanDark GreenDark

"" "" "High SNR" "" "" ""

Values that are names containing spaces are typically converted to camel case.

Refer to the examples in PairsList values that are SpacedLists.

List Actions

These Actions apply only to Lists.

See also

About the console window
Exec
Using the command interface
Using the console