MB-System Unix Manual Page

mblist

Section: MB-System 5.0 (1)
Updated: 3 June 2013
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 -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)
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.


 

Index

NAME
VERSION
SYNOPSIS
DESCRIPTION
AUTHORSHIP
OPTIONS
EXAMPLES
SEE ALSO
BUGS


Last Updated: 3 June 2013


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

Back to MB-System Home Page...