MB-System Unix Manual Page

mbprocess

NAME

mbprocess - this program performs a
variety of swath data processing
functions in a single step (producing
a single output swath data file),
including merging navigation, recalculating
bathymetry from travel time
and angle data by raytracing through a
layered water sound velocity model,
applying changes to ship draft, roll bias and pitch bias,
applying tides,
and applying bathymetry edits from edit save files.

The actions of mbprocess are controlled by text
parameter files. Each mbprocess parameter file
contains single line commands that set
processing modes and parameters. The program mbset
can be used to create and modify mbprocess parameter files.
Other programs such as mbedit, mbnavedit,
mbvelocitytool, mbnavadjust, and mbclean
modify or create (if needed) mbprocess parameter files.

The input file "infile" must be specified with the -I option.
If "infile" is a datalist, then mbprocess will
attempt to process each swath data file identified by recursively
reading the datalist. Otherwise, mbprocess will attempt
to process "infile" directly.

For any swath data file "datafile", the program
will look for and use a parameter file with the
name "datafile.par". If no parameter file exists, mbprocess
will infer a reasonable processing path by looking for navigation
and mbedit edit save files.The data format
can also be specified, though the program can
infer the format if the standard MB-System suffix convention
is used (*.mbXX where XX is the MB-System format id number).

The processed output swath files produced by mbprocess
are named using a convention based on the data format id.
MB-System data formats are specified
using two-digit or three-digit numbers (see the MBIO manual page).
If an input swath data file is named "root.mbXX", where XX is the format
id, then the default processed output file will be "rootp.mbXX"
(e.g. mydata.mb71 -> mydatap.mb71).
The "p" inserted before the ".mbXX" suffix indicates the output
file has been created by mbprocess.
If the input file does not follow the *.mbXX naming convention,
then the output filename will just consist of the input name
with "p.mbXX" added as a suffix (e.g. mydata -> mydatap.mb71)

By default, mbprocess will only process a swath data
file if the processed output file is either missing or out
of date relative to the input swath data file, the parameter
file, or any of the ancillary data files referred to in
the parameter file (e.g. navigation files, edit save files,
svp files). If the -P option is specified, mbprocess
will process every file, whether it needs it or not.

DATA CUTTING:
DATACUTCLEAR
removes all existing data cutting commands
DATACUT kind mode min max
adds new data cutting command, where:
kind = 0 : cut applied to bathymetry data
kind = 1 : cut applied to amplitude data
kind = 2 : cut applied to sidescan data
mode = 0 : min and max indicate start and end
beam/pixel numbers between which data
are flagged or zeroed
mode = 1 : min and max indicate start and end
acrosstrack distance (m) between which
data are flagged or zeroed
BATHCUTNUMBER min max
adds new bathymetry data cutting command where
min and max are the start and end beam numbers
between which data are flagged (note that
flagging bathymetry also flags amplitude data)
BATHCUTDISTANCE min max
adds new bathymetry data cutting command where
min and max are the start and end acrosstrack
distance (m) between which data are flagged
(note that flagging bathymetry also flags
amplitude data)
BATHCUTSPEED min max
adds new bathymetry data cutting command where
all beams are flagged for pings with a ship
or vehicle speed less than min or greater than
max (note that flagging bathymetry also flags
amplitude data)
AMPCUTNUMBER min max
adds new amplitude data cutting command where
min and max are the start and end beam numbers
between which amplitude data are zeroed (note
that zeroing amplitude data has no impact on
bathymetry data)
AMPCUTDISTANCE min max
adds new amplitude data cutting command where
min and max are the start and end acrosstrack
distance (m) between which amplitude data are
zeroed (note that zeroing amplitude data has
no impact on bathymetry data)
AMPCUTSPEED min max
adds new amplitude data cutting command where
all amplitude values are zeroed for pings with
a ship or vehicle speed less than min or greater
than max (note that zeroing amplitude data has
no impact on bathymetry data)
SSCUTNUMBER min max
adds new sidescan data cutting command where
min and max are the start and end pixel numbers
between which sidescan data are zeroed (note
that zeroing sidescan data has no impact on
bathymetry data)
SSCUTDISTANCE min max
adds new sidescan data cutting command where
min and max are the start and end acrosstrack
distance (m) between which sidescan data are
zeroed (note that zeroing sidescan data has
no impact on bathymetry data)
SSCUTSPEED min max
adds new sidescan data cutting command where
all sidescan values are zeroed for pings with
a ship or vehicle speed less than min or greater
than max (note that zeroing sidescan data has
no impact on bathymetry data)

BATHYMETRY RECALCULATION:
SVPMODE mode
sets usage of a water sound speed model (sound
velocity profile, or SVP) [0]
0: bathymetry recalculation by raytracing off
1: bathymetry recalculation by raytracing on
2: translate depths from corrected to uncorrected
or vice versa depending on SOUNDSPEEDREF
command
SVPFILE filename
sets SVP file path [no default]
SSVMODE boolean
sets surface sound velocity (SSV) mode [0]
0: use SSV from file
1: offset SSV from file (set by SSV command)
2: use constant SSV (set by SSV command)
SSV constant/offset
sets SSV value or offset (m/s) [1500.0]
ANGLEMODE mode
sets handling of beam angles during
raytracing [1]
0: angles not changed before raytracing
1: angles adjusted using Snell's Law for
the difference between the surface sound
velocity (SSV) and the sound speed at
the sonar depth in the SVP.
2: angles adjusted using Snell's Law and
the sonar array geometry for the
difference between the surface sound
velocity (SSV) and the sound speed at
the sonar depth in the SVP.
TTMULTIPLY multiplier
sets value multiplied by travel times [1.0]
SOUNDSPEEDREF boolean
determines the handling of the sound
speed reference for bathymetry [1]
- note: if raytracing is turned off then
this command implies correcting or
uncorrecting using the SVP specified
with the SVPFILE command
0: produce "uncorrected" bathymetry
referenced to a uniform 1500 m/s
water sound speed model.
1: produce "corrected" bathymetry
referenced to a realistic water
sound speed model.

STATIC BEAM BATHYMETRY OFFSETS:
STATICMODE mode
sets offsetting of bathymetry by
per-beam statics [0]
0: static correction off
1: static correction by beam number
2: static correction by acrosstrack beam angle
STATICFILE filename
sets static per-beam file path [no default]
- static files are two-column ascii tables
- if correction is by beam number then
the beam # is in column 1 and
the depth offset is in m in column 2
- if correction is by beam angle then
the beam angle (starboard positive)
is in column 1 and
the depth offset is in m in column 2

PROCESSING KLUGES:
KLUGE001 boolean
enables correction of travel times in
Hydrosweep DS2 data from the R/V Maurice
Ewing in 2001 and 2002.
KLUGE002 boolean
enables correction of draft values in
Simrad data
- some Simrad multibeam data has had an
error in which the heave has bee added
to the sonar depth (draft for hull
mounted sonars)
- this correction subtracts the heave
value from the sonar depth
KLUGE003 boolean
enables correction of beam angles in
SeaBeam 2112 data
- a data sample from the SeaBeam 2112 on
the USCG Icebreaker Healy (collected on
23 July 2003) was found to have an error
in which the beam angles had 0.25 times
the roll added
- this correction subtracts 0.25 * roll
from the beam angles before the bathymetry
is recalculated by raytracing through a
water sound velocity profile
- the mbprocess parameter files must be
set to enable bathymetry recalculation
by raytracing in order to apply this
correction
KLUGE004 boolean
deletes survey data associated with duplicate
or reversed time tags
- if survey data records are encountered
with time tags less than or equal to the
last good time tag, an error is set and
the data record is not output to the
processed data file.
KLUGE005 boolean
replaces survey record timestamps with
timestamps of corresponding merged navigation
records
- this feature allows users to fix
timestamp errors using MBnavedit and
then insert the corrected timestamps
into processed data
KLUGE006 boolean
changes sonar depth / draft values without

changing bathymetry values
KLUGE007 boolean
processing kluge 007 (not yet defined)
- occasionaly odd processing problems will
occur that are specific to a particular
survey or sonar version
- mbprocess will allow one-time fixes to
be defined as "kluges" that can be turned
on through the parameter files.

ANCILLARY DATA FILES

MB-System also uses a number of ancillary data files, most
of which relate to mbprocess in some way. By default,
these ancillary data files are named by adding a short suffix
to the primary data file name (e.g. ".par", ".svp", ".esf", ".nve")

The common ancillary files are listed below. The example names
given here follow from an input swath data file name of mydata.mb71.

The processing parameter file used by mbprocess has
an ".par" suffix. These files are generated
or modified by mbset, mbedit, mbnavedit,
mbvelocitytool, mbnavadjust, and mbclean.
mydata.mb71.par

The most prominent ancillary files are metadata or
"inf" files (created from the output of mbinfo).
Programs such as mbgrid and mbm_plot try to check "inf"
files to see if the corresponding data files include data within
desired areas. The program mbprocess automatically generates
an "inf" file for any processed output swath file.
Also, the program mbdatalist is often used to
create or update "inf" files for large groups of swath data files.
mydata.mb71.inf

The "fast bath" or "fbt" files
are generated by copying the swath bathymetry to a sparse,
quickly read format (format 71). Programs such as mbgrid,
mbswath, and mbcontour will try to read "fbt" files
instead of the full data files whenever only bathymetry
information are required. The program mbprocess
automatically generates
an "fbt" file for any processed output swath file.
Also, the program mbdatalist is often used to
create or update "fbt" files for large groups of swath data files.
These files are not generated or used
when the original swath data is already
in a compact bathymetry-only data format.
mydata.mb71.fbt

The "fast nav" or "fnv" files
are just ASCII lists of navigation generated using mblist
with a -OtMXYHSc option. Programs such as mbgrid,
mbswath, and mbcontour will try to read "fnv" files
instead of the full data files whenever only
navigation information are required. These files are not generated or used
when the original data is already
in a single-beam or navigation data format.
mydata.mb71.fnv

The bathymetry edit save file generated by mbedit and
mbclean has an ".esf" suffix.
mydata.mb71.esf

A water sound velocity profile (SVP) file generated
by mbvelocitytool has an ".svp" suffix unless
the user specifies otherwise.
mydata.mb71.svp

Water sound velocity profile (SVP) files generated
by mbsvplist also use the ".svp" suffix.
However, multiple SVP files may be
extracted from each input swath file, so the files are
numbered using a "_YYY.svp" suffix, where YYY increments
from 001.
mydata.mb71_001.svp
mydata.mb71_002.svp
mydata.mb71_003.svp

Edited navigation files generated by mbnavedit have
an ".nve" suffix:
mydata.mb71.nve
These navigation files can be read independently using format 166.

Adjusted navigation files generated by mbnavadjust
have an ".naY" suffix, where "Y" is a number between 0-9.
The mbnavadjust package may be used multiple times
for a survey; the adjustments are numbered sequentially from
"0":
mydata.mb71.na0
mydata.mb71.na1
mydata.mb71.na2
and so on. These navigation files can be read independently using format 166.

AUTHORSHIP

OPTIONS

format
Sets the MBIO integer format identifier
for the input file specified with the
-I option. By default, mbprocess
derives the format id from the mbprocess parameter file
associated with the input file (-I option) or, if necessary,
infers the format from the "*.mbXX" MB-System suffix
convention.

-H

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

-I

infile
Swath data file from which the input data will be read, or
a datalist file containing a list of input swath data files
and/or other datalist files. If infile is a
datalist file, then mbprocess will attempt to
process all data files identified by recursively reading
infile.

-N

By default, mbprocess passes any comment records
it encounters in the input data to the output data file
and additionally embeds new comment records detailing the
processing parameters used by mbprocess.
This option causes mbprocess to not pass new or old
comment records to the output data file.

-O

outfile
Data file to which the output data will be written. If
no output file is specified, the output filename is
set automatically. If an input swath data file
is named "root.mbXX", where XX is the format
id, then the default processed output file will be "rootp.mbXX".
The "p" inserted before the ".mbXX" suffix indicates the output
file has been created by mbprocess.
If the input file does not follow the *.mbXX naming convention,
then the output filename will just consist of the input name
with "p.mbXX" added as a suffix.

-P

By default, mbprocess will only process a swath data
file if the processed output file is either missing or out
of date relative to the input swath data file, the parameter
file, or any of the ancillary data files referred to in
the parameter file (e.g. navigation files, edit save files,
svp files). If the -P option is specified, mbprocess
will process every file, whether it needs it or not.

-T

This option puts mbprocess into a test mode. The program
will report whether or not it would process a file, but it
will not actually process the data or produce an output
processed file.

-S

This option causes mbprocess to print out the status of
each file (e.g. up to date, out of date, locked, unlocked) along
with the file modification times used to determine if the output
file is out of date.

-V

Normally, mbprocess works "silently" without outputting
anything to the stderr stream. If the
-V flag is given, then mbprocess works in a "verbose" mode and
outputs the program version being used, the processing parameters
being use, and some statistics regarding the processing accomplished.

NAVIGATION FORMATS

The navigation formats that are supported for merging by mbprocess
include the following:
MBprocess ID Name

------------------ ----

1 Simple Decimal Time

2 Simple Date 1

3 Simple Date 2

4 Simple Date 3

5 L-DEO Processed Nav

6 NMEA 0183 - GLL

7 NMEA 0183 - GGA

8 Simrad 90 Nav

9 MBPRONAV (*.nve Files)

10 R2RNAV (*_hires.r2rnav Files)

Format 1 (Simple Decimal Time):
- text

- fields separated by white space

- each line contains the following fields:

time_d lon lat

- time_d : decimal seconds since 1970 Jan 1 00:00:00.00

- lon: decimal longitude (deg)

- lat: decimal latitude (deg)

Format 2 (Simple Date 1):
- text

- fields separated by white space

- each line contains the following fields:

yr mon day hour min sec lon lat

- yr: four-digit year

- mon: integer month of year

- day: integer day of month

- hour: integer hour of day

- min: integer minute of hour

- sec: decimal second of minute

- lon: decimal longitude (deg)

- lat: decimal latitude (deg)

Format 3 (Simple Date 2):
- text

- fields separated by white space

- each line contains the following fields:

yr jday hour min sec lon lat

- yr: four-digit year

- jday: integer julian day of year

- hour: integer hour of day

- min: integer minute of hour

- sec: decimal second of minute

- lon: decimal longitude (deg)

- lat: decimal latitude (deg)

Format 4 (Simple Date 3):
- text

- fields separated by white space

- each line contains the following fields:

yr jday daymin sec lon lat

- yr: four-digit year

- jday: integer julian day of year

- daymin: integer minute of day

- sec: decimal second of minute

- lon: decimal longitude (deg)

- lat: decimal latitude (deg)

Format 5 (L-DEO Processed Nav):
- text

- fields separated by white space

- each line contains the following fields:

timetag NorS latd latm EorW lond lonm src dr1 dr2

- timetag: comes in two forms

form 1: yy+jjj:hh:mm:ss.sss

form 2: yyyy+jjj:hh:mm:ss.sss

- yy: either two-digit or four-digit year

- jjj: integer julian day of year

- hh: integer hour of day

- mm: integer minute of hour

- ss.sss: decimal second of minute

- NorS: 'S' for southern hemisphere

'N' for northern hemisphere

- latd: integer latitude degrees

- latm: decimal latitude minutes

- EorW: 'E' for eastern hemisphere

'W' for western hemisphere

- lond: integer longitude degrees

- lonm: decimal longitude minutes

- src: nav source (e.g. gp1, dr, satl)

'gp1' - GPS receiver 1

'dr' - dead reckoning

'satl' - transit satellite

- dr1: nonzero when src is 'dr'

- dr2: nonzero when src is 'dr'

Format 6 (NMEA 0183 - GLL):
- text

- fields separated by commas

- nav derived from GLL strings

Format 7 (NMEA 0183 - GGA):
- text

- fields separated by commas

- nav derived from GGA strings

Format 8 (Simrad 90 Nav):
- text

- fields not separated by white space

- each line contains the following fields:

ddmmyy_hhmmss.ss_LLlllllN_LLLllllllE- dd: day of month

- mm: integer month of year- yy: two-digit year

- hh: integer hour of day

- mm: integer minute of hour

- ss.ss: decimal second of minute

- LL: integer latitude degrees

- lllll: integer latitude minutes X 1000

- N: 'S' for southern hemisphere

'N' for northern hemisphere

- LLL: integer longitude degrees

- lllll: integer longitude minutes X 1000

- E: 'E' for eastern hemisphere

'W' for western hemisphere

Format 9 (MBPRONAV (*.nve Files)):
- text

- fields separated by white space

- each line contains at least 9, and possibly as many as 19, of the following fields:

EXAMPLES

Suppose the user has a Simrad EM120 data file called
"0051_20010829_223755.mb57" that requires processing.

Editing the bathymetry data in this file with mbedit will generate
an edit save file "0051_20010829_223755.mb57.esf" and
an mbprocess parameter file "0051_20010829_223755.mb57.par".
The contents of the parameter file are:

Editing the navigation with mbnavedit will generate
a navigation file named "0051_20010829_223755.mb57.nve"
and will modify the parameter file. The changed lines
in "0051_20010829_223755.mb57.par" are: