Igor Pro binary waves and packed experiments
WaveMetrics Igor Pro stores data as waves: arrays of up to four dimensions with a name, units, a scaling per dimension and an optional note. A binary wave file (.ibw, older Macintosh files .bwav) holds one wave. A packed experiment (.pxp, templates .pxt) holds a whole Igor session: waves in data folders, variables, procedures and the command history. Patch-clamp labs (NeuroMatic, Patcher’s Pal), atomic force microscopes (Asylum Research), synchrotron beamlines and many spectroscopy groups save their data this way.
Derived from WaveMetrics’ public technical notes TN003 (Igor binary file format) and PTN003 (writing packed files), and from hex dumps of corpus files. igor2 (LGPL) is run only as a black-box oracle (see Validation). Every name below is ours. See docs/provenance/igor.md. Format id igor, crate openreadout-igor.
What OpenReadout returns
Every numeric wave becomes a trace or an image:
- a wave of one dimension is a trace with one channel (the wave’s name); a wave of two dimensions whose columns carry labels (a force curve’s
Raw,Defl,ZSnsr) is a trace with one channel per column. Complex waves give a real and an imaginary channel. When the row units are a time unit (s,ms, …) the row step givessample_rate_hzand the row offsetstart_s; otherwiseextra.axisholds the row scaling (first,step,last,unit) and the rate is 0; - any other wave of two to four dimensions is an image: rows are X (Igor shows rows along the horizontal axis), columns Y, layers channels when they carry labels (AFM images:
HeightRetrace,AmplitudeRetrace, …) and Z planes otherwise, chunks time points. Length units (m,mm,µm,nm,pm,Å) give the physical pixel size; a time unit on the chunks givestime_increment_s.
Traces and images are numbered in file order. The trace or image name is the wave name in a binary wave and root:folder:…:name in a packed experiment. Values are returned as stored (no scaling: Igor waves hold physical values). Text waves, waves without points and waves saved without their data (governed by a formula) are not exposed; text waves’ elements are in the vendor metadata.
extra of every trace and image: wave (the full name), wave_version, wave_type (float32, float64, int8, … or complex float32), dimensions, byte_order, wave_created and wave_modified (local time of the writing computer, no zone), full_scale [bottom, top] when the file marks it valid, formula, note_bytes, and in packed experiments application (Igor Pro) and application_version (from the recreation procedures, e.g. 8.040). Images add data_units, axes (per dimension: label, unit, first, step, size) and layers_as (channels or z). format_version is ibw N (N = the binary-wave version) or pxp.
The wave creation time is not the acquisition time (Asylum Research files carry the same creation time in every file), so acquired_at is not set.
Byte order
A binary wave starts with its version (1, 2, 3 or 5) as a 16-bit integer: a first byte of 0 means big-endian (68k and PowerPC Macintosh), anything else little-endian. A packed experiment’s byte order is the one under which its record headers chain (packed_endian).
Binary wave (wave.rs)
Binary header
| version | bytes (bin_header_len) |
fields (offset) |
|---|---|---|
| 1 | 8 | version (0), wave-section size (2), checksum (6) — from TN003’s sizes, not seen |
| 2 | 16 | version (0), wave-section size (2), note size (6), unused (10), checksum (14) |
| 3 | 20 | version (0), wave-section size (2), note size (6), formula size (10), unused (14), checksum (18) — from TN003’s sizes, not seen |
| 5 | 64 (BIN_HEADER5) |
version (0), checksum (2), wave-section size (4), formula size (8), note size (12), extended data-units size (16), extended dimension-units sizes ×4 (20), dimension-label sizes ×4 (36), string-indices size (52), two unused fields (56, 60) |
The checksum: the first 134 / 142 / 146 / 384 bytes (checksum_len; versions 1 / 2 / 3 / 5) summed as 16-bit integers in the file’s byte order give 0 (checksum_zero). It is the detection signature.
Wave header, versions 1–3 (110 bytes, WAVE_HEADER2, from the end of the binary header)
| offset | field |
|---|---|
| 0 | wave type (16-bit) |
| 6 | name, 20 bytes, NUL-terminated |
| 34 | data units, 4 bytes |
| 38 | X units, 4 bytes |
| 42 | point count (32-bit) |
| 48, 56 | X step and offset (doubles): x = offset + step × point |
| 68, 70, 78 | full-scale flag (16-bit), top and bottom (doubles) |
| 96 | creation time (32-bit, seconds since 1904-01-01; not in version 1) |
| 102 | modification time |
The data follows (110 bytes after the wave header’s start), then 16 bytes of padding (PADDING2), then the note (version 2) or the formula and the note (version 3). Data bytes = wave-section size − 126.
Wave header, version 5 (320 bytes, WAVE_HEADER5, from offset 64)
| offset | field |
|---|---|
| 4, 8 | creation and modification times (seconds since 1904-01-01) |
| 12 | point count (all dimensions) |
| 16 | wave type (16-bit) |
| 26 | wave-header version (1) |
| 28 | name, 32 bytes, NUL-terminated |
| 68 | elements per dimension ×4 (rows, columns, layers, chunks; 0 = unused) |
| 84 | step per dimension ×4 (doubles) |
| 116 | offset per dimension ×4 (doubles) |
| 148 | data units, 4 bytes |
| 152 | units per dimension, 4 × 4 bytes |
| 172, 176, 184 | full-scale flag, top, bottom |
The data starts at 384; data bytes = wave-section size − 320. Then, each present when its size is not 0: the formula, the note, the extended data units, the extended units of dimensions 0–3 (they replace the 4-byte fields when units are longer than 3 bytes), the dimension labels of dimensions 0–3 (32-byte NUL-terminated fields: one for the dimension, then one per element), the string indices (text waves: the cumulative end offset of each element, 32-bit). Text is UTF-8 when it decodes as such and Latin-1 otherwise (igor_text); notes use carriage returns between lines.
Data is stored rows first, then columns, layers and chunks; complex values as real then imaginary.
Wave types (WaveKind, NumberType)
| value | meaning | seen in the corpus |
|---|---|---|
| 0 | text | yes |
| 2 | 32-bit float | yes |
| 4 | 64-bit float | yes |
| 8 | 8-bit integer | yes |
| 16 | 16-bit integer | inferred |
| 32 | 32-bit integer | inferred |
| 128 | 64-bit integer | inferred |
| +64 | unsigned (integers) | inferred |
| +1 | complex | inferred |
Other bit patterns are refused (wave_type).
Data after the wave
Asylum Research AFM images append a byte preview and its description after the wave’s last section. The bytes are counted (trailing_bytes, a note) and not read.
Packed experiment (packed.rs)
A chain of records to the end of the file. Each record header is 8 bytes (RECORD_HEADER): kind (16-bit; the high bit marks a record superseded by a later one, SUPERSEDED, which is skipped), version (16-bit) and the length of the data (32-bit).
| kind | RecordKind |
data |
|---|---|---|
| 1 | Variables |
variables of the current data folder (below) |
| 2 | History |
command history (text) |
| 3 | Wave |
one binary wave (version 2, 3 or 5) |
| 4 | Recreation |
recreation procedures (text); the first line names the platform and Igor version (// Platform=WindowsNT, IGORVersion=8.040, …) |
| 5 | Procedures |
the procedure window (text) |
| 7 | GetHistory |
no data |
| 8 | PackedFile |
a packed notebook or procedure file (not decoded) |
| 9 | FolderStart |
a data folder’s name, 32 bytes, NUL-terminated |
| 10 | FolderEnd |
no data: back to the parent folder |
| other | Other |
window, package and platform settings: skipped |
Detection (looks_like_packed): the record headers in the first 64 KiB chain without a gap, and the chain holds a wave, variables, folder or text record. With a .pxp/.pxt extension that is definite, without one likely.
Variables record (parse_variables)
A header (version 1: version, system-variable count, user numeric count, user string count, 16-bit each; version 2 adds dependent numeric and dependent string counts), the system variables K0, K1, … as 32-bit floats (kept for the root folder only), the user numeric variables (56 bytes each, NUMBER_VARIABLE: a 32-byte name, a 16-bit field, the numeric type, the real and imaginary parts as doubles, 4 unused bytes), the user string variables (a 32-byte name, the length — 16-bit in version 1, 32-bit in version 2 — and the bytes). Dependent variables are not decoded (reported in check). Variables are vendor metadata.
Vendor metadata (info --view full --vendor)
container, byte_order, waves (per wave: path, name, version, type, type_name, points, dimensions, steps, offsets, data_units, dimension_units, created, modified, data_offset, data_bytes, checksum_ok, formula, note (lines joined with newlines), note_fields (the note’s Key: value lines when most lines have that shape: Asylum Research settings such as ScanSize or SpringConstant), dimension_labels, and for text waves values, at most 1000), and for packed experiments variables (per record: folder, version, variables with name and value/imaginary/text, system, undecoded), igor_version, platform and texts (history, recreation procedures and procedures: record, bytes, text up to 1 MiB). info --view structure lists every wave (offset, size, type, dimensions, what it became) and every other record.
check
| code | severity | meaning |
|---|---|---|
checksum |
warning | the headers do not sum to zero |
wave_type |
error | the wave type names no known type |
bad_points, bad_size, dims, data_size |
error | point count, section sizes and dimension sizes disagree with each other or with the data |
truncated |
error | the data, a section or a record runs past the end of the file or record |
long_text, labels |
warning | a note or formula longer than 4 MiB (cut), dimension labels not a multiple of 32 bytes |
bad_record |
error | a record with a negative length |
folders |
warning | data folders that end without a start or never end |
bad_wave |
error | a wave record that is not a binary wave |
variables |
warning | a variables record not fully decoded |
superseded, formula_without_data, trailing_bytes |
info | superseded records skipped; a wave saved without its data; bytes after a binary wave |
too_many_records, too_many_waves |
warning | more than 4 million records or 1 million waves |
A plane or trace whose data lies outside the file is a corrupt-file error (exit 4).
Validation (2026-10-19)
Corpus files from 33 Zenodo records and NeuralEnsemble’s test data (CC-BY-4.0, CC0-1.0, CC-BY-SA-4.0): binary waves of versions 2 (big- and little-endian) and 5 (1-D spectra and time series, 2-D maps, AFM images with three and four labelled layers, a force curve with labelled columns, a 3-D stack), packed experiments written by Igor Pro 6.2, 8.0 and 9.0 on Windows and Macintosh (up to 662 waves, nested data folders, text waves, an 8-bit integer wave, 2-D images). Ground truth: igor2 0.5.14 run as a black box (oracle/igor_oracle.py); traces compare names, units, sample counts, the first values and the xxh3 of every value, images their geometry, pixel type, physical size and the hash of every plane. igor2 fails on one packed experiment (Zenodo 10473302 Fig3.pxp), which is therefore not in the corpus.
Vocabulary (every public identifier in openreadout-igor/src must appear here)
| identifier | meaning |
|---|---|
IgorReader, IgorDataset, FORMAT_ID, open, open_input, igor |
reader, opened file (and its parsed structure), format id igor |
looks_like_wave, looks_like_packed, wave_endian, packed_endian |
detection and byte order |
wave, packed, dataset, parse_wave, parse_file, walk, parse_variables |
modules and parsers |
Wave, version, endian, start, end, wave_type, kind, name, points, dims, steps, offsets, data_units, dim_units, full_scale, created, modified, data_offset, data_len, formula, note, labels, string_indices, checksum_ok, problems |
one parsed wave (above) |
rank, readable, element_labels, dimension_label, data_omitted, read_elements |
wave helpers: dimensions in use, data readable, labels, saved without data, read stored values as little-endian |
WaveKind { Text, Numeric }, number, unsigned, complex, from_type, element_bytes, pixel_type, dtype, label |
wave types |
NumberType { Float32, Float64, Int8, Int16, Int32, Int64 }, bytes |
sample types |
values_f64, text_values, igor_text, igor_time, checksum_zero, checksum_len, bin_header_len |
values, text, times (seconds since 1904), checksum |
BIN_HEADER5, WAVE_HEADER5, WAVE_HEADER2, PADDING2, MAX_TEXT, MAX_LABEL_BYTES, LABEL_FIELD |
sizes and limits |
Problem, code, detail, offset, fatal |
structure problems found while parsing |
Packed, records, Record, data_offset, superseded, folder, len |
the record chain |
RecordKind { Variables, History, Wave, Recreation, Procedures, GetHistory, PackedFile, FolderStart, FolderEnd, Other }, from_code |
record kinds |
RECORD_HEADER, MAX_RECORDS, MAX_RECORD_TEXT, MAX_VARIABLES_BYTES, SUPERSEDED, NUMBER_VARIABLE, NAME_FIELD |
record sizes and limits |
Variables, system, user, undecoded, Variable { Number, Text }, real, imaginary, number_type, value |
variables |
IgorFile, container, file_len, waves, variables, texts, igor_version, platform, trailing_bytes |
the parsed file |
Container { BinaryWave, Packed } |
binary wave or packed experiment |
WaveEntry, path, record, role, layers |
one wave and what it becomes |
Role { Trace, Image, Text, Empty, Unreadable } |
what a wave becomes |
LayerAxis { Channel, Z } |
how an image’s layers are exposed |
note_fields |
Key: value lines of a note |
MAX_TRACE_READ, MAX_PLANE_BYTES, MAX_TEXT_ELEMENTS, MAX_WAVES, MAX_TRACE_COLUMNS |
read limits |
How this reader was derived, file by file: provenance log.