mbcopy(1)

NAME
mbcopy - Copy swath sonar bathymetry data files.

VERSION
Version 5.0

SYNOPSIS
mbcopy [-Byr/mo/da/hr/mn/sc -Ccommentfile -D -Eyr/mo/da/hr/mn/sc -Finformat[/outformat[/mergeformat]] -H -Iinfilename -Llonflip -Mmergefilename -N -Ooutfilename -Ppings -Qsleep_factor -Rwest/east/south/north -Sspeed -V]

DESCRIPTION
mbcopy is a utility for copying swath sonar data files which may be used to change formats, average pings, or window in time and space. mbcopy can be used as a filter from stdin to stdout, or it may do i/o to and from files.

AUTHORSHIP
David W. Caress (caress@mbari.org)
  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)
  Lamont-Doherty Earth Observatory

OPTIONS

-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  commentfile
    Text file containing comments which are inserted into the beginning of the output data stream. This option is typically used to insert a data pedigree statement at the beginning of data processing.

-D  This option only works when the output format is MBLDEOIH (format 71). When -D is invoked, mbcopy only outputs swath bathymetry data (any amplitude and sidescan data found in the input are ignored). The MB-System program mbdatalist uses this option to generate "fast bathymetry" or "fbt" files. See the MB-System manual page for information on the use and utility of "fbt" files.

-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  informat[/outformat[/mergeformat]]
    Sets the format for the input and output swath sonar data using MBIO integer format identifiers. If only informat is specified, then outformat is assumed to be the same. If bathymetry merging is specified with the -M option, then the optional mergeformat specifies the format of the merge file. This program uses the MBIO library and will read or write any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. When the informat and outformat values are both associated with the same swath sonar sonar system (e.g. the Atlas Hydrosweep DS system), then the complete data stream contained in the input file can be copied to the output file. If the two formats are associated with two different swath sonar systems, then only the time stamp, navigation, and beam values will be copied. The use of ping averaging also causes a partial data stream to be passed, even when compatible or identical input and output formats are specified (see the -P option). Default: informat = 11; outformat = 11.

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

-I  infilename
    Data file from which the input data will be read. If no input file is specified, the input will be read from stdin. Default: infilename = stdin.

-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  mergefilename
    If a merge file is specified then the bathymetry data and flags from the merge file will be written to the output file along with the remaining data from the input file. This can be used to merge two processing streams, one for bathymetry data and the other for other data sets. The input file and merge file must both be based on the same raw data.

-N  Normally, mbcopy generates a set of comment records at the beginning of the output stream which record when, how, and by whom mbcopy was run. If the -N flag is given, these comments are not included in the output stream, and, in addition, any preexisting comment records in the input data stream are not passed to the output data stream. However, the -N option does not affect the insertion of comments from a text file if specified using the -C option.

-O  outfilename
    Data file to which the output data will be written. If no output file is specified, the output will be written to stdout. Default: outfilename = stdout.

-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. If ping averaging is used (pings != 1), then only a partial data stream can be copied (see the -F option). Default: pings = 1 (no ping averaging).

-Q  sleep_factor
    Causes the program to sleep before writing each data record, thus simulating a simple data logger. The amount of time slept is the time between the previous and current pings times the value sleep_factor. Default: sleep_factor = 1.0

-R  west/east/south/north
    Sets the longitude and latitude bounds within which swath sonar data will be read. Only the data which lies within these bounds will be copied. 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.

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

EXAMPLES
Suppose one wishes to copy a raw Hydrosweep file (format 21) called hs_raw into a L-DEO binary Hydrosweep file (format 24) called hs_binary while windowing the data into a region between 145W and 140W longitude and between 10S and 5S longitude. The following will suffice:
     mbcopy -P1 -F21/24 -R-145/-140/-10/-5 -Ihs_raw -Ohs_binary Suppose one has a program called thrash_prog which requires Hydrosweep data to be input in the URI format (format 23) to stdin, but the existing data is in a raw Hydrosweep file (format 21). The following will work:
     mbcopy -P1 -F21/23 | thrash_prog where a pipe (|) has been used to direct the stdout stream from mbcopy to the stdin stream of thrash_prog. Suppose one has some raw data from a Simrad EM300 that has been cleaned and processed by a third party using other software and exported as a GSF file, but one wants to access the original Simrad attitude and backscatter data with the corrected bathymetry data. The following will work:
     mbcopy -F56/57/121 -I0015_20040212_052714_raw.all -M20040212_052714.gsf -O20040212_052714.mb57

SEE ALSO
mbsystem(l), mbio(l)

BUGS
Certainly.