MATLAB SEG-2 Toolkit

MATLAB toolkit for reading, writing, and working with SEG-2 seismic data files.

Vibe coded, use at your own risk. This code has not been reviewed or extensively tested yet.

This repository provides:

• a package +seg2 with public APIs for SEG-2 I/O and convenience utilities,
• an example script for round-trip write/read,
• a smoke test script for quick validation,
• a comprehensive API test suite for broader coverage.

Repository layout

• +seg2/ — public toolkit functions
• +seg2/private/ — internal helpers for parsing/encoding
• examples/seg2_roundtrip_demo.m — quick demo
• tests/seg2_smoke_test.m — smoke test
• tests/seg2_api_test.m — comprehensive API coverage test
• tests/seg2_negative_fixture_test.m — malformed-file fixture tests
• tests/run_all_tests.m — runs all test scripts

Requirements

• MATLAB (recommended R2018b+)
• No external dependencies

Installation

1. Copy this folder (matlab_seg2) to your machine.
2. In MATLAB, add the project root (the folder that contains +seg2) to your path:

projectRoot = '/path/to/matlab_seg2';  % <-- change this
addpath(projectRoot);
savepath;  % optional, persists path for future sessions

3. Verify installation:

which seg2.read -all
seg2.version

If which does not show +seg2/read.m, see the troubleshooting section.

Quick start

Run the included demo:

run('/path/to/matlab_seg2/examples/seg2_roundtrip_demo.m');

Expected output:

• Wrote: ...
• Read: ...
• Error: ...

Error is the max absolute round-trip difference. For DataFormatCode = 4 (float32), a small nonzero error is expected.

Minimal usage

Read a SEG-2 file

s = seg2.read('input.seg2');

Read metadata only (skip sample payloads)

info = seg2.info('input.seg2');

Convert traces to a matrix

[data, meta] = seg2.toMatrix(s);

Write a new SEG-2 file from an existing struct

seg2.write('output.seg2', s);

Write from a matrix (samples x traces)

data = randn(1000, 8);
seg2.write('output.seg2', data, ...
    'DataFormatCode', 4, ...
    'SampleInterval', 0.001);

Public API

seg2.read(filename, ...)

Read SEG-2 file into a struct.

Options:

• 'ReadData' (default true) — set false to read headers only
• 'TraceIndices' — numeric indices or logical mask to select traces

seg2.info(filename, ...)

Shortcut for header-only read (seg2.read(..., 'ReadData', false)).

seg2.write(filename, dataOrStruct, ...)

Write SEG-2 file from:

• a SEG-2 struct, or
• a numeric matrix (samples x traces) via seg2.fromMatrix.

Common options:

• 'ByteOrder' — 'little' or 'big'
• 'DataFormatCode' — SEG-2 sample format (see below)
• 'FileHeaders' — file-level headers
• 'TraceHeaders' — per-trace headers
• 'SampleInterval' — convenience header injection (SAMPLE_INTERVAL)
• 'StringTerminator' — 1 or 2 bytes
• 'LineTerminator' — 1 or 2 bytes
• 'Revision' — SEG-2 revision number

seg2.fromMatrix(data, ...)

Build a SEG-2 struct from samples x traces numeric data.

seg2.toMatrix(seg2Struct, ...)

Convert trace vectors back into a matrix, with padding when trace lengths differ.

Option:

• 'PadValue' (default NaN)

seg2.selectTraces(seg2Struct, indices)

Return a SEG-2 struct with only selected traces.

seg2.getHeaderValue(headers, key, defaultValue, ...)

Header lookup helper for:

• key/value pair arrays (struct('Key',...,'Value',...))
• scalar header structs

Options:

• 'Numeric' (default false) — convert output to numeric (double)
• 'CaseSensitive' (default false)

seg2.version()

Return toolkit version string.

SEG-2 sample format codes

Supported data format codes:

• 1 — 16-bit signed integer
• 2 — 32-bit signed integer
• 3 — 20-bit packed format (Appendix B style)
• 4 — 32-bit IEEE float
• 5 — 64-bit IEEE float

Notes:

• Format 3 requires sample count divisible by 4.
• Format 4 is often a good balance of precision and file size.
• Use format 5 when you need near-double round-trip precision.

Header input formats

Where headers are accepted (FileHeaders, TraceHeaders), you can use:

• key/value struct array with fields Key, Value
• scalar struct (FIELD_NAME = value)
• containers.Map
• N x 2 cell array of {key, value}

NOTE values can be provided as cell arrays of lines.

Validation script

Run smoke test:

run('/path/to/matlab_seg2/tests/seg2_smoke_test.m');

Run comprehensive API suite:

run('/path/to/matlab_seg2/tests/seg2_api_test.m');

Run malformed-file fixture suite:

run('/path/to/matlab_seg2/tests/seg2_negative_fixture_test.m');

Run everything:

run('/path/to/matlab_seg2/tests/run_all_tests.m');

Troubleshooting

“Unable to resolve name ...”

Usually path configuration or stale function cache.

Try:

restoredefaultpath;
rehash toolboxcache;
clear functions;
addpath('/path/to/matlab_seg2');
which seg2.read -all

Nonzero round-trip error in demo

Small error is expected for float32 writes (DataFormatCode = 4). Use DataFormatCode = 5 for higher precision.

“Trace pointers ... out of bounds”

File may be malformed or truncated. The reader includes strict pointer and block-bound checks by design.