#### DESCRIPTION #######################################################
########################################################################
##   Finds segmented data and organizes overlaps, gaps, and multiples.##
##  If two segments are sequential (within a tolerance) they are      ##
##  merged.  Multiples and repeated segments are removed.  Large      ##
##  overlaps and gaps are noted (in STDOUT) and left alone.           ##
##                                                                    ##
##  Next Version: gap interpolation via matlab routines               ##
##                                                                    ##
##   LAST EDITED: Jun. 14, 2008 at 18:20 GMT by Garrett Euler         ##
##   VERSION INFO:                                                    ##
##            3.6: doc updates                                        ##
##            3.5: fixed delete bug in sub merge                      ##
##            3.4: better handling of when input and output           ##
##                 directories are equal (skip copying)               ##
##            3.3: - threading support added to optimize efficiency   ##
##                 - calling of matlab routines for gap interpolation ##
##                   established - just need routines                 ##
##            3.2: selection for overlaps or gaps only                ##
##            3.1: debugging and merge verification                   ##
##            3.0: major rewrite - highly modularized, filename       ##
##                 independence, some major bugfixes for complicated  ##
##                 situations and new options - gapfill, lapcut, ddr  ##
##                 and show                                           ##
##            2.4: removed nasty bug                                  ##
##            2.3: tableless                                          ##
##            2.2: perl modules and debugging                         ##
##            2.1: fix update bug                                     ##
##            2.0: cleaner, more portable, and resilient              ##
##            1.3: added update list output for tupdate.pl            ##
##            1.2: workaround for sac no-merge bug                    ##
##            1.1: streamlined and added this helpful feature.        ##
##            1.0: initial version                                    ##
########################################################################

#### USAGE #############################################################
########################################################################
##  Command line input:                                               ##
##     overgaps.pl in_data_dir new_data_dir tolerance type gapfill    ##
##        lapcut ddr ncpu [show]                                      ##
##                                                                    ##
##     where:                                                         ##
##        *in_data_dir - input data directory                         ##
##        *new_data_dir - output data directory                       ##
##        *tolerance - merging tolerance (allowance in seconds for    ##
##          adjusting the timing of files)                            ##
##          -- consider a value equivalent to at least 2 sample       ##
##             intervals as SAC has single precision timing which can ##
##             be awful for merging what should be continuous data    ##
##          -- note that when merging multiple files the overall time ##
##             adjustment of any segment will never exceed this value ##
##          -- mergers adjust the timing of the shorter length file   ##
##             to make the files sequential                           ##
##          -- allowing greater than 1 second adjustment can clean up ##
##             leap second timing issues (in the immediate sense)     ##
##          -- negative values never allow merging                    ##
##        *type - 0 - work on both overlaps and gaps                  ##
##                1 - work on overlaps only                           ##
##                2 - work on gaps only                               ##
##        *gapfill - 0 - remove gaps by making files sequential       ##
##                   1 - fill gaps with zeros                         ##
##                   2 - interpolate gaps linearly                    ##
##                   3 - interpolate gaps piecewise cubic             ##
##                   4 - interpolate gaps with spline                 ##
##          -- only for gaps less than or equal to 'tolerance'        ##
##          -- interpolation is not working yet!!!                    ##
##        *lapcut - 0 - remove overlap by making files sequential     ##
##                  1 - cut overlap from shorter file and merge       ##
##          -- only for overlaps less than or equal to 'tolerance'    ##
##        *ddr - delta difference range in percent                    ##
##          -- ie. 5 means the sample interval of the two files must  ##
##             be within +/-5% of their averaged sample interval in   ##
##             order to merge or delete the files                     ##
##          -- 0 means delta must be exactly the same for merge or    ##
##                 delete to occur                                    ##
##        *nproc - number of processor threads for this task          ##
##        *show - report unmerged overgaps (if defined)               ##
########################################################################

