plotAngular

Description

plotAngular is a specialized plotting utility designed to visualize angular response data from multibeam sonars. It reads ASCII data files, typically generated by tools like DelayEditor or other tools that output similar ASCII data. It plots backscatter strength (or other quantities) versus angle, typically displaying mean values and standard deviations.

The tool supports various input file formats, allows for plotting multiple datasets on the same graph, and offers customizable plot ranges and titles.

Usage 

plotAngular <infile(s)> [-outfile <filename.meta>] [-size <dx> <dy>] [-yrange <min> <max>] [OPTIONS]

Arguments

Option Description  
<infile(s)> Required. One or more paths to input ASCII files containing angular response data.  
-outfile <filename.meta> Specifies the output PostScript metafile name. plot.meta
-size <dx> <dy> Specifies the total plot size in centimeters (X and Y dimensions). 15.0 22.0
-yrange <min> <max> Sets the Y-axis range (backscatter strength in dB). -45.0 to -15.0

File Format Selection (Choose one)

| Option | Description | |—|—| | -jackTool | Interprets the input file as being from jackTool. | | -swathed | Interprets the input file as being from swathed. | | -delayed | (Default) Interprets the input file as being from DelayEditor. |

Plot Customization

| Option | Description | |—|—| | -together | Plots all input files on a single graph, overlapping. | | -sparse | (Not fully implemented) Intended for sparse plotting. | | -tit1 <string> / -tit2 <string> | Sets titles for the plot. | | -v | Enable verbose output. | |

Input File Formats

  • DELAYED (default):
    • For each angle bin (1 to 180): angle average std (double, double, double).
    • If type == 9: tot_used sd_ratio (int, double).
  • JACKTOOL: Not explicitly implemented in the provided code snippet beyond setting file_format.
  • SWATHED: Not explicitly implemented in the provided code snippet beyond setting file_format.

How It Works

  1. Initialization: Parses command-line arguments to set plotting options, file formats, and ranges. Initializes a plotlib PostScript output (plot.meta).
  2. Plot Area Setup: Sets up the overall plot dimensions (xlength, ylength, xoff, yoff). Draws the main plot border.
  3. Title and Labels: If titles are provided, they are added to the plot.
  4. File Reading Loop: Loops through each input file specified:
    • Opens the input ASCII file.
    • Data Loading: Reads angle, average, and std values for 180 angle bins. If type == 9, also reads tot_used and sd_ratio.
    • Y-axis Range Adjustment: Adjusts ymin and ymax if together_flag is not set (to stack plots vertically).
    • Axes and Labels: Draws X and Y axes with labels for “Backscatter Strength (dB)” and “Grazing Angle (degrees)”.
    • Plotting Data: Iterates through j from 0 to 179 (representing angles):
      • Plots average[j] (mean backscatter) as a line.
      • If type != 10 and type != 9, it also plots av_plus[j] and av_minus[j] (mean +/- standard deviation) as lines, representing the spread of the data.
  5. Cleanup: Calls plot_close to finalize the PostScript output and closes input files.

Output Files

  • <outfile.meta>: A PostScript metafile (.meta) containing plots of angular response data.

Dependencies

  • plotlib.h: For plotlib functions.
  • support.h: For general utility functions.
  • math.h: For mathematical functions.

Notes

plotAngular is a versatile tool for visualizing angular response curves, allowing for comparison of different datasets and assessing the mean and variability of backscatter measurements as a function of incidence angle. The tool is designed to work with ASCII data output from various processing tools, making it a flexible component in the data analysis workflow. The JACKTOOL and SWATHED file formats are recognized but their specific parsing logic is not implemented in the provided code snippet. The -sparse option is listed but not implemented.