mbhistogram(1)

NAME
mbhistogram - Generate a histogram of bathymetry, amplitude, or sidescan values from swath sonar data files.

VERSION
Version 5.0

SYNOPSIS
mbhistogram [-Akind -Byr/mo/da/hr/mn/sc -C -Dmin/max -Eyr/mo/da/hr/mn/sc -Fformat -G -Ifilename -Llonflip -Mnintervals -Nnbins -Pping -Rwest/east/south/north -Sspeed -V -H]

DESCRIPTION
mbhistogram reads a swath sonar data file and generates a histogram of the bathymetry, amplitude, or sidescan values. Alternatively, mbhistogram can output a list of values which break up the distribution into equal sized regions. These values can be used to construct a color table, producing an image which is histogram equalized. If desired, the histogram can be recast into a Gaussian distribution before output or the calculation of the histrogram equalization This feature is similar to the Gaussian option of grdhisteq. The linear histogram equalization is most appropriate for use with grayscale images, such as those produced from amplitude or sidescan data, and is used by the macro mbm_plot for that purpose. The Gaussian histogram equalization is well suited for shading of images, and is used by mbm_plot for shading of color bathymetry with amplitude data. The results are dumped to stdout.

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

OPTIONS

-A  kind
    Sets the kind of data to be processed, where
         kind = 0 : histogram of bathymetry data
         kind = 1 : histogram of beam amplitude data
         kind = 2 : histogram of sidescan data Default: kind = 2.

-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.

-D  min/max
    Specifies the minimum and maximum data values used for constructing the histogram. The width of the bins is determined by (max - min) divided by nbins (see the -N option). The min value is the center of the first histogram bin, and the max value is the center of the last histogram bin. Data values falling outside the range of the bins are ignored.

-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 data format used if the input is read from stdin or from a file. If format < 0, then the input file specified with the -I option will actually contain a list of input swath sonar data files. 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. Default: format = 11.

-G  This option causes the data histogram to be recast into a Gaussian distribution.

-I  filename
    Sets the input filename. If format > 0 (set with the -f option) then the swath sonar 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 sonar 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 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. Default: infile = "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  nintervals
    If nintervals > 0 then mbhistogram will calculate and output a list of values which break up the data distribution into equal sized regions. This can be useful for constructing color tables which accentuate features in amplitude and sidescan data (the macro mbm_plot makes use of this feature). If this option is enabled, then the raw histogram is not output.

-N  nbins
    Sets the number of bins used to calculate the histogram.

-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).

-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 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.

-V  Normally, mbhistogram only prints out the statistics obtained by reading all of the data. If the -V flag is given, then MBCOPY works in a "verbose" mode and outputs the program version being used and all read error status messages.

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

EXAMPLES
Suppose one wishes to obtain a histogram of the sidescan data in a file called mbexample.mb41 containing raw data from a SeaBeam 2112 sonar (format 41). The following will suffice:
 mbhistogram -F41 -I sb199411211212.rec -D0.0/45000 -N25
to yield the following histogram:
 0.000000 183814
 1875.000000 30845
 3750.000000 5365
 5625.000000 1918
 7500.000000 951
 9375.000000 591
 11250.000000 403
 13125.000000 232
 15000.000000 189
 16875.000000 127
 18750.000000 108
 20625.000000 75
 22500.000000 85
 24375.000000 48
 26250.000000 30
 28125.000000 31
 30000.000000 28
 31875.000000 21
 33750.000000 10
 35625.000000 9
 37500.000000 4
 39375.000000 2
 41250.000000 2
 43125.000000 2
 45000.000000 1
In order to obtain 16 values breaking up the distribution into equal sized regions, use the -M option:
 mbhistogram -F41 -I sb199411211212.rec -D0.0/45000 -N45000 -M25
giving:
  -0.500011
 110.657221
 137.446811
 165.916284
 199.635469
 239.900007
 287.726270
 345.615610
 418.142114
 513.487776
 639.986551
 824.475879
 1140.372280
 1994.280032
 44803.495633

SEE ALSO
mbsystem(l), mbm_plot(l), grdhisteq(l)

BUGS
You find em, we fix 'em...