About the Echoview Python source file

The Code* operators and the Echoview Python source file
Generating the default Echoview Python source file

Python source file indentation
File encoding

Understanding the default Echoview Python source file: Code operator
Understanding the default Echoview Python source file: Code - Time series operator
Executing an Echoview Python source file
See also

The Code* operators and the Echoview Python source file

The Code and Code - Time series operators execute the Python commands in the Echoview Python source file.

Each Echoview Python source file contains commands that

interface between Python and Echoview, and
characterize the operator's function.

You may create an Echoview Python source file from an empty text file. Refer to the OperatorBase class for the details. However, for convenience, we recommend you generate the default Echoview Python source file using the Code* operator.

You can only specify one Echoview Python source file per Code* operator.

Generating the default Echoview Python source file

On a newly created Code variable, open the Variable Properties dialog box (press F8).
On the Operands page, specify Operand 1 from the acoustic variable list.
On the Code page, under Python source file, click on New.
In the Windows dialog box, specify the path and name for the Echoview Python source file, and click Save.

Note: You can use the same process for a Code - Time series variable. Open its Time Series Properties dialog box and use the Code - Time Series page.

Echoview creates the default Echoview Python source file, appends the .py extension to it, and opens the file in Windows Notepad (default).

You can change the default editor for the Echoview Python source file on the General page of the Echoview configuration dialog box.

Python source file indentation

The default Echoview Python source file uses tabs for Python code indentation.

You may use spaces instead, but do not mix tabs and spaces.

File encoding

The default Echoview Python source file uses the UTF-8 file encoding system. Saving using a different encoding system can cause a Code* variable to produce an error.

Understanding the default Echoview Python source file

Code

We will use the default Echoview Python source file to describe the commands that the Code operator requires to interface between Python and Echoview.

Here is a condensed version of the default Echoview Python source file, with the comments removed. The behavior is unchanged.

      from typing import List
      import echoview as ev
      import numpy as np

      class Operator(ev.OperatorBase):

          def eval(self, inputs: List[ev.OperandInput]):
              first_input = inputs[0]
              return first_input.measurement.data

Firstly, import List (from the typing module), and the echoview and numpy Python packages.

Next, define the Operator class, deriving it from the OperatorBase class.

Finally, define the eval method within the Operator class. This method contains your Python command instructions for the Code operator.

In the case of the default Echoview Python source file, the line

      first_input = inputs[0]

assigns Operand 1 to the Python variable first_input. Next,

      return first_input.measurement.data

communicates the ping sample data from Operand 1 to Echoview. Hence, the default Echoview Python source file simply programs the Code operator to return a copy of the ping sample values from Operand 1.

Code - Time series

The default Echoview Python source file demonstrates how the Code - Time series operator processes the pings from acoustic Operand 1. Echoview calls the script for each matched ping and supplies that ping, together with any surrounding pings included by the Window size (pings) setting. The eval method returns one time series measurement for the matched ping. Echoview assembles the returned measurements into the output time series.

Here is a condensed version of the default Echoview Python source file, with the comments removed. The behavior is unchanged.

from typing import List, Union
import echoview as ev
import numpy as np


class Operator(ev.OperatorBase):
	def result_type(self, inputs: List[ev.MeasurementType]) -> Union[tuple[ev.MeasurementType,ev.TimeSeriesInterpolationMode],ev.MeasurementType]:
		return ev.MeasurementType.LINE

	def eval(self, inputs: List[ev.OperandInput]):
		ping = inputs[0].measurement
		start_depth = ping.start_depth[0]
		stop_depth = ping.stop_depth[0]
		n_samples = ping.data.size
		sample_thickness = (stop_depth - start_depth) / n_samples
		max_sample_index = np.argmax(ping.data)
		bottom_range = start_depth + (max_sample_index + 0.5) * sample_thickness
		return bottom_range, ev.TimeSeriesStatus.GOOD

Firstly, import List and Union (from the typing module), and the echoview and numpy Python packages.

Next, define the Operator class, deriving it from the OperatorBase class.

The result_type method specifies the output data type. Its inputs parameter is a list containing the MeasurementType of each input operand.

The return annotation uses Union to indicate that result_type may return either:

a MeasurementType; or
a tuple containing a MeasurementType and a time series interpolation mode.

The default script returns ev.MeasurementType.LINE, so the output is a Line time series.

Finally, define the eval method within the Operator class. This method contains the Python instructions for the Code - Time series operator. Its inputs parameter is a list of input operands. Python lists begin at index 0, whereas operands in the virtual variable are numbered from 1. Consequently, the matched ping from Operand 1 is accessed using inputs[0].measurement.

The script processes each matched ping from Operand 1 and identifies the sample with the maximum value. A strong sample may represent the seabed or another strongly reflecting feature in the water column, such as an organism or ring down. You can use Graph ping from the echogram’s shortcut menu to inspect the sample values of individual pings.

For each matched ping, the script returns the range of the sample with the maximum value. Echoview uses the measurement times of Operand 1 to assemble these values into the output Line time series.

The current ping from Operand 1 is defined as ping = inputs[0].measurement. The measurement is an attribute of the OperandInput class which accesses the matched ping (also called the current ping).
start_depth is assigned ping.start_depth[0], the start depth of the current ping. start_depth is an attribute of the Ping class.
stop_depth is assigned ping.stop_depth[0], the stop depth of the current ping. stop_depth is an attribute of the Ping class.
n_samples is assigned ping.data.size, the number of values in the current ping’s sample array. The data attribute contains the NumPy array of sample values, and size is a property of that array.
sample_thickness is calculated as (stop_depth - start_depth) / n_samples. This is analogous to how Echoview calculates sample thickness.
max_sample_index is the index of the maximum sample value returned by the NumPy argmax() function. The expression passed to argmax() is ping.data, the sample array of the current ping.
bottom_range is calculated using max_sample_index. The equation is similar to how Echoview defines ping samples and sample ranges. It assumes that the transducer is pointed straight down and that transducer elevation, heave, and draft are zero.

For each matched ping, the eval method returns bottom_range as the measurement value and ev.TimeSeriesStatus.GOOD as its status. Echoview assembles these measurements into the output Line time series.

Notes:

A Python tuple groups multiple values. In this return annotation, the tuple contains the output measurement type and its interpolation mode. Specifying an interpolation mode is particularly important for an Unspecified time series because standard time series data types have inherent interpolation modes. See the TimeSeriesInterpolationMode example.
Union, from the Python typing module, indicates that a value may be one of several specified types.
See also Using the Code* operators: Selecting the matched ping, Using the window of measurements.

Executing an Echoview Python source file

Firstly, either specify the path to your Echoview Python source file, or generate a new Echoview Python source file on the Code page of the Variable Properties dialog box of the Code operator. Similarly for the Code - Time Series page of the Time Series Properties dialog box for the Code - Time series operator.

Then in Echoview:

Double-click the Code dataflow object to execute its Echoview Python source file. This opens an echogram and displays the result.
Double-click the Code - Time series dataflow object to execute its Echoview Python source file. This opens a time series graph and displays the result.

A uniformly black echogram or blank graph indicates an error.