mblist(1)

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 -M[start_beam/end_beam | A | Xpercentage] -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 or Xexcludepercent
    Determines the range of bathymetry beams for which records will be output. If this option is used, then any longitude and latitude values output will reflect the positions of individual beams on the seafloor. 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 -MXexcludepercent is given, then records will be output for each valid, non-excluded beam where the outer excludepercent percentage of beams are excluded. 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)

    F for beamflag numeric value (1=null, 0=good, 5=manual, 9=filter, 129=sonar).

    f for beamflag character value ('-'=null, 'G'=good, 'M'=manual, 'F'=filter, 'S'=sonar).

    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

    Q for bottom detection type as letter (A=amplitude, P=phase, U=unknown)

    q for bottom detection type as number (1=amplitude, 2=phase, 0=unknown)

    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(1), mbinfo(1)

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