layout: default title: applySectBP parent: OMG Tools nav_order: 78 —

applySectBP

Description

applySectBP is a utility designed to apply sector-specific beam pattern (BP) corrections directly to sidescan (SS) trace data or reflectivity values within OMG-HDCS merged files. This tool acts as an intermediary processing step, allowing the removal of angular response effects (either Sonar Relative Angle (SRA) or Vertically Referenced Angle (VRA)) before other processing steps, thereby “de-corrupting” the SS data.

It reads beam patterns from files generated by newGetBP (single or multi-sector) and applies them as a gain correction to each sidescan sample or reflectivity value. The corrected data is then written to a new .ss_data_deSRA or .ss_data_deVRA file, or it updates the reflectivity field in the merged file.

Usage 

applySectBP <input_omg_file(.merged)> [OPTIONS]

Arguments

Option Description  
<input_omg_file(.merged)> Required. The path to the input OMG-HDCS merged file.  
-v Enable verbose output.  
-AUV_draft Use AUV draft calculation (may override WLZ-Zloc draft).  
-draft <val> Specifies the draft (in meters) to use for launch angle calculations. Auto-calculated from .param.
-ymount <val> Specifies the Y-mount offset (in meters) to use for launch angle calculations. Auto-calculated from .param.
-SRA Apply corrections based on Sonar Relative Angle (SRA). This implies -sonar_relative.  
-VRA Apply corrections based on Vertically Referenced Angle (VRA).  
-apply_to_REFL Apply the BP correction directly to the reflectivity field of the beams in the merged file, instead of writing a new .ss_data file.  
-use_deTVG Indicates that the input sidescan file is already de-TVG corrected (e.g., .ss_data_deTVG).  
-sonar_relative Forces sonar-relative angle calculation (redundant if -SRA is used).  
-multi_sector_bp <filename> Specifies a multi-sector beam pattern file (output from newGetBP) to use for corrections.  
-Apply_ACROSS_track_RBP_before_making_ss <filename> Specifies a file for applying across-track Receiver Beam Pattern (RBP) corrections.  
-Apply_ALONG_track_RBP_before_making_ss <filename> Specifies a file for applying along-track Receiver Beam Pattern (RBP) corrections.  
-SR_ATBP_ignore_within <deg> Ignores the RBP correction within a specified sonar-relative incidence angle range (e.g., to ignore nadir).  
-DN_offset <val> Applies a constant Digital Number (DN) offset to the sidescan values after BP correction.  

Beam Pattern Source

| Option | Description | |—|—| | -beam_patt <filename> | Specifies a single beam pattern file to apply (used if multi_sector_bp is not used). |

How It Works

  1. Initialization & Argument Parsing: Sets up various flags and parameters for angle calculation, BP source, and output type.
  2. File Setup:
    • Opens the input merged file (.merged).
    • Reads sonar_settings and .param files to get sonar configuration, draft_to_use, and yoffset_to_use.
    • Opens the .sectors file to read transmit sector definitions.
    • Opens the .orientation file to get attitude information for SRA/VRA calculations.
    • Loads the beam pattern(s) (EM1000_Beam_Pattern, The_Sector_Beam_Pattern, The_Sector_Beam_Pattern_Across_SRBP, The_Sector_Beam_Pattern_Along_SRBP) based on chosen options (-beam_patt, -multi_sector_bp, -Apply_ACROSS_track_RBP_before_making_ss, etc.).
  3. Output File Configuration:
    • If -apply_to_REFL is not used, it opens the input .ss_data file (or .ss_data_deTVG if -use_deTVG) for reading and creates a new output .ss_data_deSRA or .ss_data_deVRA file for writing corrected sidescan traces.
  4. Profile Iteration: Loops through each profile (ping) in the merged file:
    • Reads the current profile header and raw beams.
    • Draft/Y-offset Update: Updates draft_to_use if GA_AUV_draft is active.
    • Attitude Time Synchronization: Syncs the current ping’s time with attitude records from the .orientation file for SRA/VRA calculations if necessary.
    • Loads transmit sector definitions for the current ping.
    • Beam Iteration: For each beam within the current ping:
      • Launch Angle Calculation: Calculates the launch_angle (either SRA or VRA) using simple_get_launch_angle based on sonar parameters, draft, y-offset, and attitude.
      • Beam Pattern Gain Retrieval: Retrieves the BP_gain from the loaded beam pattern(s) based on the calculated launch_angle. If multi-sector BP is used, it determines the correct sector’s BP to apply.
      • Apply Correction:
        • If -apply_to_REFL is used, it updates the beams[k].calibratedBackscatter by adding BP_gain and DN_offset.
        • Otherwise, it reads the raw sidescan trace for the beam from the input .ss_data file, applies BP_gain and DN_offset to each sample, and writes the modified trace to the output .ss_data_deSRA or .ss_data_deVRA file.
  5. In-Place Modification (for -apply_to_REFL) or New File Creation:
    • If -apply_to_REFL is used, the merged file is modified in place.
    • Otherwise, a new sidescan data file is created with the corrected traces.

Output Files

  • The input merged file may be modified in-place if -apply_to_REFL is used.
  • A new sidescan data file: <input_omg_file_prefix>.ss_data_deSRA or <input_omg_file_prefix>.ss_data_deVRA.

Dependencies

  • OMG_HDCS_jversion.h: For OMG-HDCS data structures.
  • support.h: For general utility functions and error handling.
  • j_proj.h: For coordinate projection functions.
  • j_generic_beam_pattern.h: For beam pattern structures and loading.
  • j_get_launch_angle.h: For launch angle calculation.

Notes

This tool is crucial for achieving accurate and consistent backscatter data by removing the sonar’s intrinsic angular response. The choice between SRA and VRA correction depends on the sonar system and the specific goals of the backscatter processing. Careful selection of beam pattern files (e.g., from newGetBP) is essential for effective correction.

How It Works

  1. Initialization & Argument Parsing: Sets up various flags and parameters for angle calculation, BP source, and output type.
  2. File Setup:
    • Opens the input merged file (.merged).
    • Reads sonar_settings and .param files to get sonar configuration, draft_to_use, and yoffset_to_use.
    • Opens the .sectors file to read transmit sector definitions.
    • Opens the .orientation file to get attitude information for SRA/VRA calculations.
    • Loads the beam pattern(s) (EM1000_Beam_Pattern, The_Sector_Beam_Pattern, The_Sector_Beam_Pattern_Across_SRBP, The_Sector_Beam_Pattern_Along_SRBP) based on chosen options (-beam_patt, -multi_sector_bp, -Apply_ACROSS_track_RBP_before_making_ss, etc.).
  3. Output File Configuration:
    • If -apply_to_REFL is not used, it opens the input .ss_data file (or .ss_data_deTVG if -use_deTVG) for reading and creates a new output .ss_data_deSRA or .ss_data_deVRA file for writing corrected sidescan traces.
  4. Profile Iteration: Loops through each profile (ping) in the merged file:
    • Reads the current profile header and raw beams.
    • Draft/Y-offset Update: Updates draft_to_use if GA_AUV_draft is active.
    • Attitude Time Synchronization: Syncs the current ping’s time with attitude records from the .orientation file for SRA/VRA calculations if necessary.
    • Loads transmit sector definitions for the current ping.
    • Beam Iteration: For each beam within the current ping:
      • Launch Angle Calculation: Calculates the launch_angle (either SRA or VRA) using simple_get_launch_angle based on sonar parameters, draft, y-offset, and attitude.
      • Beam Pattern Gain Retrieval: Retrieves the BP_gain from the loaded beam pattern(s) based on the calculated launch_angle. If multi-sector patterns are used, it determines the correct sector’s BP to apply.
      • Apply Correction:
        • If -apply_to_REFL is used, it updates the beams[k].calibratedBackscatter by adding BP_gain and DN_offset.
        • Otherwise, it reads the raw sidescan trace for the beam from the input .ss_data file, applies BP_gain and DN_offset to each sample, and writes the modified trace to the output .ss_data_deSRA or .ss_data_deVRA file.
  5. In-Place Modification (for -apply_to_REFL) or New File Creation:
    • If -apply_to_REFL is used, the merged file is modified in place.
    • Otherwise, a new sidescan data file is created with the corrected traces.
  6. Cleanup: Closes all open files.