MB-System Unix Manual Page: mbvelocitytool

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

    mbvelocitytool
    Section:  MB-System 5.0  (1)
    Updated:  26 October 2009
    Index

    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. 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 throught 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(l), mbprocess(l), mbset, mbsvplist,
    mbbath, mblevitus(l),
    mbm_xbt(l), mbm_xbt(l)

    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.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    INTERACTIVE CONTROLS
    SEE ALSO
    BUGS

Last Updated: 26 October 2009

Return to list of MB-System manual pages...

Back to MB-System Home Page...