MB-System Unix Manual Page: mblist

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

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

    NAME

    mblist - List data in swath data files.

    VERSION

    Version 5.0

    SYNOPSIS

    mblist [-A -Byr/mo/da/hr/mn/sc
    -C
    -Ddumpmode
    -Eyr/mo/da/hr/mn/sc -Fformat -Gdelimiter
    -H -Iinfilename -Kdecimate
    -Llonflip -Mstart_beam/end_beam
    -Nstart_pixel/end_pixel
    -Ooutput_format -Ppings -Q
    -Rwest/east/south/north
    -Sspeed -Ttimegap
    -Ucheck -V -W
    -Xoutfile
    -Zsegment]

    DESCRIPTION

    mblist is a utility to list the contents of a swath
    data file or files to stdout. By default, mblist
    produces ASCII files in
    spreadsheet style, with data columns separated by tabs. Alternatively,
    other column delimiters can be used (-G option), or
    the output can be binary, with each field represented
    as a double precision float (-A option).
    Output can also be in netCDF CDL (-C option) format,
    or as a binary netCDF file (-C -A).
    The output of
    mblist can be piped to plotting and data analysis programs. The
    option -Ooutput_format can be
    used to control the data types that
    are sent to stdout. The default is to output a single record for
    each survey ping, and for any output navigation values to reflect
    the sonar or ship navigation. In this mode, any output depth,
    amplitude, or sidescan values are derived from the beam and pixel
    located closest to the navigation (the most vertical position under
    the sonar). If the -M or -N options
    are used to set specific ranges of beams or pixels to be used,
    then records are output for each of the specified beams or
    pixels and any navigation, depth or sidescan values output reflect
    the positions and values of the specified beams or pixels.
    The data input may be averaged or windowed in time
    and space before it is listed.  Complete dumps of bathymetry,
    amplitude, or sidescan data are possible as well.

    AUTHORSHIP

    David W. Caress (caress@mbari.org)

      Monterey Bay Aquarium Research Institute

    Dale N. Chayes (dale@ldeo.columbia.edu)

      Lamont-Doherty Earth Observatory

    Alberto Malinverno

      Schlumberger-Doll

    OPTIONS

    -A

    Causes the output to be binary (native double precision floating
    point) rather than ASCII. Some
    output options cannot be represented as single binary floats (e.g.
    time strings and longitude or latitude broken into degrees
    and minutes. These values are output as multiple fields as
    appropriate.
    Default: ASCII output with fields separated by tabs, or by another
    delimiter specified with the -G option.
    -B

    yr/mo/da/hr/mn/sc

    This option sets the starting time for data allowed in the input data.
    The -E option sets the ending time for data. If the
    starting time is before the ending time, then any data
    with a time stamp before the starting time or after the
    ending time is ignored. If instead the starting time is
    after the ending time, then any data between the ending
    and starting time will be ignored. This scheme allows time
    windowing both inside and outside a specified interval.
    Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.
    -C

    Causes netCDF CDL format output to be generated (see ncgen).
    When the -A (binary) option is also set mblist will call ncgen to
    convert the CDL file to a binary netCDF file (default name is mblist.nc),
    if successful the CDL file will be removed.
    -D

    dumpmode

    Normally, the output format is controlled by the -O option and
    the number of beams or pixels which are output is controlled by
    the -M and -N options.  The -D option provides
    a short cut for producing complete dumps of the longtitude and
    latitude locations of all beams or pixels along with the
    associated bathymetry, topography, amplitude, or sidescan values.
    The "lon lat value" triples are often useful for input into
    gridding programs (e.g. the GMT program surface) or
    other utilities. All valid (positive) values will be output, unless
    the -Q option is used to disable value checking.
    The dumpmode options are:

    dumpmode = 1:  format controlled by -O option

    dumpmode = 2:  longitude latitude depth

    dumpmode = 3:  longitude latitude topography

    dumpmode = 4:  longitude latitude amplitude

    dumpmode = 5:  longitude latitude sidescan

    Use of the -D option supercedes the -O, -M,
    and -N options.
    Default: mode = 1.
    -E

    yr/mo/da/hr/mn/sc

    This option sets the ending time for data allowed in the input data.
    The -B option sets the starting time for data. If the
    starting time is before the ending time, then any data
    with a time stamp before the starting time or after the
    ending time is ignored. If instead the starting time is
    after the ending time, then any data between the ending
    and starting time will be ignored. This scheme allows time
    windowing both inside and outside a specified interval.
    Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.
    -F

    format

    Sets the format for the input swath data using
    MBIO integer format identifiers.
    This program uses the MBIO library and will read any swath
    format supported by MBIO. A list of the swath data formats
    currently supported by MBIO and their identifier values
    is given in the MBIO manual page. Default: format = 11.
    -G

    delimiter

    Sets the character(s) used to separate output fields when ascii
    columns are output. Default: tabs are used as delimiters.
    -H

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

    filename

    Sets the input filename. If format > 0 (set with the
    -F option) then the swath data contained in infile
    is read and processed. If format < 0, then infile
    is assumed to be an ascii file containing a list of the input swath
    data files to be processed and their formats.  The program will read
    the data in each one of these files.
    In the infile file, each
    data file should be followed by a data format identifier, e.g.:

            datafile1 11

            datafile2 24

    This program uses the MBIO library and will read any swath
    format supported by MBIO. A list of the swath data formats
    currently supported by MBIO and their identifier values
    is given in the MBIO manual page.
    Default: infile = "datalist.mb-1".
    -K

    decimate

    Sets the decimation of the output data. By default (i.e. decimate=1),
    every available data record is output. If decimate>1, then only
    every "decimate"th record will be output. Default: decimate=1.
    -L

    lonflip

    Sets the range of the longitude values returned.
    If lonflip=-1 then the longitude values will be in
    the range from -360 to 0 degrees. If lonflip=0
    then the longitude values will be in
    the range from -180 to 180 degrees. If lonflip=1
    then the longitude values will be in
    the range from 0 to 360 degrees.
    Default: lonflip = 0.
    -M

    start_beam/end_beam or A

    Determines the range of bathymetry beams for which records will be output.
    If -MA is given, then a record
    will be output for each valid beam. If start_beam/end_beam
    is specified, then records will be output only for beams in this
    range. Beam numbers start with zero on the port side.
    If this option is used,
    then any longitude and latitude values output will reflect the
    positions of individual beams on the seafloor.
    The default is to output a single record for each ping
    in which longitude and latitude values reflect
    the sonar navigation, the depth,
    topography, and amplitude values reflect the valid beam
    nearest to vertical, and the sidescan value reflects the pixel
    nearest to vertical.
    -N

    start_pixel/end_pixel or A

    Determines the range of sidescan pixels for which records will be output.
    If start_pixel/end_pixel
    is specified, then records will be output only for pixels in this
    range. Pixel numbers start with zero on the port side. The default is
    to not output records associated with sidescan pixels. Instead,
    the default is to output a single record for each ping
    in which longitude and latitude values reflect
    the sonar navigation, the depth,
    topography, and amplitude values reflect the valid beam
    nearest to vertical, and the sidescan value reflects the pixel
    nearest to vertical. If -NA is given, then a record
    will be output for all sidescan pixels.
    -O

    output_format

    Determines the form of the output. Output_format is a string composed
    of one or more of the following characters:

    /
    special character: this causes the value
    indicated by the next character to be  inverted. This applies only to simple
    numeric values such as depth and
    heading and not to values like time
    strings or positions with hemisphere
    characters.

    -
    special character: this causes the value
    indicated by the next character to be
    multiplied by -1. This applies only
    to simple numeric values such as
    depth and heading and not to values
    like time strings or positions with
    hemisphere characters.

    =
    special character: this causes the value
    indicated by the next character to
    derive from the port-most non-null
    beam or pixel. This applies only
    to numeric values associated with
    beams or pixels such as depth, longitude,
    or latitude.

    +
    special character: this causes the value
    indicated by the next character to
    derive from the starboard-most non-null
    beam or pixel. This applies only
    to numeric values associated with
    beams or pixels such as depth, longitude,
    or latitude.

    A
    for apparent seafloor crosstrack slope
    (degrees from horizontal with positive
    slopes dipping toward port.) Calculated
    by fitting a line to the the
    bathymetry data of each ping.

    a
    for apparent seafloor crosstrack slope
    (degrees from horizontal with positive
    slopes dipping toward port.) Calculated
    by interpolation for each beam or pixel.

    B
    for amplitude

    b
    for sidescan

    C
    for sonar altitude above the bottom (m)

    c
    for sonar tranducer depth (m)

    D
    for bathymetry acrosstrack distance (m)

    d
    for sidescan acrosstrack distance (m)

    E
    for bathymetry alongtrack distance (m)

    e
    for sidescan alongtrack distance (m)

    G
    for flat bottom grazing angle (degrees)

    g
    for grazing angle using seafloor slope (degrees)

    H
    for heading (degrees)

    h
    for course made good (degrees)

    J
    for a time string (yyyy jd hh mm ss.ssssss)
    where jd is the day of the year

    j
    for a time string (yyyy jd dm ss.ssssss)
    where jd is the day of the year
    and dm is the minute of the day

    L
    for cumulative along-track distance (km)

    l
    for cumulative along-track distance (m)

    M
    for unix (epoch) time in decimal seconds since 1/1/70 00:00:00

    m
    for time in decimal seconds since first record

    N
    for ping count

    P  for pitch in degrees

    p  for draft in meters

    R  for roll in degrees

    r  for heave in meters

    S  for speed (km/hr)

    s  for speed made good (km/hr)

    T  for a time string (yyyy/mm/dd/hh/mm/ss)

    t  for a time string (yyyy mm dd hh mm ss)

    U  for unix time in integer seconds since 1/1/70 00:00:00

    u  for time in integer seconds since first record

    V  for ping interval (decimal seconds)

    X  for longitude (decimal degrees)

    x  for longitude (degrees + decimal minutes + E/W)

    Y  for latitude (decimal degrees)

    y  for latitude (degrees + decimal minutes + N/S)

    Z  for topography (positive upwards) (m)

    z  for depth (positive downwards) (m)

    #  for beam or pixel number

     .
    special character: this causes the next character to be
    interpretted from the following list rather than the above list.
    These allow access to raw values in format specific form and may
    not be supported by all formats.

     .A  Amplitude (backscatter) in dB (formats 56 & 67 - Simrad multibeam only)

     .a  Mean absorption coefficient in dB/km (formats 56 & 67 - Simrad multibeam some versions only)

     .B  Normal incidence backscatter in dB (formats 56 & 67 - Simrad multibeam only)

     .b  Oblique backscatter in dB (formats 56 & 67 - Simrad multibeam only)

     .c  Mean backscatter, one value per ping (formats 56 & 67 - Simrad multibeam only)

     .d  Beam depression angle (formats 56 & 67 - Simrad multibeam only)

     .F  Filename

     .f  File format

     .G  Start of TVG ramp in samples (formats 56 & 67 - Simrad multibeam only)

     .g  Stop of TVG ramp in samples (formats 56 & 67 - Simrad multibeam only)

     .L  Transmit pulse length (usec) (formats 56 & 67 - Simrad multibeam only)

     .l  Transmit pulse length (sec)

     .M  Sounder mode (formats 56 & 67 - Simrad multibeam only)

     .N  Ping number according to sounder (formats 56 & 67 - Simrad multibeam only)

     .p  Raw sidescan pixels in dB (formats 56 & 67 - Simrad multibeam only).
    May be preceded by a number to give the first n pixels (NaN padded) of the beam,
    for example .30p will give the first 30 sidescan pixels of each beam.

     .R  Range in samples (formats 56 & 67 - Simrad multibeam only)

     .r  Sampling rate in Hz (formats 56 & 67 - Simrad multibeam only)

     .S  Number of raw sidescan pixels per ping (formats 56 & 67 - Simrad multibeam only)

     .s  Number of raw sidescan pixels per beam (formats 56 & 67 - Simrad multibeam only)

     .T  Transmit gain (dB)

     .t  Receive gain (dB)

    Default output_format = YXLZ (latitude, longitude, cumulative
    along-track distance, and depth).
    -P

    pings

    Sets the ping averaging of the input data. If pings = 1, then
    no ping averaging is performed. If pings > 0, then
    that number of input pings will be averaged to produce one output
    ping.  If pings = 0, then the ping averaging will automatically
    be done so that the along-track ping spacing is equal to the across-track
    beam spacing.
    Default: pings = 1 (no ping averaging).
    -Q

    Disables value checking for validity (only positive bathymetry,
    amplitude, and sidescan values are valid).  This allows dumps
    of all of the data, including null or flagged beams and pixels.
    The flagged values are output without change. Null values are
    output as zero. This option is equivalent to -U2.
    -R

    west/east/south/north

    Sets the longitude and latitude bounds within which swath
    data will be read. Only the data which lies within these bounds will
    be read.
    Default: west=-360, east=360, south=-90, north=90.
    -S

    speed

    Sets the minimum speed in km/hr (5.5 kts ~ 10 km/hr) allowed in
    the input data; pings associated with a smaller ship speed will not be
    copied. Default: speed = 0.
    -T

    timegap

    Sets the maximum time gap in minutes between adjacent pings allowed before
    the data is considered to have a gap. Default: timegap = 1.
    -U

    check

    Sets the manner in which mblist handles flagged and null
    bathymetry, amplitude, and sidescan values. By default, mblist
    omits lines of output if they contain flagged or null values. This
    default corresponds to check = 0.
    If check = 1, then flagged values will be output
    unchanged and null values will be ignored.
    If check = 2,
    then flagged values will be output unchanged and null values
    will be output as zero (This corresponds to the -Q option).
    If check = 3, then flagged values will be output unchanged
    and null values will be output as "NaN".
    If check = 4, then flagged values and null values
    will be output as "NaN".
    -V

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

    Normally, mblist outputs bathymetry and across and along
    track distances in meters.  If the
    -W flag is given, then mblist outputs these values
    in feet.
    -X

    outfile

    Normally, mblist outputs to stdout.
    If the -X flag is given, then mblist creates a new file
    outfile and outputs to it.
    An output file must be specified if a netCDF file (-C -A) is required.
    -Z

    segment

    Causes the ascii output of different input swath files
    (e.g. when a datalist is specified with the -I option)
    to be separated by lines with segment. If segment
    is a single character, then the output is a multiple segment
    file of the sort accepted by the GMT program psxy.
    This option only works with ascii output, and is thus disabled
    when the -A option is specified. The most common usage
    is -ZI>.

    EXAMPLES

    Suppose one wishes to obtain a centerbeam profile
    from a raw Hydrosweep file
    (format 21) in a region between 105W and 103W
    longitude and between 10S and 8S latitude. The following will suffice:

            mblist -Iinfile.mb21 -F21 -R-105/-103/-10/-8 -OLz

    The output will be as follows:

            0.000  4378

            0.085  4370

            0.166  4370

            0.247  4351

            0.330  4353

            0.407  4337

            0.492  4334

            0.571  4323

            0.651  4316

            0.737  4307

            .....

    Here the depth values will correspond to the beam in each
    ping which is located closest to vertical under the ship.

    Suppose one wishes instead to obtain time, heading and speed data
    in the same file from 8AM to 9AM on August 10 1991. The following
    is appropriate:

            mblist -Iinfile.mb21 -F21 -B1991/8/10/8/0/0

            -E1991/8/10/9/0/0 -OTHS

    The output will be as follows:

            1991/08/10/08/00/05     283.9   41.29

            1991/08/10/08/00/19     283.4   20.36

            1991/08/10/08/00/33     285.1   20.36

            1991/08/10/08/00/48     286.7   20.09

            1991/08/10/08/01/02     284.9   20.08

            1991/08/10/08/01/16     285.2   20.02

            1991/08/10/08/01/44     284.2   20.20

            1991/08/10/08/02/12     283.7   20.50

            1991/08/10/08/02/41     283.6   20.75

            1991/08/10/08/03/09     285.1   21.19

            .....

    Suppose one wishes a data series with along-track distance,
    topography and across-track distance of beam number 15 for the same file
    and time limits as above:

            mblist -Iinfile.mb21 -F21 -B1991/8/10/7/0/0

            -E1991/8/10/9/0/0 -OLZD -M15/15

    The output will be as follows:

              0.000  4510   -1704

              0.172  4494   -1692

              0.260  4486   -1689

              0.343  4471   -1683

              0.427  4491   -1691

              0.506  4490   -1690

              0.591  4478   -1686

              0.676  4505   -1697

              0.763  4488   -1695

              0.849  4495   -1699

              .....

    Supppose one wishes to obtain longitude, latitude, and
    depth at the centerbeam as x-y-z data for the same region as in the
    first example:

            mblist -Iinfile.mb21 -F21 -R-105/-103/-10/-8 -OXYz

    The output will be as follows:

            -103.000236      -9.577439       4378

            -103.000943      -9.577229       4370

            -103.001651      -9.577020       4370

            -103.002372      -9.576794       4351

            -103.003041      -9.576584       4353

            -103.003771      -9.576338       4337

            -103.004456      -9.576105       4334

            -103.005153      -9.575895       4323

            -103.005903      -9.575679       4316

            -103.006586      -9.575449       4307

            .....

    Suppose one wishes to obtain a dump of longitude, latitude, and
    depth for all good beams in a Hydrosweep data file. There are two ways to
    obtain this output. One can explicitly specify the output format as
    -OXYz and the output beams as -M0/58:

            mblist -Iinfile.mb21 -F21 -OXYz -M0/58

    or one can use the equivalent -D2 shortcut:

            mblist -Iinfile.mb21 -F21 -D2

    Either way, the output is as follows:

            -49.296454        12.180552       4866

            -49.296695        12.178668       4858

            -49.296923        12.176893       4855

            -49.297123        12.175341       4877

            -49.297319        12.173808       4895

            -49.297536        12.172122       4879

            -49.297744        12.170498       4865

            -49.297909        12.169216       4904

            -49.298100        12.167727       4899

            -49.298299        12.166175       4871

            -49.298476        12.164803       4873

            -49.298639        12.163530       4891

            .....

    Suppose one wishes to obtain a dump of longitude, latitude, and
    depth for all beams, valid or not, in a Hydrosweep data file.
    The approach is the same as the preceding example, except that
    the -Q option is used to disable validity checking of
    beam values. One can explicitly specify the output format as
    -OXYz and the output beams as -M0/58:

            mblist -Iinfile.mb21 -F21 -OXYz -M0/58 -Q

    or one can use the equivalent -D2 shortcut:

            mblist -Iinfile.mb21 -F21 -D2 -Q

    Either way, the output includes both zero beams (no data) and
    beams with negative depths (flagged as bad data):

            -49.301094        12.144409          0

            -49.301094        12.144409          0

            -49.296454        12.180552       4866

            -49.296695        12.178668       4858

            -49.296923        12.176893       4855

            -49.297123        12.175341       4877

            -49.297319        12.173808       4895

            -49.297536        12.172122       4879

            -49.297744        12.170498       4865

            -49.297909        12.169216       4904

            -49.298100        12.167727       4899

            -49.298100        12.167727      -4144

            -49.298299        12.166175       4871

            -49.298476        12.164803       4873

            -49.298639        12.163530       4891

            .....

    Finally, suppose one wishes to obtain a dump of longitude, latitude, and
    amplitude for all good beams in a Hydrosweep data file. There are two ways to
    obtain this output. One can explicitly specify the output format as
    -OXYB and the output beams as -M0/58:

            mblist -Iinfile.mb21 -F21 -OXYB -M0/58

    or one can use the equivalent -D4 shortcut:

            mblist -Iinfile.mb21 -F21 -D4

    Either way, the output is as follows:

            -49.296454        12.180552         13

            -49.296695        12.178668         17

            -49.296923        12.176893         16

            -49.297123        12.175341         14

            -49.297319        12.173808         17

            -49.297536        12.172122          9

            -49.297744        12.170498         14

            -49.297909        12.169216         15

            -49.298100        12.167727         12

            -49.298299        12.166175         12

            -49.298476        12.164803         28

            -49.298639        12.163530         14

            .....

    Suppose one wishes to examine the number of raw sidescan pixels in Simrad EM1002 data file
    and the first 5 pixels of each beam:

            mblist -i 0044_20000425_093808.mb57 -MA -ON#.S.s.5p

    The output will be as follows:

         1       0           11278     286      -31.5   -32.0   -32.0   -32.5   -33.0

         1       1           11278     133      -34.5   -34.5   -34.5   -34.5   -33.5

         1       2           11278     142      -40.0   -40.0   -40.0   -40.0   -40.0

         1       3           11278     139      -40.0   -40.5   -40.5   -40.5   -40.5

         1       4           11278     159      -39.5   -38.5   -38.5   -39.0   -38.5

         ...

         1      54           11278     1        -27.00  NaN     NaN     NaN     NaN

         .....

    SEE ALSO

    mbsystem(l), mbinfo(l)

    BUGS

    mblist is not able to list all of the information available in some
    swath data formats.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 26 October 2009

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

Back to MB-System Home Page...