mergeOpWave

Description

mergeOpWave is a utility designed to merge Optech LASER Bathymetry waveform data (stored in a custom binary format) with corresponding Optech bottom detections (stored in OMG-HDCS merged files). It synchronizes waveform traces to individual beam records in the merged file based on timestamps and then stores pointers to the waveform data within the beam structure.

This tool is essential for linking the detailed waveform information to the final detected depths, allowing for more advanced analysis of bottom detection confidence, water column properties, and seafloor characteristics.

Usage

mergeOpWave -bathy <bathyfilename(s)> -waves <wavefilename(s)>

Arguments

Option	Description
-bathy <bathyfilename(s)>	Required. One or more paths to input OMG-HDCS merged files (containing Optech bottom detections). These files are modified in place.
-waves <wavefilename(s)>	Required. One or more paths to input binary waveform files (generated by readOpWave). These files contain the waveform trace data.
-v	Enable verbose output.

How It Works

1. Initialization: Defines global variables, file handles, and structures for Optech waveform data (optech_waveform) and waveform file bounds (wave_file_bounds).
2. Waveform File Processing: Loops through each specified binary waveform file (-waves):
   • Opens the .wave file and its corresponding .16_data file (which contains the actual 16-bit waveform traces).
   • Reads the first optech_waveform record to get min_timestamp.
   • Seeks to the end of the .wave file to determine no_recs and max_timestamp.
   • Allocates memory for wave_details[i] (an array of optech_waveform structures) and loads all waveform details from the .wave file into memory.
3. Bathy File Processing: Loops through each specified bathy (OMG-HDCS merged) file (-bathy):
   • Opens the merged file for reading and writing (r+).
   • Reads the summary header.
   • Timestamp Range Check: Approximates the timestamp range of the merged file’s first and last beams.
   • Waveform File Intersection: For each waveform file, it checks if its time bounds (wavebound[k]) intersect with the current merged file’s time bounds using wave_intersects_bathy.
   • Profile and Beam Iteration: If intersection is found, it iterates through each profile (ping) in the merged file, and then through each beam within that profile:
     • Reads the profile header and raw beams.
     • Timestamp Synchronization: Calculates a precise timestamp (dtimestamp) for the current beam’s bottom strike using profile.laser_timestampRef and beams[j].timestampOffset.
     • Waveform Record Search: If dtimestamp falls within the time bounds of an intersecting waveform file, it calls search_for_closer_timestamp to find the wave_record (index) in wave_details[k] that best matches dtimestamp.
     • Waveform Data Merging: If a matching wave_record is found:
       • Sets beams[j].offset to the PMT_byte_offset from the wave_details record, which points to the waveform trace in the .16_data file.
       • Sets beams[j].no_PMT, no_GAPD, no_IR, no_RAMAN from the wave_details record.
       • Note: The actual 16-bit waveform data (data16) is read from the .16_data file and written to an auxiliary .waveform file associated with the merged file. beams[j].offset then points to this new location. This suggests a two-step process: readOpWave creates the .wave and .16_data files, and mergeOpWave re-organizes the actual waveform data into a new .waveform file that’s linked from the merged file.
     • Write Back: The modified beams (with updated waveform pointers) are written back to the merged file.
4. Cleanup: Closes all open files and frees allocated memory.

Output Files

The input merged files (-bathy) are modified in-place, updating beam structures with pointers to waveform data. An auxiliary .waveform file is created.

Helper Functions

• wave_intersects_bathy(): Checks if the time range of a waveform file overlaps with the time range of a bathy file.
• search_for_closer_timestamp(): Searches for the closest matching optech_waveform record based on dtimestamp.

Dependencies

• OMG_HDCS_jversion.h: For OMG-HDCS data structures.
• support.h: For general utility functions and error handling.
• Optech_waveform.h: For optech_waveform data structure and related functions.

Notes

This tool is crucial for integrating raw waveform data with processed bottom detections, enabling more detailed analysis of the Optech SHOALS data. The two-step process (waveform extraction by readOpWave and merging by mergeOpWave) is necessary due to the structure of the data. As the tool modifies merged files in-place, backups are highly recommended.