mbhistogram
Section:  MB-System 5.0  (1)
Updated:  3 June 2013 
Index


 
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(1), mbm_plot(1), grdhisteq(1)

 
BUGS

You find em, we fix 'em...



 
Index

NAME

VERSION

SYNOPSIS

DESCRIPTION

AUTHORSHIP

OPTIONS

EXAMPLES

SEE ALSO

BUGS

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

Back to MB-System Home Page...