This directory contains Cube examples useful for (unit-) testing as they
contain various errors, defects or other "special features". 


Test 002 -- Buffer overrun system event
---------------------------------------

  During the recording a buffer overrun of the internal ring buffer occurred.
  Such buffer overruns happen when the Cube does not manage to write the
  recorded samples fast enough to the internal SD card. As a consequence,
  samples will be missing from the saved data stream!

  These problems are detected by the Cube hardware and marked in the data
  stream by a SYSTEM EVENT block. This test ensures that buffer overrun
  events are detected and correctly handled by the GIPPtools.

  002-buffer-overrun-1.cube ... A Cube file with a 3142 sample data gap.
  002-buffer-overrun-2.cube ... A Cube file without data gap.

  002-buffer-overrun.error .... Standard error output when trying to convert
                                the Cube file (running 'cube2ascii')

  002-buffer-overrun.txt ...... Converted data (up to the buffer overrun)

    Note: The ASCII output was generated using the command line options
          "--resample=none" and "--timing-control=none". (Options were used
          to ease debugging.)

  The 'cube2ascii' utility will begin to convert both files until it
  encounters the buffer overrun system event. (Located in the first input
  file.) Processing stops at the data gap i.e. the second file is never
  converted.

  The Cube files were recorded in January 2023, underground in a mine in
  Ireland. Only relevant parts (for this test) were extracted from the input
  to reduce the overall file size. TAIP messages in the input were modified
  such that the GIPPtools will accept them as valid. (The recording took
  place underground without satellite reception.)


Test 003 -- Five byte sample block
----------------------------------

  The corrupt Cube input file of this test contains a faulty sample block 
  with a five byte long data value (instead of the expected 4 byte long 
  sample value).
  
  003-five-byte-sample.cube ... A corrupt Cube file
  
  003-five-byte-sample.error .. Standard error output when trying to convert 
                                the Cube file (running 'cube2ascii')

  The GIPPtools will abort processing of such files. Preceding valid
  samples will not (yet) be converted/recovered.
                                
  The trouble file / bug was reported by Ole Zeising, AWI in June 2018.                         
  

Test 004 -- Huge, corrupt sample block
--------------------------------------

  The last valid content of this Cube file is block #284896 (a sample block).
  The next sample block after this positions starts correctly but then the 
  file continues with "zero" bytes up to the end. This leads to the situation
  that (formally) the last "sample block" extends up to the end of the file 
  as the most significant bit is not set in any of the remaining bytes. 
  (Which would indicate the beginning of a new block).
  
  This leads to problems in two areas:
  
  - A (single) Cube block that does not completely fit into the internal byte 
    buffer allocated by the GIPPtools. This will result in endless loops if 
    not caught.
    
    Note: To test this situation, the part of the file containing "zeros" 
          must be larger than the used (read) byte buffer (currently 8 MByte). 
          Otherwise the error-condition will not trigger!
    
  - A sample block containing seemingly millions of recording channels.
    This exceeds the number of recording channels given in the Cube header
    block as well as the hard-coded limit of the GIPPtools (eight channels
    is the maximum).
  
    004-huge-sample-block.cube ... A corrupt sample file ending in several 
                                   megabytes of "zeros".
    004-huge-sample-block.error .. Standard error output running 'cube2ascii'.
    
    004-huge-sample-block.txt .... Sample data that can be recovered from the 
                                   corrupt Cube file (running 'cube2ascii').
    
    Note: The ASCII output was generated using the command line options 
          "--resample=none" and "--timing-control=none". They were used so 
          that the input file could be (manually) shrunk for this test case 
          as much as possible.
          
          
  The trouble file / bug was reported by Kristen Cook, Section 5.1 
  Geomorphology, GFZ in August 2018.
  