PCLR2SonicWCLoader

MLModule
genre FileMain
author Wolf Spindler
package FMEstable/PCL
dll MLPCLR2SonicWCLoader
definition PCLR2SonicWCLoader.def
see also LocalImage, ImageSave, PCLLoad, PCLSave
inherits from PCLModule
keywords sonar, importer, loader, reader, r2, sonic, r2sonic, water, column, watercolumn

Purpose

This is a reader for R2Sonic .wc water column files generated by SONIC 2026/2024/2022 devices by R2 Sonic LLC..

It reads magnitude data from such files, applies

Possible phase values are shifted and scaled from range [-32768,32767] to [0,1] if not specified otherwise in Disable value normalization to [0,1] and/or in Scale phase to [-1,1].

Output points are of type XYZINormal which means that each point is a tupel (x, y z, w, nx, ny, nz, nw, intensity):

  • x / data[0]: the x-component of the point
  • y / data[1]: the y-component of the point
  • z / data[2]: the z-component of the point
  • w / data[3]: the homogeneous scale factor (usually 1)
  • x / data_n[0]: the x-component of the normal of the point (usually 0)
  • y / data_n[1]: the y-component of the normal of the point (usually 0)
  • z / data_n[2]: the z-component of the normal of the point (usually 0)
  • data_n[3]: the homogeneous scale w-component of the normal of the point (usually 0)
  • curvature: the curvature value of the point, usually filled with the phase value of the signal if available, otherwise 0)
  • intensity: the intensity value of the point (filled usually with the magnitude value of the signal)

For very large files a number of settings allow the control of maximum number of generated points, used memory, file sizes and cache memory for speed optimizations.

Thank you to Dr. Yann Marcon from MARUM for providing support, lively discussions, code of a draft reader as well as example data which can be published with this module. It was very useful to implement this module, to develop tests and examples.

Details

Loaded R2Sonic .wc water column data can be very large and data structures managed internally can be up to 16 times larger. The module makes use of as much memory as needed to fulfill its operation correctly and assumes that settings are configured appropriately. Thus ensure that the machine is capable to manage the configured amount of data. Some tips to reduce the amount of data:

Windows

Default Panel

../../../Projects/MLPCLR2SonicWCLoader/Modules/mhelp/Images/Screenshots/PCLR2SonicWCLoader._default.png

Output Fields

outputPCLObject0

name: outputPCLObject0, type: MLBase

Point cloud output with PCL XYZINormal cartesian points. x,y, and z specify the coordinates of samples, intensity the magnitude value and curvature the phase value (if available, otherwise 0). This module still does not set up any indices in this output base object, which, however, may be added in the future.

outputPCLObject1

name: outputPCLObject1, type: MLBase

If Create point cloud with index coordinates at second output then a second point cloud with index coordinates is generated and provided at outputPCLObject1, otherwise this output connector is left NULL. If enabled then it contains points of type PCL XYZINormal with index coordinate points. x,y, and z specify the index positions of beam, ping, and sample of any sample, intensity the magnitude value and curvature the phase value (if available, otherwise 0). This module still does not set up any indices in this output base object, which, however, may be added in the future.

Parameter Fields

Field Index

A1_BeamAngle: String H0_RxMiscInfo: Integer Min Valid Second: Integer
A1_MoreInfo: String H0_RxMountTilt: Float Mount Plane Tilt Offset In Degree: Float
A1_SectionName: String H0_RxRange: Float Mx_Beams: Integer
A1_SectionSize: Integer H0_RxSampleRate: Float Mx_FirstBeam: Integer
Actually Used Angle Offset Per Ping In Degree: Float H0_RxSpreading: Float Mx_FirstSample: Integer
Actually Used Threshold: Float H0_SectionName: String Mx_PingNumber: Integer
Add H0_RxMountTilt to Mount Plane Tilt: Bool H0_SectionSize: Integer Mx_reserved0: Integer
Angle Of First Ping In Degree: Float H0_SerialNumber: String Mx_reserved1: Integer
Angle Offset Per Ping In Degree: Float H0_SoundSpeed: Float Mx_Samples: Integer
applyTVG: Bool H0_TimeNanoseconds: Integer Mx_ScalingFactor: Float
Auto adapt threshold on too many points: Bool H0_TimeSeconds: Integer Mx_SectionName: String
Auto Apply: Bool H0_TxBeamwidthHoriz: Float Mx_SectionSize: Integer
Auto Calculate Angle Offset Per Ping: Bool H0_TxBeamwidthVert: Float Mx_TotalBeams: Integer
Convert Orphaned Beams And Samples: Bool H0_TxMiscInfo: Integer Mx_TotalSamples: Integer
Create point cloud with index coordinates at second output: Bool H0_TxPower: Float Normalize to a TxPower of 191 dB: Bool
DataStreamID: Integer H0_TxPulseWidth: Float Number Of Beams To Output: Integer
Disable value normalization to [0,1]: Bool H0_TxSteeringHoriz: Float Number Of Pings To Output: Integer
File Dump: String H0_TxSteeringVert: Float numberOfPingsInFile: Integer
File IO has succeeded: Bool H0_VTX_Plus_Offset: Integer PacketName: String
Full File Path: String Index Of First Beam To Output: Integer PacketSize: Integer
Full Rotator Range In Degree: Float Index Of First Ping To Output: Integer progress: Float
H0_Beams: Integer Load: Trigger Scale phase to [-1,1]: Bool
H0_Frequency: Float Magnitude Scale: Float Show First Of Each Packet Type Only: Bool
H0_ModelNumber: String Magnitude Threshold: Float Status: String
H0_PingNumber: Integer Magnitude Threshold Percentage: Float Stop: Trigger
H0_PingPeriod: Float Max Allowed File Size In MBytes: Integer Subtract gain from signal values: Bool
H0_reserved: Integer Max Num Allowed Points: Integer Unify to homogeneous range after TVG: Bool
H0_RxAbsorption: Float Max Number Of Beams To Show: Integer Working Memory Hint In MBytes: Integer
H0_RxBandwidth: Float Max Number Of Packets To Show: Integer  
H0_RxGain: Float Max Number Of Samples Per Beam To Show: Integer  

Visible Fields

Status

name: status, type: String, persistent: no

Shows success state of the recent .wc file operation.

see also PCLModule.status

Full File Path

name: fullFilePath, type: String

Full path to the file to be loaded.

Auto Apply

name: autoApply, type: Bool, default: FALSE

If checked then the file specified in Full File Path is loaded immediately on changes of Full File Path, otherwise Load must be used instead.

Load

name: load, type: Trigger

Sensitive only if Auto Apply is not checked. Then it can be used to load the file specified in Full File Path.

File IO has succeeded

name: fileIOHasSucceeded, type: Bool, persistent: no

Checked after a successful load of the file specified in Full File Path. If not checked after load then file loading failed. See messages in Status and in the error output for error analysis.

Max Number Of Packets To Show

name: maxNumberOfPacketsToShow, type: Integer, default: 0, minimum: -1

The maximum number of data packets from file Full File Path to be dumped as text in File Dump. -1 dumps all packets, 0 disables packet dumping. Take care with -1 and with large values since large file dumps need a lot of memory and degrade performance. Only sensitive if Show First Of Each Packet Type Only is off, otherwise unused.

Show First Of Each Packet Type Only

name: showFirstOfEachPacketTypeOnly, type: Bool, default: FALSE

If checked then only the first of each section type (WCD0, H0, A1, M1 or M2) of the file is shown in File Dump and Max Number Of Packets To Show is ignored. If off then Max Number Of Packets To Show controls the number of sections to display independent of the section types inside.

Max Number Of Beams To Show

name: maxNumberOfBeamsToShow, type: Integer, default: 0, minimum: -1

The maximum number of data beams from each dumped packet from file Full File Path to be shown as text in File Dump. -1 dumps all beams, 0 disables dump of beam data values at all. Take care with -1 and with large values since large file dumps need a lot of memory and degrade performance.

Max Number Of Samples Per Beam To Show

name: maxNumberOfSamplesPerBeamToShow, type: Integer, default: 0, minimum: -1

The maximum number of data samples to be shown as text in File Dump for each shown beam. -1 dumps all samples of shown beams, 0 disables dump of samples at all. Take care with -1 and with large values since large file dumps need a lot of memory and degrade performance.

Index Of First Ping To Output

name: indexOfFirstPingToOutput, type: Integer, default: -1, minimum: 0, maximum: -1

The output point cloud contains only the beams and samples from pings with indexes [Index Of First Ping To Output, Index Of First Ping To Output + Number Of Pings To Output-1]. Note that not all ping numbers may be part of the given file and not all pings contain valid beam and/or sample data. If Number Of Pings To Output is -1 then an unlimited number is allowed.

Number Of Pings To Output

name: numberOfPingsToOutput, type: Integer, default: -1, minimum: -1

The output point cloud contains only the beams and samples from pings with indexes [Index Of First Ping To Output, Index Of First Ping To Output + Number Of Pings To Output-1]. Note that not all ping numbers may be part of the given file and not all pings contain beam and/or sample data. If Number Of Pings To Output is -1 then an unlimited number is allowed.

Index Of First Beam To Output

name: indexOfFirstBeamToOutput, type: Integer, default: 0, minimum: 0, maximum: 2048

The output point cloud contains only samples of beams with indexes [Index Of First Beam To Output, Index Of First Beam To Output + Number Of Beams To Output-1]. If Number Of Beams To Output is -1 then an unlimited number is allowed.

Number Of Beams To Output

name: numberOfBeamsToOutput, type: Integer, default: -1, minimum: -1

The output point cloud contains only samples of beams with indexes [Index Of First Beam To Output, Index Of First Beam To Output + Number Of Beams To Output-1]. If Number Of Beams To Output is -1 then an unlimited number is allowed.

Magnitude Scale

name: magnitudeScale, type: Float, default: 175, minimum: 0, maximum: 4096

Intensity values of the points in the output point cloud are multiplied with this value before passing them to further processing and finally to the output.

Magnitude Threshold

name: magnitudeThreshold, type: Float, default: 175, minimum: 0, maximum: 65536

Each magnitude value found in the file (and possibly compensated with Unify to homogeneous range after TVG) is compared with Magnitude Threshold: values equal or larger are passed through to further operations, all others are skipped.

Magnitude Threshold Percentage

name: magnitudeThresholdPercentage, type: Float, default: 0.26702881, minimum: 0, maximum: 100

Same as Magnitude Threshold only in percent [0,100] of the possible range [0,65536] of signal data.

Actually Used Threshold

name: actuallyUsedThreshold, type: Float, persistent: no

Actually Used Threshold usually will be updated to the value of Magnitude Threshold after loading a file. If, however, the amount of loaded points is larger than Max Num Allowed Points and Auto adapt threshold on too many points is enabled then the loader internally will use another (automatically determined) threshold which is displayed in Actually Used Threshold.

Normalize to a TxPower of 191 dB

name: normalizeTxPowerTo191db, type: Bool, default: FALSE

Experimental: If enabled then the decibel TxPower value from file is taken and a relative factor to 191db is calculated, and all signal values from file are rescaled with this value, otherwise the signal values are taken as they are. For example with a TxPower of 191db, all signal values are left as they are, with TxPower = 192db, they are scaled with 1.26, with TxPower = 194db they are scaled with 1/(1.26*1.26*1.26).

Notes:

Subtract gain from signal values

name: compensateGain, type: Bool, default: TRUE

If enabled then the H0_RxGain value from file member is subtracted from signal values before passing it to the output point cloud intensities, otherwise not.

Auto adapt threshold on too many points

name: autoAdaptThreshold, type: Bool, default: FALSE

If the setting of Magnitude Threshold causes that more points than specified in Max Num Allowed Points would be created and Auto adapt threshold on too many points is on then PCLR2SonicWCLoader will automatically adapt the threshold internally such that the number of points is not exceeded. If Auto adapt threshold on too many points and Max Num Allowed Points cannot be fulfilled then the file load operation is terminated as described in Max Num Allowed Points.

Unify to homogeneous range after TVG

name: unifyTVGResults, type: Bool, default: TRUE

Experimental mode to make signal settings be in the same range after different TVG calculations. If the sonar signal data has been processed with a TVG curve (see “2022-2024-2026 Sonic Operation Manual v6.3r000.pdf”, section 5.8.3 “Time Variable Gain”) or the sonar system itself applies it, the output signal range for each sonar device setting differs. This makes it very difficult to find constant settings for Magnitude Threshold and Magnitude Scale - therefore it is desirable to compensate this and to rescale settings into same range after any TVG. Since the TVG is needed the inverse is estimated only for a constant range:

antiTVGScale = 1 / (RxRange * ((2.0f*RxAbsorption/1000.f)+log10(RxRange)/RxSpreading))

For details about TVG see “2022-2024-2026 Sonic Operation Manual v6.3r000.pdf”, section 5.8.3 “Time Variable Gain”:

TVG = 2*R* alpha/1000 + Sp*log(R) + G

alpha = Absorption Loss db/km

R = Range in metres

Sp = Spreading loss coefficient

G = Gain from Sonar Control setting

For log a logarithm of 10 is used as calculations are in db, R is the distance of each sample position in euclidean space from the sonar device (and not the H0_RxRange from H0 sections as it may be suggested by the manual). Since log10 becomes negative on values smaller 1 in such cases 0 is used instead.

Notes:

Convert Orphaned Beams And Samples

name: convertOrphanedBeamsAndSamples, type: Bool, default: FALSE

If enabled then M1 or M2 sections which have no associated H0 or A1 sections are converted to points anyway by using the first found H0/A1 sections of the data set which usually contains the same data as the (probably) lost ones did. Differing parameters are usually not used for conversion, thus the conversion is usually safe. If disabled then such M1/M2 sections are not converted to points.

Disable value normalization to [0,1]

name: disableNormalization, type: Bool, default: FALSE

If enabled then original values are passed through: magnitude values then will be in [0,65535] and phase values in [-32768,32767]. Otherwise, if Disable value normalization to [0,1] is off then magnitude values will be in [0,1] and phase either from [-1,1] or [0,1], dependent on Scale phase to [-1,1].

Scale phase to [-1,1]

name: scalePhaseToMinus1To1, type: Bool, default: FALSE

If enabled then phase values are scaled to range [-1, 1], otherwise they are scaled to [0,1]. If Disable value normalization to [0,1] is on then phase values are not scaled at all and remain in original range [-32768,32767]; Scale phase to [-1,1] is inactive in this case.

Create point cloud with index coordinates at second output

name: createIndexCloud, type: Bool, default: FALSE

If enabled then a second point cloud with index coordinates is generated and provided at the second output outputPCLObject1, otherwise that output connector is left NULL.

File Dump

name: fileDump, type: String, persistent: no

A textual dump of file sections to inspect file contents. Since a file dump easily can become memory and time consuming it is limited by the settings Max Number Of Packets To Show, Max Number Of Beams To Show, and Max Number Of Samples Per Beam To Show.

Max Allowed File Size In MBytes

name: maxAllowedFileSizeInMBytes, type: Integer, default: 250, minimum: -1

To avoid out-of resource problems when operating on large R2Sonic .wc water column files, a maximum file size can be specified. All files larges than the limits will be handled as an error, data load is refused and Status is set appropriately. -1 allows any file size.

Max Num Allowed Points

name: maxNumAllowedPoints, type: Integer, default: 32000000, minimum: -1

To avoid out-of resource problems when operating on large R2Sonic(.wc) files, a maximum number of result points can be specified. Knowing that one point needs around 64 bytes this can help the user to define a maximum number of points which can be handled safely on a system. All settings resulting in more points will be handled as an error, no points are created and Status is set appropriately. -1 allows any number of points regardless of available resources.

Working Memory Hint In MBytes

name: workingMemoryHintInMBytes, type: Integer, default: 5000, minimum: 0

A hint for the loader how much working memory (in megabytes) can be used. This, for example, allows using less memory at the expense of loading time. As a general hint, working memory larger than a loaded file size are very beneficial, however, not more than 30% of the physically available memory should be spent. Note that this only a hint and no obligatory limit.

Min Valid Second

name: minValidSecond, type: Integer, default: 0, minimum: 0

The second after 1st of January 1970 which H0_TimeSeconds must have at least to be accepted as valid. If H0_TimeSeconds is older then something is probably broken, for example the data/date connections to the sonar which created the data, did not deliver a valid date/time setting. As an example the second 1135296000 could be used, because it is roundabout year 2006 when R2Sonic was founded (= 365 x (36 years after 1970) x 24 x 3600 secs/h). Since R2Sonic devices did not create sensible data sets before, either the data creation unit did not deliver correct dates or the data set is invalid for other unknown reasons. If a sonar device does not have a valid time source then 0 should be used to accept all data sets.

Angle Of First Ping In Degree

name: angleOfFirstPingInDegree, type: Float, default: -90, minimum: -400, maximum: 400

A ping contains a number of beams with each one a number of samples which result to a swath in 3D. The orientation of the swath is not defined in the WaterColum data. Therefore the angle over ground of the first swatch is defined with this angle.

Angle Offset Per Ping In Degree

name: angleOffsetPerPingInDegree, type: Float, default: 3, minimum: -400, maximum: 400

Angular difference between two neighbor ping swaths. As described for Angle Of First Ping In Degree each ping results to a swath in 3D. If a sonar device has a rotating head multiple swaths can result to a half sphere where all ping related swaths have a small angle difference. This difference/offset between swaths is defined with Angle Offset Per Ping In Degree. This value is used only if Auto Calculate Angle Offset Per Ping is off, otherwise it is insensitive.

Auto Calculate Angle Offset Per Ping

name: autoCalculateAngleOffsetPerPing, type: Bool, default: FALSE

If enabled then Angle Offset Per Ping In Degree is ignored and the value is determined from Full Rotator Range In Degree and the number of pings found in file, otherwise it is taken from Angle Offset Per Ping In Degree.

Full Rotator Range In Degree

name: fullRotatorRangeInDegree, type: Float, default: 360, minimum: -400, maximum: 400

Rotation angle of sonar rotator in degree for a full scan of multiple swaths; only used if Auto Calculate Angle Offset Per Ping is on, otherwise unused and insensitive.

Actually Used Angle Offset Per Ping In Degree

name: actuallyUsedAngleOffsetPerPingInDegree, type: Float, persistent: no

Output only field displaying the actually used angle offset between two pings/swaths, determined as described in Auto Calculate Angle Offset Per Ping.

Mount Plane Tilt Offset In Degree

name: mountPlaneTiltOffsetInDegree, type: Float, default: 0, minimum: -360, maximum: 360

Angle added to beam angles before calculating the sample position in cartesian coordinates. Changing this angle rotates a ping swath in its plane.

Add H0_RxMountTilt to Mount Plane Tilt

name: addRxMountTiltToOffset, type: Bool, default: FALSE

If enabled the angle of file member RxMountTilt is added to Mount Plane Tilt Offset In Degree while creating points from file samples, otherwise the information from RxMountTilt is ignored.

Stop

name: stop, type: Trigger

Sensitive only while loading a file; if pressed then the load or update operation is interrupted as soon as possible. The current operation will finalize with an interruption error in this case.

PacketName

name: PacketName, type: String, persistent: no

Name of WaterColumn packet, usually ‘WCD0’. It is the value of the first packet found in file.

PacketSize

name: PacketSize, type: Integer, persistent: no

[bytes] The size of the WaterColumn ‘WCD0’ section in bytes. It is the value of the first section found in file.

DataStreamID

name: DataStreamID, type: Integer, persistent: no

Reserved for future use. It is the value of the first section found in file.

H0_SectionName

name: H0_SectionName, type: String, persistent: no

Name of WaterColumn H0 section, usually ‘H0’. It is the value of the first section found in file.

H0_SectionSize

name: H0_SectionSize, type: Integer, persistent: no

[bytes] The size of the WaterColumn H1 section in bytes. It is the value of the first section found in file.

H0_ModelNumber

name: H0_ModelNumber, type: String, persistent: no

[12 characters] Model number of the sonic device, for example “2024”, unused chars are shown dotted. It is the value of the first section found in file.

H0_SerialNumber

name: H0_SerialNumber, type: String, persistent: no

[12 characters] Serial number of the sonic device, for example “100017”, unused chars are shown dotted. It is the value of the first section found in file.

H0_TimeSeconds

name: H0_TimeSeconds, type: Integer, persistent: no

[seconds] Ping time in seconds, relative to 0000 hours 1-Jan-1970, integer part. It is the value of the first section found in file.

H0_TimeNanoseconds

name: H0_TimeNanoseconds, type: Integer, persistent: no

[nanoseconds] Ping time in nanoseconds relative to 0000 hours 1-Jan-1970, fraction part. It is the value of the first section found in file.

H0_PingNumber

name: H0_PingNumber, type: Integer, persistent: no

[integer] Pings since power-up or reboot. It is the value of the first section found in file.

H0_PingPeriod

name: H0_PingPeriod, type: Float, persistent: no

[seconds] Time between most recent two pings in seconds. It is the value of the first section found in file.

H0_SoundSpeed

name: H0_SoundSpeed, type: Float, persistent: no

[meters per second] Sound speed in meters per second. It is the value of the first section found in file.

H0_Frequency

name: H0_Frequency, type: Float, persistent: no

[hertz] Sonar center frequency in hertz. It is the value of the first section found in file.

H0_TxPower

name: H0_TxPower, type: Float, persistent: no

[dB re 1 uPa at 1 meter]. It is the value of the first section found in file.

H0_TxPulseWidth

name: H0_TxPulseWidth, type: Float, persistent: no

[seconds] It is the value of the first section found in file.

H0_TxBeamwidthVert

name: H0_TxBeamwidthVert, type: Float, persistent: no

[radians] Width of a beam in radians. It is the value of the first section found in file.

H0_TxBeamwidthHoriz

name: H0_TxBeamwidthHoriz, type: Float, persistent: no

[radians] Height of a beam in radians. It is the value of the first section found in file.

H0_TxSteeringVert

name: H0_TxSteeringVert, type: Float, persistent: no

[radians] It is the value of the first section found in file.

H0_TxSteeringHoriz

name: H0_TxSteeringHoriz, type: Float, persistent: no

[radians] It is the value of the first section found in file.

H0_TxMiscInfo

name: H0_TxMiscInfo, type: Integer, persistent: no

Reserved for future use. It is the value of the first section found in file.

H0_VTX_Plus_Offset

name: H0_VTX_Plus_Offset, type: Integer, persistent: no

[hundredths of a dB] transmit voltage offset at time of ping (divide value by 100 to get dB). It is the value of the first section found in file.

H0_RxBandwidth

name: H0_RxBandwidth, type: Float, persistent: no

[hertz]. It is the value of the first section found in file.

H0_RxSampleRate

name: H0_RxSampleRate, type: Float, persistent: no

[hertz] Sample rate of data acquisition and signal processing in hertz.

H0_RxRange

name: H0_RxRange, type: Float, persistent: no

[meters] Sonar range setting in meters. It is the value of the first section found in file.

H0_RxGain

name: H0_RxGain, type: Float, persistent: no

[multiply by two for relative dB]. It is the value of the first section found in file.

H0_RxSpreading

name: H0_RxSpreading, type: Float, persistent: no

[dB (times log range in meters)] The ocean setting describing the loss of intensity of a sound wave, due to dispersion of the wave front in dB (times log range in meters). It is the value of the first section found in file.

H0_RxAbsorption

name: H0_RxAbsorption, type: Float, persistent: no

[dB per kilometer] The ocean setting describing the absorption in dB per kilometer. It is the value of the first section found in file.

H0_RxMountTilt

name: H0_RxMountTilt, type: Float, persistent: no

[radians]. It is the value of the first section found in file.

H0_RxMiscInfo

name: H0_RxMiscInfo, type: Integer, persistent: no

Reserved for future use. It is the value of the first section found in file.

H0_reserved

name: H0_reserved, type: Integer, persistent: no

Reserved for future use. It is the value of the first section found in file.

H0_Beams

name: H0_Beams, type: Integer, persistent: no

Number of beams per ping. It is the value of the first section found in file.

A1_SectionName

name: A1_SectionName, type: String, persistent: no

[UInt16] Name of WaterColumn A1 section, usually ‘A1’. It is the value of the first section found in file.

A1_SectionSize

name: A1_SectionSize, type: Integer, persistent: no

[UInt16] The size of the WaterColumn A1 section in bytes. It is the value of the first section found in file.

A1_MoreInfo

name: A1_MoreInfo, type: String, persistent: no

[Float32][6] Reserved for future use. It is the value of the first section found in file.

A1_BeamAngle

name: A1_BeamAngle, type: String, persistent: no

[Float32*H0_Beams] [radians] Angle of beam relative to array centerline, ordered from port to starboard, first angle < last angle in radians. It is the value of the first section found in file.

Mx_SectionName

name: Mx_SectionName, type: String, persistent: no

Uint16-coded name of section (‘M1’ or ‘M2’) shown as string in this field. It is the value of the first section found in file.

Mx_SectionSize

name: Mx_SectionSize, type: Integer, persistent: no

[UInt16] The size of the WaterColumn M1 or M2 section in bytes. It is the value of the first section found in file.

Mx_PingNumber

name: Mx_PingNumber, type: Integer, persistent: no

[UInt32] The number of pings since power-up or reboot of the sonar device. It is the value of the first section found in file.

Mx_ScalingFactor

name: Mx_ScalingFactor, type: Float, persistent: no

[Float32] Reserved for future use. It is the value of the first section found in file.

Mx_TotalSamples

name: Mx_TotalSamples, type: Integer, persistent: no

[UInt32] Range samples in entire ping, sample rate is H0_RxSampleRate. It is the value of the first section found in file.

Mx_FirstSample

name: Mx_FirstSample, type: Integer, persistent: no

[UInt32] First sample of this section. It is the value of the first section found in file.

Mx_Samples

name: Mx_Samples, type: Integer, persistent: no

[UInt16] Number of samples in this section. It is the value of the first section found in file.

Mx_TotalBeams

name: Mx_TotalBeams, type: Integer, persistent: no

[UInt16] Number of Beams (always a multiple of 2) (typically columns in your memory buffer). It is the value of the first section found in file.

Mx_FirstBeam

name: Mx_FirstBeam, type: Integer, persistent: no

[UInt16] First beam of this section (always a multiple of 2). It is the value of the first section found in file.

Mx_Beams

name: Mx_Beams, type: Integer, persistent: no

[UInt16] Number of beams in this section (always a multiple of 2). It is the value of the first section found in file.

Mx_reserved0

name: Mx_reserved0, type: Integer, persistent: no

[UInt32] Reserved for future use. It is the value of the first section found in file.

Mx_reserved1

name: Mx_reserved1, type: Integer, persistent: no

[UInt32] Reserved for future use. It is the value of the first section found in file.

Hidden Fields

applyTVG

name: applyTVG, type: Bool, default: FALSE

If checked then each magnitude value found in the file is transformed with the Time Variable Gain (TVG). If applied then the original signal data is scaled with the formula described below, even before scaling with Magnitude Scale and thresholding with Magnitude Threshold is applied. Note that the signal data from a sonar device is usually already transformed with the TVG, so enable this only after ensuring that the data is still not transformed. The used TVG formula is as described in “2022-2024-2026 Sonic Operation Manual v6.3r000.pdf”, section 5.8.3 “Time Variable Gain”:

TVG = 2*R* alpha/1000 + Sp*log(R) + G

alpha = Absorption Loss db/km

R = Range in metres

Sp = Spreading loss coefficient

G = Gain from Sonar Control setting

For log a logarithm of 10 is used as calculations are in db, R is the distance of each sample position in euclidean space from the sonar device (and not the H0_RxRange from H0 sections as it may be suggested by the manual). Since log10 becomes negative on values smaller 1 in such cases 0 is used instead.

numberOfPingsInFile

name: numberOfPingsInFile, type: Integer, default: 0

Hidden field indicating the number of pings found in the loaded file. It is used to define that maximum range for the Index Of First Ping To Output slider.

progress

name: progress, type: Float, default: 0

Shows roughly how much the current load or update operation has proceeded.