segyio

Development of segyio 2.0 (which improves support for SEG-Y 2.1 revision) happens in the main branch. 2.0.0-alpha.1 pre-release is published, but further development and support are, for the moment, put on hold.

Support for segyio 1.0 releases happens in segyio-1.x branch, mostly via backporting of relevant commits from main.

Documentation

The official documentation is hosted on readthedocs.

Introduction

Segyio is a small LGPL licensed C library for easy interaction with SEG-Y and Seismic Unix formatted seismic data, with language bindings for Python and Matlab. Segyio is an attempt to create an easy-to-use, embeddable, community-oriented library for seismic applications. Features are added as they are needed; suggestions and contributions of all kinds are very welcome.

To catch up on the latest development and features, see the changelog. To write future proof code, consult the planned breaking changes.

Feature summary

A low-level C interface with few assumptions; easy to bind to other languages
Read and write binary and textual headers
Read and write traces and trace headers
Simple, powerful, and native-feeling Python interface with numpy integration
Read and write seismic unix files
xarray integration with netcdf_segy
Some simple applications with unix philosophy

Getting started

When segyio is built and installed, you're ready to start programming! Check out the tutorial, examples, example programs, and example notebooks. For a technical reference with examples and small recipes, read the docs. API docs are also available with pydoc - start your favourite Python interpreter and type help(segyio), which should integrate well with IDLE, pycharm and other Python tools.

Quick start

import segyio
import numpy as np
with segyio.open('file.sgy') as f:
    for trace in f.trace:
        filtered = trace[np.where(trace < 1e-2)]

See the examples for more.

Get segyio

A copy of segyio is available both as pre-built binaries and source code:

In Debian unstable
- apt install python3-segyio
Wheels for Python from PyPI
- pip install segyio
Source code from github
- git clone https://github.com/statoil/segyio
Source code in tarballs

Build segyio

To build segyio you need:

A C99 compatible C compiler (tested mostly on gcc and clang)
A C++11 compiler for the Python extension and tests
CMake version 3.18 or greater
Python 3.10 or greater
numpy version 1.10 or greater
pytest

To build the documentation, you also need sphinx

To build and install segyio, perform the following actions in your console:

git clone https://github.com/equinor/segyio
mkdir segyio/build
cd segyio/build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
make
make install

make install must be done as root for a system install; if you want to install in your home directory, add -DCMAKE_INSTALL_PREFIX=~/ or some other appropriate directory, or make DESTDIR=~/ install. Please ensure your environment picks up on non-standard install locations (PYTHONPATH, LD_LIBRARY_PATH and PATH).

If you have multiple Python installations, or want to use some alternative interpreter, you can help cmake find the right one by passing -DPython_ROOT_DIR=/opt/python/binary along with install prefix and build type.

To build the matlab bindings, invoke CMake with the option -DBUILD_MEX=ON. In some environments the Matlab binaries are in a non-standard location, in which case you need to help CMake find the matlab binaries by passing -DMATLAB_ROOT=/path/to/matlab.

Developers

It's recommended to build in debug mode to get more warnings and to embed debug symbols in the objects. Substituting Debug for Release in the CMAKE_BUILD_TYPE is plenty.

Tests are located in the language/tests directories, and it's highly recommended that new features added are demonstrated for correctness and contract by adding a test. All tests can be run by invoking ctest. Feel free to use the tests already written as a guide.

After building segyio you can run the tests with ctest, executed from the build directory.

Please note that to run the Python examples you need to let your environment know where to find the Python library. It can be installed as a user, or on adding the segyio/build/python library to your pythonpath.

Tutorial

All code in this tutorial assumes segyio is imported, and that numpy is available as np.

import segyio
import numpy as np

This tutorial assumes you're familiar with Python and numpy. For a refresh, check out the python tutorial and numpy quickstart

Basics

Opening a file for reading is done with the segyio.open function, and idiomatically used with context managers. Using the with statement, files are properly closed even in the case of exceptions. By default, files are opened read-only.

with segyio.open(filename) as f:
    ...

Open accepts several options (for more a more comprehensive reference, check the open function's docstring with help(segyio.open). The most important option is the second (optional) positional argument. To open a file for writing, do segyio.open(filename, 'r+'), from the C fopen function.

Files can be opened in unstructured mode, either by passing segyio.open the optional arguments strict=False, in which case not establishing structure (inline numbers, crossline numbers etc.) is not an error, and ignore_geometry=True, in which case segyio won't even try to set these internal attributes.

The segy file object has several public attributes describing this structure:

f.ilines Inferred inline numbers
f.xlines Inferred crossline numbers
f.offsets Inferred offsets numbers
f.samples Inferred sample offsets (frequency and recording time delay)
f.unstructured True if unstructured, False if structured
f.ext_headers The number of extended textual headers

If the file is opened unstructured, all the line properties will be None.

Modes

In segyio, data is retrieved and written through so-called modes. Modes are abstract arrays, or addressing schemes, and change what names and indices mean. All modes are properties on the file handle object, support the len function, and reads and writes are done through f.mode[]. Writes are done with assignment. Modes support array slicing inspired by numpy. The following modes are available:

trace

The trace mode offers raw addressing of traces as they are laid out in the file. This, along with header, is the only mode available for unstructured files. Traces are enumerated 0..len(f.trace).

Reading a trace yields a numpy ndarray, and reading multiple traces yields a generator of ndarrays. Generator semantics are used and the same object is reused, so if you want to cache or address trace data later, you must explicitly copy.
```
>>> f.trace[10]
>>> f.trace[-2]
>>> f.trace[15:45]
>>> f.trace[:45:3]
```
header

With addressing behaviour similar to trace, accessing items yield header objects instead of numpy ndarrays. Headers are dict-like objects, where keys are integers, seismic unix-style keys (in segyio.su module) and segyio enums (segyio.TraceField).

Header values can be updated by assigning a dict-like to it, and keys not present on the right-hand-side of the assignment are unmodified.
```
>>> f.header[5] = { segyio.su.tracl: 10 }
>>> f.header[5].items()
>>> f.header[5][25, 37] # read multiple values at once
```
iline, xline

These modes will raise an error if the file is unstructured. They consider arguments to [] as the keys of the respective lines. Line numbers are always increasing, but can have arbitrary, uneven spacing. The valid names can be found in the ilines and xlines properties.

As with traces, getting one line yields an ndarray, and a slice of lines yields a generator of ndarrays. When using slices with a step, some intermediate items might be skipped if it is not matched by the step, i.e. doing f.line[1:10:3] on a file with lines [1,2,3,4,5] is equivalent of looking up 1, 4, 7, and finding [1,4].

When working with a 4D pre-stack file, the first offset is implicitly read. To access a different or a range of offsets, use comma separated indices or ranges, as such: f.iline[120, 4].
fast, slow

These are aliases for iline and xline, determined by how the traces are

Segyio

Install / Use

README