Segyio

segyio - SEG-Y Seismic Data

Quick Reference

import segyio

# Read
with segyio.open('seismic.sgy', 'r') as f:
    print(f.tracecount, len(f.samples))
    trace0 = f.trace[0]              # Single trace as numpy array
    data = segyio.tools.collect(f.trace[:])  # All traces

# 3D access (specify inline/xline byte locations)
with segyio.open('seismic.sgy', 'r', iline=189, xline=193) as f:
    inline_100 = f.iline[100]        # 2D array (xlines x samples)
    cube = segyio.tools.cube(f)      # Full 3D cube

# Write
spec = segyio.spec()
spec.samples = samples
spec.tracecount = n_traces
with segyio.create('output.sgy', spec) as f:
    f.trace[0] = data

Key Access Modes

| Mode | Description | |------|-------------| | f.trace[i] | Sequential trace access by index | | f.header[i] | Trace header access (dict-like) | | f.iline[n] | Inline slice (3D surveys) | | f.xline[n] | Crossline slice (3D surveys) | | f.depth_slice[n] | Horizontal time/depth slice | | f.text[0] | Text header (3200 bytes) | | f.bin | Binary header |

Essential Operations

Open and Inspect

with segyio.open('seismic.sgy', 'r') as f:
    print(f"Traces: {f.tracecount}")
    print(f"Samples: {len(f.samples)}")
    print(f"Sample interval: {f.samples[1] - f.samples[0]} ms")
    if f.ilines is not None:
        print(f"Inlines: {f.ilines}")
        print(f"Crosslines: {f.xlines}")

Read Trace Headers

with segyio.open('seismic.sgy', 'r') as f:
    header = f.header[0]
    print(header[segyio.TraceField.INLINE_3D])
    print(header[segyio.TraceField.CDP_X])

    # Get all values for one field
    inlines = f.attributes(segyio.TraceField.INLINE_3D)[:]

Read 3D Data

with segyio.open('seismic.sgy', 'r', iline=189, xline=193) as f:
    inline_data = f.iline[100]       # Shape: (n_xlines, n_samples)
    xline_data = f.xline[200]        # Shape: (n_ilines, n_samples)
    time_slice = f.depth_slice[250]  # Shape: (n_ilines, n_xlines)
    cube = segyio.tools.cube(f)      # Shape: (ilines, xlines, samples)

Read Unstructured Data

# For 2D lines or unsorted data
with segyio.open('seismic.sgy', 'r', ignore_geometry=True) as f:
    data = segyio.tools.collect(f.trace[:])

Create New SEG-Y

import numpy as np

spec = segyio.spec()
spec.samples = np.arange(500) * 4  # 4ms sample rate
spec.tracecount = 100
spec.format = 1  # IBM float

with segyio.create('output.sgy', spec) as f:
    for i in range(100):
        f.trace[i] = data[i]
        f.header[i] = {
            segyio.TraceField.TRACE_SEQUENCE_LINE: i + 1,
        }

Modify Existing File

with segyio.open('seismic.sgy', 'r+') as f:
    f.trace[0] = f.trace[0] * 2.0
    f.header[0][segyio.TraceField.CDP] = 999

Data Formats

| Code | Format | |------|--------| | 1 | IBM 4-byte float | | 2 | 4-byte signed integer | | 3 | 2-byte signed integer | | 5 | IEEE 4-byte float | | 8 | 1-byte signed integer |

When to Use vs Alternatives

| Tool | Best For | |------|----------| | segyio | Fast SEG-Y I/O, 3D inline/crossline access, header manipulation | | obspy | Broader seismology: FDSN access, waveform processing, event analysis | | segysak | xarray-based SEG-Y workflows, NetCDF conversion, labeled dimensions |

Use segyio when you need fast, low-level access to SEG-Y files -- reading traces, headers, 3D slices, or creating new SEG-Y files programmatically.

Use obspy instead when you need seismological processing beyond file I/O: instrument response removal, FDSN data fetching, or earthquake analysis.

Use segysak instead when you want xarray integration with labeled dimensions (inline, crossline, time) and easy conversion to NetCDF/Zarr.

Common Workflows

Read, inspect, and extract 3D seismic data

- [ ] Open file with `segyio.open()`, specify `iline=` and `xline=` byte positions
- [ ] Inspect geometry: trace count, sample count, inline/crossline ranges
- [ ] Read headers to verify coordinate and survey metadata
- [ ] Extract target inline/crossline slices or full cube
- [ ] Apply amplitude scaling or subset extraction as needed
- [ ] Write results to new SEG-Y or export as numpy arrays

Common Issues

| Issue | Solution | |-------|----------| | Geometry not detected | Specify iline= and xline= byte positions | | Can't read 3D slices | Use ignore_geometry=True for unstructured data | | Wrong inline/xline bytes | Check headers with f.header[0] to find correct bytes | | File not opening | Check file path, permissions, and SEG-Y format validity |

References

• [Trace Header Fields](references/header_fields.md) - Complete header field reference (bytes, types)
• [Troubleshooting](references/troubleshooting.md) - Common problems and solutions

Scripts

• [scripts/inspectsegy.py](scripts/inspectsegy.py) - Inspect SEG-Y file structure and geometry
• [scripts/extractsubset.py](scripts/extractsubset.py) - Extract subset of traces or inlines

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SteadfastAsArt
• Source: SteadfastAsArt/geoscience-skills
• License: MIT

Install and usage instructions live in the source repository linked above.