0
# Segyio
1

2
A Python library for easy interaction with SEG-Y formatted seismic data files. Segyio provides a low-level C interface with Python bindings that offers fast, streaming-based file operations with numpy integration for efficient seismic data processing.
3

4
## Package Information
5

6
- **Package Name**: segyio
7
- **Language**: Python
8
- **Installation**: `pip install segyio`
9
- **Dependencies**: numpy >= 1.10
10

11
## Core Imports
12

13
```python
14
import segyio
15
```
16

17
Common patterns for working with SEG-Y files:
18

19
```python
20
import segyio
21
import numpy as np
22
```
23

24
## Basic Usage
25

26
```python
27
import segyio
28
import numpy as np
29

30
# Open an existing SEG-Y file for reading
31
with segyio.open('seismic.sgy') as f:
32
    # Get basic file information
33
    print(f"Samples per trace: {len(f.samples)}")
34
    print(f"Number of traces: {f.tracecount}")
35
    print(f"Inline range: {f.ilines[0]} to {f.ilines[-1]}")
36
    print(f"Crossline range: {f.xlines[0]} to {f.xlines[-1]}")
37
    
38
    # Read a single trace
39
    trace = f.trace[0]
40
    
41
    # Read an inline
42
    inline_data = f.iline[100]
43
    
44
    # Read trace headers
45
    headers = f.header[0:10]
46

47
# Create a new SEG-Y file
48
spec = segyio.spec()
49
spec.samples = np.arange(0, 1000, 4)  # 0-1000ms, 4ms intervals
50
spec.ilines = range(1, 11)  # Inlines 1-10
51
spec.xlines = range(1, 21)  # Crosslines 1-20
52

53
with segyio.create('output.sgy', spec) as f:
54
    # Write trace data
55
    for i, trace_data in enumerate(synthetic_data):
56
        f.trace[i] = trace_data
57
```
58

59
## Architecture
60

61
Segyio's architecture centers around streaming file operations and structured data access:
62

63
- **File Handle (SegyFile)**: Main interface for SEG-Y file operations with multiple access modes
64
- **Access Modes**: Different views of the same data (trace, iline, xline, depth_slice, gather, header)
65
- **Enumerations**: Type-safe constants for header fields and format codes
66
- **Specifications**: Template system for creating new SEG-Y files with proper geometry
67
- **Streaming Operations**: Memory-efficient processing of large seismic volumes
68

69
This design enables both low-level control for performance and high-level convenience for common seismic processing tasks.
70

71
## Capabilities
72

73
### File Operations
74

75
Core functionality for opening existing SEG-Y files, creating new files, and managing file handles with proper resource management.
76

77
```python { .api }
78
def open(filename, mode="r", iline=189, xline=193, strict=True, ignore_geometry=False, endian='big'):
79
    """Open a SEG-Y file for reading or writing."""
80

81
def create(filename, spec):
82
    """Create a new SEG-Y file with specified geometry."""
83

84
class SegyFile:
85
    """Main file handle for SEG-Y operations."""
86
```
87

88
[File Operations](./file-operations.md)
89

90
### Header Access
91

92
Access to binary header fields and trace header fields using meaningful enumeration constants instead of byte offsets.
93

94
```python { .api }
95
class BinField:
96
    """Binary header field byte offset constants."""
97
    
98
class TraceField:
99
    """Trace header field byte offset constants."""
100

101
class SegySampleFormat:
102
    """Data sample format codes."""
103
```
104

105
[Header Access](./header-access.md)
106

107
### Data Access Modes
108

109
Multiple specialized interfaces for accessing seismic data organized by traces, inlines, crosslines, depth slices, and gathers.
110

111
```python { .api }
112
# Access modes available on SegyFile instances
113
f.trace[i]        # Individual traces
114
f.iline[il]       # Inline slices
115
f.xline[xl]       # Crossline slices  
116
f.depth_slice[d]  # Horizontal depth/time slices
117
f.gather[cdp]     # Pre-stack gathers
118
```
119

120
[Data Access](./data-access.md)
121

122
### Utility Functions
123

124
Helper functions for format conversion, metadata extraction, array-to-SEG-Y conversion, and common seismic processing operations.
125

126
```python { .api }
127
def dt(f, fallback_dt=4000.0):
128
    """Infer sample rate from SEG-Y file."""
129

130
def cube(f):
131
    """Read full 3D cube into memory."""
132

133
def from_array(filename, data, **kwargs):
134
    """Create SEG-Y file from numpy array."""
135
```
136

137
[Utilities](./utilities.md)
138

139
### Seismic Unix Compatibility
140

141
Seismic Unix field name aliases and specialized file handling for SU format compatibility.
142

143
```python { .api }
144
import segyio.su
145

146
# Use SU field names instead of numeric constants
147
segyio.su.tracl  # Trace sequence number within line
148
segyio.su.cdp    # CDP ensemble number
149
segyio.su.offset # Source-receiver offset
150
```
151

152
[Seismic Unix](./seismic-unix.md)