plotBP

Description

plotBP is a versatile plotting utility designed to visualize multibeam sonar beam patterns and related characteristics. It can read beam pattern data from files generated by getBeamPattern.c or beam footprint files, and then generate plots in various formats: Cartesian, polar, or as a weighting function.

The tool supports advanced features like plotting multiple beam patterns, applying filters (median, average), highlighting specific sectors or traces, and normalizing responses. It’s crucial for analyzing sonar performance, understanding beam shaping, and validating calibration.

Usage

plotBP <files...> [-outfile <filenm>] [OPTIONS]

Arguments

Option	Description
<files...>	Required. One or more input files containing beam pattern or beam footprint data.
-outfile <filenm>	Specifies the output PostScript metafile name.	plot.meta

Input Type

| Option | Description | |—|—| | -bp | Input files are beam patterns (default). | | -foot | Input files are beam footprint files. |

Plotting Type

| Option | Description | |—|—| | -cartes | Generates a Cartesian plot (intensity vs. angle). | | -polar | Generates a polar plot (intensity in radial direction, angle in angular direction). | | -polar_fill | Same as -polar, but fills the area under the curve in the polar plot. |

Display Options

| Option | Description | Default | |—|—| | -size <dx> <dy> | Specifies the plot size in centimeters. | 16.0 20.0 | | -port / -stbd / -both / -wrap | Specifies which side of the swath to plot (port, starboard, both, or wrap-around). | both | | -ref | Plots the reference beam pattern (if available). | | | -invert | Inverts the intensity values (e.g., for plotting attenuation). | | | -multi_sect | Indicates that the input file contains multi-sector beam patterns. | | | -show_refcorr | Shows reference corrected intensity instead of raw intensity. | | | -plot_bandwidth <min> <max> <step> | Plots bandwidth information (typically for multi-sector systems). | | | -flipswaths | (For multi-sector) Attempts to reorder swaths if the first port is > second frequency. | | | -sect_limits <idx> <plot_flag> <min_ang> <max_ang> | Defines angular limits for plotting a specific sector. | | | -roll_bp <val> | Applies a simulated roll to the beam pattern (in degrees). | 0.0 | | -show_lambertian <BSo> <power> | Overlays a Lambertian scattering model with specified BSo (backscatter coefficient) and power. | | | -text_col <val> / -line_col <val> | Sets text and line colors. | 7 (black) / 2 (red) | | -median | Applies a median filter to the beam pattern data. | | | -average | Applies a running average filter to the beam pattern data. | | | -fillzeros | Interpolates zero values in the beam pattern data. | | | -mincount <val> | Only uses data points with a count greater than or equal to val. | | | -fraccount <val> | Only uses data points with a count greater than or equal to val times the average count. | | | -labelcurves | Labels the plotted curves with their filenames. | | | -notext | Suppresses text labels on the plot. | | | -rainbow / -rainbow2 | Uses a rainbow color scheme for multiple curves. | | | -do_thick | Plots thicker lines. | | | -gainup <trace_idx> <db_offset> | Applies a gain offset (db_offset) to a specific trace (trace_idx). | | | -gainall <db_offset> | Applies a bulk gain offset to all traces. | | | -highsector <val> | Highlights a specific sector in multi-sector plots. | | | -highlight <trace_idx> | Highlights a specific trace by making it stand out (e.g., with a different color or marker). | | | -valid_angles <min_ang> <max_ang> | Defines minimum and maximum valid angles for plotting. | -120.0 to 120.0 | | -bigger_text | Uses larger text. | | | -sigrange <min> <max> | Sets the Y-axis range for intensity/backscatter (in dB). | -60.0 to 0.0 | | -refrange <angle> <range_db> | Normalizes intensity values relative to a specified angle or the maximum response. | | | -apart | Plots each beam pattern in a separate subplot within the overall plotting area. | | | -title1 <string> / -title2 <string> | Sets titles for the plot. | |

How It Works

1. Initialization: Parses command-line arguments to configure plotting options, input file types, display styles, and ranges.
2. File Reading Loop: Iterates through each input file:
   • Beam Footprint (-foot): If foot_flag is set, it reads the beam footprint characteristics using load_BF_characteristics (from BeamFoot.h).
   • Beam Pattern (-bp or default): Reads beam pattern data.
     • Multi-sector (-multi_sect): Reads specific header information for each sector, then angle, intensity, reference correction, and count data for each angle bin within each sector (MS_angle, MS_intensity, MS_refcorr, MS_the_count). Applies gainup if specified. Filters data based on mincount or fraccount.
     • Single-sector (default): Reads angle, intensity, reference correction, and count data (angle, intensity, refcorr, the_count). Applies gainup. Filters based on min_valid_angle, max_valid_angle, mincount, fraccount. Can apply fillzeros, average_flag, or median_flag filters. Can adjust intensities based on refrange.
3. Plot Setup: Initializes the plotlib PostScript output. Sets up plot dimensions and offsets. Adds titles.
4. Plotting Loop:
   • Polar Plot (-polar):
     • Draws concentric circles for dB levels and radial lines for angles.
     • Plots the beam pattern by converting angle and intensity values to polar coordinates.
     • If polar_fill is set, it fills the area under the curve in the valid sector limits.
   • Cartesian Plot (-cartes or default):
     • Draws X (angle) and Y (intensity/dB) axes with ticks and labels.
     • Plots the beam pattern as a line graph.
     • Overlays a Lambertian scattering model if show_lambertian is set.
   • Weighting Function Plot (if bp_flag is active): Plots the array weighting function (amplitude vs. element number).
5. Filtering Functions:
   • javerage(float *vals, int novals): Calculates the average of an array of floats.
   • jmedian(float *vals, int novals): Calculates the median of an array of floats.
6. Cleanup: Calls plot_close to finalize the PostScript output.

Output Files

• <outfile_name>: A PostScript metafile (.meta) containing the visualized beam patterns or beam footprint.

Dependencies

• plotlib.h: For plotlib functions.
• support.h: For general utility functions.
• BeamFoot.h: For BeamFoot structure and load_BF_characteristics function (if -foot is used).
• math.h: For mathematical functions.

Notes

plotBP is an essential tool for quality control, calibration, and understanding the performance of multibeam sonar systems. Its ability to display beam patterns in different formats and apply various filters allows for comprehensive analysis of how the sonar measures backscatter across the swath. The tool is flexible for handling both single and multi-sector beam patterns.