Text data files

Text data files are provided primarily to allow you to export data values from Echoview, process them using another application, and then add the resulting data files to Echoview for display and analysis. Echoview supports these character encoding systems for text data files: UTF8, UTF-16 and ASCII.

Text data files do not have to originate from Echoview exports and may be created manually or from data exported from other applications. Regardless of the creation method, a text data file must be a comma-separated values (.csv) file that conforms to relevant file format described below.

When adding data from text data files, Echoview looks at the header line of the file for fields in the list of required and optional fields and then notes the column number associated with each name. Columns it does not recognize are generally ignored (see notes below). Echoview reads each line and pulls out required fields. Therefore you can insert any number of other columns with sensible headers, and Echoview ignores them. These can be interspersed among the expected columns. The order of the columns is not important.

When adding data, it is also particularly important to specify dates in a clear and unambiguous way e.g. 06/Jun/2008 or Jun/02/2008. Ambiguity and errors arise when the numerical day and month transpose due to changes in Microsoft Windows Regional settings for Regional and Language Options in the Control Panel.

Notes:

The following file types are supported:

Note: Prior to Echoview 4.90 a bug was associated with using field names from .csv files. The bug fix can affect pre-Echoview 4.90 EV files that use field names. For more information refer to the bug fix documentation.

Data columns

Echoview uses the column header to identify and locate required columns in .csv files. Columns Echoview does not recognize are generally ignored. The exception is the case of single target .csv files which are used with the TS substitution operator. This operator can use values from "unrecognized" custom columns.

The files produced when exporting data from Echoview contain all required data columns. It is therefore possible to export data, modify it, and add it again to Echoview for further processing. Note however, that files containing underlying data exported from Echoview cannot meaningfully be added to Echoview as data files.

To add text data files to an existing EV file, you may need to create a new fileset.

Data values from single beam, split beam and dual beam variables

Text data files may contain data values from single beam, split beam and dual beam variables.

Data types

A prefix is added to the .csv file extension to identify what type of data is contained in a file.

Data type

File extension

Sv

.sv.csv

TS

.ts.csv

Angular position

.angles.csv

Linear

.linear.csv

File format

The first line of the *.csv file lists the names of the variables that appear in subsequent lines (these will be used as column headings if the file is loaded into a spreadsheet program). No column heading is provided for the list of data values. Each subsequent line contains the value for each variable for a single ping and the data value for each sample in the ping.

The following columns are expected.

Variable

Description

Ping_date

yyyy-mm-dd

Ping_time

hh:mm:ss

Ping_milliseconds

ms (optional column, may be left out)

Range_start

m

Range_stop

m

Sample_count

Number of samples to follow

List of data values

Sample values (separated by commas)

Notes:

That is, the range of each data point (measured at the center of that data point) is,

Range = Range_start + (n + 0.5) * (Range_stop - Range_start) / Sample_count)

Where n = 0, 1, 2, 3, 4 … Sample_count-1

Data values from multibeam variables

Text data files may contain data values from multibeam variables. See Exporting data for more information.

Data types

A prefix is added to the .csv file extension to identify what type of data is contained in a file.

Data type

File extension

magnitude (beamformed)

.mag.mb.csv

phase (beamformed)

.phase.mb.csv

Sv

.sv.mb.csv

unspecified dB

.db.mb.csv

TS

.ts.mb.csv

Boolean

.boolean.mb.csv

color

.color.mb.csv

Note: files containing underlying data values exported from Echoview cannot be added to Echoview as data files.

File format

The first line of the *.csv file lists the names of the variables that appear in subsequent lines (these will be used as column headings if the file is loaded into a spreadsheet program). No column heading is provided for the list of data values. Each subsequent line contains the value for each variable for a single ping and the data value for each sample in the ping.

Variable

Description

Ping_date

The date (yyyy-mm-dd) on which the ping was transmitted

Ping_time

The time (hh:mm:ss) at which the ping was transmitted

Ping_milliseconds

The millisecond (0..999) at which the ping was transmitted (optional column, may be left out)

Range_start

Range (m) of the closest sample (measured along the beam-axis)

Range_stop

Range (m) of the farthest sample (measured along the beam-axis). Range_stop must be greater than Range_start.

Ping_mode

A number identifying the ping mode (optional column, may be left out, defaults to 1).

Ping_group

A number identifying the ping group (optional column, may be left out, defaults to 0).

Sector_angle

Angle (degrees) scribed between the outer edges of the two outer beams. Angle must be greater than 0.001.

Tilt_angle

The tilt angle of the ping (optional column, necessary only if ping_mode is 3 or 5).

Bearing_angle

The bearing angle of the ping (optional column, necessary only if ping_mode is 4 or 5).

Number_of_beams

Number of beams in the ping. There must be at least 2 beams.

If you have only 1 beam please consider using the single beam text data file format.

Samples_per_beam

Number of samples in each beam

Data values

Note: No title in the header row of the file

On the remainder of this line, the data value for each sample arranged as follows (for x+1 samples and y+1 beams):

<beam0 sample0>, <beam1 sample0> ... <beamy sample0>,

<beam0 sample1>, <beam1 sample1> ... <beamy sample1>,

...

<beam0 samplex>, <beam1 samplex> ... <beamy samplex>

Note: For "color" variables, the red, green and blue color intensities of each data point is encoded in a single number. The number is a decimal representation of a six digit hexadecimal number 'bbggrr'; where 'bb' represents the intensity of blue, 'gg' represents the intensity of green, and 'rr' represents the intensity of red. The intensity range is 0 (00) to 255 (FF).

There must be at least one data point.

Notes:

That is, the range of each data point (measured at the center of that data point) is,

Range = Range_start + (n + 0.5) * (Ra nge_stop - Range_start) / Samples_per_beam)

Where n = 0, 1, 2, 3, 4 … Samples_per_beam-1 (for all the samples in any one beam)

Single targets (.target.csv)

Text data files may contain single beam targets. The .target prefix is added to the csv tile extension (e.g. filename.target.csv) to identify single beam targets files from other text data files.

The first line of the file is a header row that contains the names of the variables in the file. Each additional row contains the corresponding variables for a single ping. Echoview can read the following single target variables:

Variable

Description

Ping_date

The date (yyyy-mm-dd) on which the ping was transmitted.

Ping_time

The time (hh:mm:ss) at which the ping was transmitted.

Ping_milliseconds

The millisecond (0..999) at which the ping was transmitted (optional column, may be left out).

Target_on_axis_depth

The on axis depth (m) of a single target. When adding single target data to an EV file consider the issues raised in Notes.

Target_range

The range (m) of a single target.

TS_comp

The compensated target strength (dB re 1m2) of a single target .

See also: Single target analysis variable TS_comp.

TS_uncomp

The uncompensated target strength (dB re 1m2) of a single target (optional column, may be left out).

See also: Single target analysis variable TS_uncomp.

Angle_minor_axis

The Minor-axis angle (degrees) of a single target (optional column, may be left out).

The Minor-axis angle (degrees) of a multibeam target.

Angle_major_axis

The Major-axis angle (degrees) of a single target (optional column, may be left out).

The Major-axis angle (degrees) of a multibeam target.

PulseLengthDeterminationLevel

The pulse length determination level (PLDL) used for calculating single target properties (optional column, may be left out).

See also: Single target analysis variable PulseLengthDeterminationLevel.

Samples_above_PLDL

The number of samples in a single target pulse with a value above the pulse length determination level (PLDL). (Optional column, may be left out.)

StandDev_angles_minor_axis

The standard deviation of the Minor-axis angles of all samples within a single target pulse determined relative to the PLDL. (Optional column, may be left out.)

StandDev_angles_major_axis

The standard deviation of the Major-axis angles of all samples within a single target pulse determined relative to the PLDL. (Optional column, may be left out.)

PulseLength_normalized_6dB

The length of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

PulseLength_normalized_12dB

The length of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

PulseLength_normalized_18dB

The length of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

PulseLength_normalized_PLDL

The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

Pulse_start_normalized_6dB

The distance between the start and peak of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

Pulse_start_normalized_12dB

The distance between the start and peak of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

Pulse_start_normalized_18dB

The distance between the start and peak of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

Pulse_start_normalized_PLDL

The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (-). (Optional column, may be left out.)

Transmitted_pulse_length

The transmitted pulse length (ms) against which pulse dimensions are normalized. (Optional column, may be left out.)

Target_length

The length (cm) of a single target. Within Echoview, Target_length can be estimated from single targets data or multibeam targets data. (Optional column, may be left out.)

Target_length_uncompensated

The length (cm) of a single target that has been calculated using uncompensated TS in the target_length_calculator_algorithm. (Optional column, may be left out.)

Target_length_manual

See Target length manual. Only relevant for multibeam targets.

Target_perimeter

See Target perimeter. Only relevant for multibeam targets.

Target_area

See Target area. Only relevant for multibeam targets.

Target_intensity_variation

See Target intensity variation. Only relevant for multibeam targets.

Target_compactness

See Target compactness. Only relevant for multibeam targets.

Target_thickness

See Target thickness. Only relevant for multibeam targets.

Target_length_across_beams

See Target length across beams . Only relevant for multibeam targets.

Target_range_extent

See Target range extent . Only relevant for multibeam targets.

Target_class

See Target class. Only relevant for multibeam targets.

Target_orientation

See Target orientation. Only relevant for multibeam targets.

Ping number

The ping number of a single target.

Notes:

Multibeam targets (.targets.mb.csv)

Text data files may contain multibeam targets. The targets.mb. prefix is added to the csv file extension (e.g. filename.targets.mb.csv) to identify multibeam targets files from other text data files.

The first line of the file is a header row that contains the names of the variables in the file (see below). Each additional row contains the corresponding variables for a single ping.

Variable

Description

Ping_index

Sequential ping number

Note: In Echoview, pings are renumbered sequentially beginning with 0

Distance_gps

Distance (nmi) from the first GPS fix in the data file

Distance_vl

Vessel log (nmi) at the time the ping was transmitted

Ping_date

The date (yyyy-mm-dd) on which the ping was transmitted

Ping_time

The time (hh:mm:ss) at which the ping was transmitted

Ping_milliseconds

The millisecond (0..999) at which the ping was transmitted (optional column, may be left out)

Latitude

The latitude (degrees) of the GPS antenna at the time the ping was transmitted

Longitude

The longitude (degrees) of the GPS antenna at the time the ping was transmitted

Heading

The heading of the platform at the time the ping was transmitted

Note: Heading values are taken from the heading source selected on the Attitude_page of the Platform Properties dialog box.

Range_start

Minimum range (m) of the sector plot on which the targets will be displayed.

Range_stop

Maximum range (m) of the sector plot on which the targets will be displayed.

Sector_angle

Angle (degrees) between outer edges of the sector plot on which the targets will be displayed.

Number_of_beams

Number of beams in this ping (ignored by Echoview)

Number_of_targets

Number of targets in this ping

Ping_mode

Ping mode of the multibeam target variable.

Variable_name

Name of multibeam target variable.

Datafile_ping_number

The number, if any, asssigned to the ping in the original data file from which Echoview read the data.

Target values

Note: No title in the header row of the file

Five (or four) values are provided for each target

  • target range (m)

  • target mean Sv (dB re 1m-1)

  • target major-axis angle (degrees)

  • target minor-axis angle (degrees) - optional

  • target status:

  • 1 = excluded from the echogram by the thresholds on the Data page of the Variable Properties dialog box

  • 0 = included on the echogram

The values expected are as follows:

<target 0 range>, <target 0 mean Sv >, <target 0 major-axis angle>, <target 0 minor-axis angle>, <target 0 status>,
<target 1 range>, <target 1 mean Sv >, <target 1 major-axis angle>, <target 1 minor-axis angle>, <target 1 status>,
 ...
<target n range>, <target n mean Sv >, <target n major-axis angle>, <target n minor-axis angle>, <target n status>

For Number_of_targets=n+1.

Note: The minor-axis angle may be omitted. Echoview version 3.20 did not export this and created such files with multibeam target exports. Echoview will expect the minor-axis if the number of target values is equal to 5 times the number of targets, and not if the it is 4 times the number of targets.

Notes:

GPS fixes data

Text data files may contain GPS fixes.

A .gps prefix is added the *.csv file extension to distinguish these files from other .csv files.

The first line lists the variables in the file. Each subsequent line contains the following values for a single GPS fix:

Variable

Description

GPS_date

yyyy-mm-dd

GPS_time

hh:mm:ss

GPS_milliseconds

ms (optional column, may be left out)

Latitude

degrees

Longitude

degrees

Notes:

Vessel Log Data

Text data files may contain vessel log data.

A .log prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.log.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single log position:

Variable

Description

Log_data

A sequential number

Log _date

yyyy-mm-dd

Log_time

hh:mm:ss

Log_milliseconds

ms

Log_distance

distance in nautical miles

Notes

Heading Data

Text data files may contain heading data.

A .heading prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.heading.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single heading determination:

Variable

Description

Heading_date

yyyy-mm-dd

Heading_time

hh:mm:ss

Heading_milliseconds

ms (optional column, may be left out)

Bearing

degrees.

Measured clockwise from north, i.e. 0 is north and 90 is east.

Notes:

Roll Data

Text data files may contain roll data.

A .roll prefix is added the *.csv file extension to distinguish these files from other .csv files, e.g. filename.roll.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single roll determination:

Variable

Description

Roll_date

yyyy-mm-dd

Roll_time

hh:mm:ss

Roll_milliseconds

ms (optional column, may be left out)

Roll_angle

degrees.

Measured as a clockwise rotation of the platform about the alongship axis when viewed towards the bow. 0 degrees indicates a horizontal platform.

Notes:

Pitch Data

Text data files may contain pitch data.

A .pitch prefix is added the *.csv file extension to distinguish these files from other .csv files, e.g. filename.pitch.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single pitch determination:

Variable

Description

Pitch_date

yyyy-mm-dd

Pitch_time

hh:mm:ss

Pitch_milliseconds

ms (optional column, may be left out)

Pitch_angle

degrees.

Measured as a clockwise rotation of the platform about the athwartship axis when viewed towards the bow. 0 degrees indicates a horizontal platform.

Notes:

See also

Raw variables derived from text data files
Calibration settings for text data

Export file formats

Exporting data

Exporting GPS fixes