mbvelocitytool(1)

NAME
mbvelocitytool - Interactive water sound velocity profile editor.

VERSION
Version 5.0

SYNOPSIS
mbvelocitytool [-Byr/mo/da/hr/mn/sc -Eyr/mo/da/hr/mn/sc -Fformat -Ifile -Ssvpfile -Wsvpfile -V -H]

DESCRIPTION
MBvelocitytool is an interactive water sound velocity profile (SVP) editor used to examine multiple SVPs, to create new SVPs, and to model the impact of SVP modification on swath bathymetry data. SVPs created using MBvelocitytool can be used by the program mbprocess to recalculate swath bathymetry from raw travel time and angle data. In general, MBvelocitytool is used to examine SVPs obtained from swath data files (see mbsvplist manual page), XBTs, CTDs, or databases, and to construct new profiles consistent with these various sources of information. The SVPs are represented by a set of paired depth and velocity values which are connected by linear interpolation. Users may load a number of SVPs for display. Users may load or create a single editable SVP and then interactively modify this profile. When users load swath bathymetry data containing raw travel time and angle data (many but not all swath data format include this information), MBvelocitytool recalculates the bathymetry by raytracing through the current SVP model. If the bathymetry in the input swath file has been edited (e.g. with mbedit), then the associated edit save file (*.esf file) will be loaded as well, and the beams flagged as bad will not be used by MBvelocitytool. The bathymetry of each ping is fit with a line, and bathymetry residuals are calculated for each good beam relative to the linear fit. The average of the bathymetry residuals is displayed along with "error bars" indicating the standard deviations of the residuals. Anomalously shallow bathymetry maps into negative residuals and deep bathymetry into positive residuals; the residuals are displayed so that shallow is up and deep is down. If the seafloor is reasonably smooth so that a linear fit is appropriate, then the residuals will accurately reflect any problems with the water velocity profile. If the water velocity profile is correct, then the residual plot will be roughly flat. If the water velocity profile is significantly in error, then the outer beam depths may anomalously shallow (edge curl up) or deep (edge curl down). In practice, the editable velocity profile is altered interactively until a reasonably residual pattern is achieved. In order to calculate bathymetry values from travel time observations, geometrical raypaths are traced through the SVP for each beam. Because the sound velocity gradients are uniform between the depth-velocity nodes (linear interpolation), the raypaths are be calculated analytically as pieces of circular arcs. This raytracing algorithm is the same used in the program mbprocess. One important aspect of the raytracing is the handling of the initial takeoff angles associated with each beam or sounding. In general, the raytracing will begin at a point in the sound speed model that has a sound velocity different than the surface sound velocity (SSV) used by the mapping sonar for the original beamforming. The usual approach is to use Snell's law to adjust the starting angle for this change in sound velocity. This amounts to an assumption that the original SSV was correct and that the rays pass through an insignificantly thick layer in which the sound speed equals the SSV before transitioning to the sound speed implied by the SVP. This is the default setting for raytracing in MB-System. Alternatively, one can proceed with raytracing using the original angle but this is rarely useful or correct. Finally, if the SSV used by the sonar is judged to have been incorrect, then the takeoff angle must be corrected for the erroneous beamforming as well as for the difference between the SSV and the initial raytracing sound velocity. This correction must take the sonar geometry into account because the impact of changing the SSV on a beam angle from a flat receive array is very different from a V-shaped or curved array. All three of these angle correction modes are available in mbvelocitytool. MBvelocitytool can be used in conjunction with mbprocess. If the user uses the Save swath svp file option to save an SVP model developed through the analysis of a particular swath data file, MBvelocitytool also sets the associated mbprocess parameter file so that mbprocess recalculates the bathymetry using the new SVP model. The program mbset may be used to set the SVP file in the parameter file for any swath data file. Users may also save SVP models without setting any mbprocess parameters by using the Save editable profile option. Sometimes the bathymetry residuals show structure indicative of persistent artifacts in the bathymetry (e.g. certain parts of the swath may be persistently shallower or deeper than the rest of the swath). In this situation, it is possible to export the residuals and to then apply them in mbprocess as static corrections to the bathymetry. This is accomplished by using the Save residuals as offsets option under the File menu. If a user attempts to read in swath bathymetry that does not contain the travel time and beam angle data required for bathymetry recalculation, MBvelocitytool will estimate the travel times and angles from the bathymetry by assuming a 1500 m/s half-space (and then post a warning dialog). Although the user can proceed to model bathymetry recalculation by modifying the active SVP just as with proper data, the travel times and angles are not in general correct and so the modeling and any results it gives are, well, bogus. A more useful approach is to leave the SVP alone and simply export the residuals to be applied as static corrections in mbprocess. This approach allows users a practical means of correcting older multibeam bathymetry that was originally calculated with an incorrect SVP but which contains no travel time or angle data.

AUTHORSHIP
David W. Caress (caress@mbari.org)
  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)
  Lamont-Doherty Earth Observatory

OPTIONS

-B  yr/mo/da/hr/mn/sc
    Sets the starting time for data allowed in the input data; pings with times before the starting time will be ignored. Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.

-E  yr/mo/da/hr/mn/sc
    Sets the ending time for data allowed in the input data; pings with times after the ending time will be ignored. Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.

-F  format
    Sets the format at startup for the input and output swath sonar data using MBIO integer format identifiers. This value can also be set interactively when specifying the input file. This program uses the MBIO library and will read any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. Default: format = 11.

-H  This "help" flag cause the program to print out a description of its operation and then exit immediately.

-I  file
    Sets the data file from which the input swath data will be read at startup. This value can also be set interactively. See below.

-S  svpfile
    Sets the data file from which an input display sound velocity profile will be read at startup. See below. This value can also be set interactively.

-W  svpfile
    Sets the data file from which an input editable sound velocity profile will be read at startup. This value can also be set interactively. See below.

-V  Normally, mbvelocitytool works "silently" without outputting anything to the stderr stream. If the -V flag is given, then mbvelocitytool works in a "verbose" mode and outputs the program version being used, all error status messages, and a large amount of other information.

INTERACTIVE CONTROLS

File
    This button brings up a menu containing the commands listed below:

File->Open Display Profile
    Selecting this menu item brings up a popup window which allows the user to select an input water velocity profile file. The profile will be displayed in a depth vs velocity plot along with other display profiles and the edit velocity profile, if one has been opened. Up to ten display velocity profiles may be loaded; the color of the display profiles cycles through red, green, blue, and black in the order that they are loaded.

File->Open Editable Profile
    Selecting this menu item brings up a popup window which allows the user to select an input water velocity profile file to be edited. The profile will be displayed in a depth vs velocity plot along with any display profiles that have been opened. This profile will be plotted as black lines with small black squares at the velocity depth points. The velocity depth points may be selected and dragged using the mouse to change the editable velocity profile.

File->New Editable Profile
    Selecting this menu item creates a default editable velocity profile consisting of 14 velocity-depth points with a velocity of 1500 m/s. Any previously defined editable velocity profile will disappear. The profile will be displayed in a depth vs velocity plot along with any display profiles that have been opened. This profile will be plotted as black lines with small black squares at the velocity depth points. The velocity depth points may be selected and dragged using the left mouse button to change the editable velocity profile. The center mouse button adds new velocity-depth points, and the right mouse button removes velocity-depth points.

File->Save Editable Profile
    Selecting this menu item brings up a popup window which allows the user to save the current editable velocity profile as a file.

File->Open Swath Sonar Data
    Selecting this menu item brings up a popup window which allows the user to select an input swath sonar data file to be processed in conjunction with the current editable velocity profile. The format id for the data file must be set appropriately in the editable text widget labeled "MBIO Format ID:"; this program uses the MBIO library and will read or write any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. If the swath sonar data file is named using the MB-System suffix convention (format 11 files end with ".mb11", format 41 files end with ".mb41", etc.), then the program will automatically use the appropriate format id. The swath sonar data file must be in one of the formats which store travel time data for each beam. Up to 25000 data records will be read into a buffer for processing. If there is no current editable velocity profile, then a default profile consisting of 14 velocity-depth points with a velocity of 1500 m/s will be created. A display profile generated by the mblevitus program will also be automatically generated and loaded into mbvelocitytool; this Levitus profile will serve as an average reference for the water sound velocity structure at the location of the swath data being analyzed. The travel time data will then be processed and displayed in the manner described below for the Reprocess button.

File->Save Swath SVP File
    Selecting this menu item saves the current editable velocity profile as a file. The SVP filename is that of the current swath data input file with a ".svp" suffix added. MBvelocitytool also sets the swath data file's mbprocess parameter file to recalculate bathymetry using the new SVP file and using the same angle mode setting applied in the interactive modeling (see the Angle Mode dialog description below).

File->Save Residuals As Offsets
    Selecting this menu item saves the current bathymetry residuals as a "static bathymetry offset" file. The filename is that of the current swath data input file with a ".sbo" suffix added. MBvelocitytool also sets the swath data file's mbprocess parameter file to apply these residuals as static corrections to the bathymetry.

Plot Scaling
    This button brings up a dialog containing the three controls discussed immediately below.

Plot Scaling->Maximum Depth
    This slider sets the maximum depth in meters of both the velocity profile display and the raypath display. The minimum depths of these displays are always zero. The acrosstrack distance axis of the raypath display automatically adjusts so that the rays are plotted with no vertical exageration.

Plot Scaling->Velocity Range
    This slider sets the minimum and maximum velocity values of the velocity profile display. The minimum value is the velocity center minus the velocity range; the maximum value is the velocity center plus the velocity range.

Plot Scaling->Velocity Center
    This slider sets the center velocity value of the velocity profile display. The minimum value is the velocity center minus the velocity range; the maximum value is the velocity center plus the velocity range.

Plot Scaling->Residual Range
    This slider sets the minimum and maximum bathymetry residual values of the bathymetry residual display. The residual plot has a minimum value of -range and a maximum value of +range.

Angle Mode
    This button brings up a dialog containing three choices for how the starting beam angles are corrected during raytracing. The selected angle mode is used by mbvelocitytool in the interactive modeling, and is also passed on to the mbprocess parameter file created or modified when an SVP file is saved.

Angle Mode->Do Not Change Beam Angles
    This button sets the angle mode so that the starting beam angles are not corrected before raytracing for the difference between the surface sound velocity (SSV) and the sound velocity of the starting depth in the SVP.

Angle Mode->Adjust Angles Using Snell's Law
    This button sets the angle mode so that the starting beam angles are corrected before raytracing, using Snell's Law, for the difference between the surface sound velocity (SSV) and the sound velocity of the starting depth in the SVP. This amounts to an assumption that the original SSV was correct and that the rays pass through an insignificantly thick layer in which the sound speed equals the SSV before transitioning to the sound speed implied by the SVP. This is the default setting for raytracing in mbvelocitytool and in MB-System in general.

Angle Mode->Adjust Angles Using Sonar Geometry
    This button sets the angle mode so that the starting beam angles are corrected before raytracing, using Snell's Law and the sonar geometry, for the difference between the surface sound velocity (SSV) and the sound velocity of the starting depth in the SVP. This option is relevant to situations where the SSV used by the sonar for beamforming was incorrect, and so the initial angles themselves must be adjusted. This mode is indistinguishable from that of "Adjust Angles Using Snell's Law" for multibeam sonars with flat, horizontal receive arrays, but deviates strongly for sonars with tilted, V-shaped, or curved receive arrays.

Reprocess
    Selecting this button causes the swath sonar travel time data to be processed into bathymetry using the current editable velocity profile. The processing involves full raytracing through the water velocity model. The bathymetry of each ping is fit with a line, and bathymetry residuals are calculated for each good beam relative to the linear fit. The average of the bathymetry residuals is displayed in the upper right part of the window as a function of beam number, along with "error bars" indicating the standard deviations of the residuals. Raypaths are displayed without vertical exageration in the lower part of the window; these represent the first raypath calculated for each beam while processing the current data (most will be from the first ping). Anomalously shallow bathymetry maps into negative residuals and deep bathymetry into positive residuals; the residuals are displayed so that shallow is up and deep is down. If the seafloor is reasonably smooth so that a linear fit is appropriate, then the residuals will accurately reflect any problems with the water velocity profile. If the water velocity profile is correct, then the residual plot will be roughly flat. If the water velocity profile is significantly in error, then the outer beam depths may anomalously shallow (edge curl up) or deep (edge curl down). In practice, the editable velocity profile is altered interactively until a reasonably residual pattern is achieved; reference velocity profiles obtained from CTD casts, XBT's, or data bases (see manual page for program mblevitus) may be read in as display profiles to guide the editing process.

Quit
    This button causes the program to exit gracefully, but without asking any questions. If you haven't already saved your edited velocity profile it will be lost when you quit.

SEE ALSO
mbsystem(1), mbprocess(1), mbset, mbsvplist, mbbath, mblevitus(1), mbm_xbt(1), mbm_xbt(1)

BUGS
Users cannot remove display sound velocity profiles from the screen once they are read in. The main window for mbvelocitytool is too large for use on screens smaller than 1024 X 768 pixels.