readOpWave

Description

readOpWave is a utility designed to parse ASCII Optech waveform data files and convert them into a custom binary format suitable for processing by other OMG tools. It extracts waveform traces for different channels (PMT, GAPD, IR, RAMAN) and stores a summary of each waveform record (timestamp, counter, and byte offsets/lengths) in a .wave file, and the actual 16-bit waveform trace data in a .16_data file.

This tool essentially “unpacks” the ASCII waveform data into a more efficient binary representation, facilitating faster access and integration into the OMG processing pipeline.

Usage 

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

Arguments

Option Description
<infile> Required. The path to the input ASCII Optech waveform 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 handle RAMAN waveforms, but its current implementation seems to trigger an error if RAMAN data is present while this flag is set.
-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 ASCII waveform file for reading. Opens two output binary files: <outfile_prefix>.wave for writing waveform record summaries, and <outfile_prefix>.16_data for writing raw 16-bit waveform traces.
  2. Record Processing Loop: Reads the ASCII input file line by line, identifying blocks of data associated with different waveform types:
    • Waveform Type Detection: It checks for lines starting with “PMT”, “GAPD”, “IR”, or “RAMAN”.
    • Header Parsing: For each waveform type block, it parses the timestamp and counter.
    • Trace Data Extraction: It then reads subsequent lines containing trace_count and data values, accumulating them into a data array.
    • Waveform Structure Population: Populates an optech_waveform structure (owave) with the extracted timestamp, counter, and the number of samples (tslength) for the current waveform type. It sets PMT_byte_offset (or the offset for the respective waveform type) to the current file position in datfile.
    • Waveform Trace Writing: Writes the data array (as 16-bit shorts) to the .16_data file.
    • Waveform Summary Writing: If it’s a “complete” set of waveforms (e.g., after processing RAMAN or if -noraman is used after IR), it writes the owave structure (summary) to the .wave file.
  3. 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 is present while this flag is set, leading to an error. 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.