readINW

Description

readINW is a utility designed to parse raw binary Optech INW (Integrated Navigational and Waveform) data files and extract waveform information. It processes these files, identifies different waveform types (PMT, GAPD, IR, RAMAN), and then writes a summary of each waveform record (timestamp, counter, and byte offsets/lengths) to a .wave file, and the actual 16-bit waveform trace data to a .16_data file.

This tool essentially “unpacks” the raw INW data into a more usable format for subsequent processing by other Optech-related tools.

Usage 

readINW <infile> <outfile_prefix> [-noraman] [-v]

Arguments

Option Description  
<infile> Required. The path to the input raw binary Optech INW file.  
<outfile_prefix> Required. The base name for the output files. The tool will generate <outfile_prefix>.wave (summary) and <outfile_prefix>.16_data (raw waveform traces).  
-noraman (Present in USAGE but its effect is inverted in code logic) Intended to ignore RAMAN waveforms, but its current implementation seems to manage handling with or without RAMAN based on existence.  
-v Enable verbose output.  

Data Structures

  • optech_waveform: This structure holds summary information for each waveform record, including timestamp, counter, and byte offsets/number of samples for PMT, GAPD, IR, and RAMAN waveforms.

How It Works

  1. File Opening: Opens the input raw INW file for reading. Opens two output files: <outfile_prefix>.wave for writing waveform record summaries, and <outfile_prefix>.16_data for writing raw 16-bit waveform traces.
  2. INW Header Skipping: Reads and discards the first 4096 bytes, assumed to be a header (inw_head).
  3. Record Processing Loop: Reads the INW file in fixed-size blocks (992 bytes, representing all_trace) until the end of the file:
    • Timestamp Extraction: Extracts timestamp from the first 8 bytes of the all_trace block.
    • Waveform Trace Data Writing: For records beyond a SKIP_PINGS threshold (4 pings), it writes 984 bytes of all_trace (converted to 16-bit shorts) to the .16_data file.
    • Waveform Structure Population: Populates an optech_waveform structure (owave) with the extracted timestamp, a counter, and fixed numbers of samples for PMT, GAPD, IR, and RAMAN channels. It sets PMT_byte_offset to the current file position in datfile.
    • Waveform Structure Writing: If the current record counter is greater than SKIP_PINGS, it writes the owave structure to the .wave file.
  4. Cleanup: Closes all open files.

Output Files

  • <outfile_prefix>.wave: A binary file containing optech_waveform summary structures.
  • <outfile_prefix>.16_data: A binary file containing raw 16-bit waveform trace data.

Dependencies

  • support.h: For general utility functions and error handling.
  • Optech_waveform.h: For optech_waveform data structure.

Notes

Byte Order and Alignment: The code explicitly warns that writing and reading is “not byte order or dstructure alignment independent.” This means the binary files (.wave, .16_data) generated by this tool (and expected by mergeOpWave) should ideally be processed on the same machine architecture to avoid endianness or padding issues. -noraman flag: The -noraman option’s description in USAGE and its actual implementation logic in the provided code snippet (if (noraman) { error(...) }) appear contradictory or incomplete. It seems designed to prevent processing if RAMAN data exists while this flag is set. The code includes a commented-out section for parsing an ASCII version of the waveform data, suggesting an alternative input format was considered or used previously.