MB-System Unix Manual Page
mblist
Section: MB-System 5.0 (1)
Updated: 17 May 2014
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)
-
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.
Index
- NAME
-
- VERSION
-
- SYNOPSIS
-
- DESCRIPTION
-
- AUTHORSHIP
-
- OPTIONS
-
- EXAMPLES
-
- SEE ALSO
-
- BUGS
-
Last Updated: 17 May 2014
Return to list of MB-System manual pages...
Back
to MB-System Home Page...