0
# Header Access
1

2
Access to binary header fields and trace header fields using meaningful enumeration constants instead of raw byte offsets. Headers contain essential metadata about SEG-Y file structure and individual trace properties.
3

4
## Capabilities
5

6
### Binary Header Access
7

8
Access to file-level binary header fields that describe the overall file structure, sample format, and acquisition parameters.
9

10
```python { .api }
11
class BinField:
12
    """Binary header field byte offset constants."""
13
    
14
    # Job and line identification
15
    JobID = 3201              # Job identification number
16
    LineNumber = 3205         # Line number (for 2D), reel number (for 3D)
17
    ReelNumber = 3209         # Reel number
18
    
19
    # Trace counts and geometry
20
    Traces = 3213             # Number of data traces per ensemble
21
    AuxTraces = 3215          # Number of auxiliary traces per ensemble
22
    EnsembleFold = 3227       # Ensemble fold
23
    
24
    # Sample format and timing
25
    Interval = 3217           # Sample interval in microseconds
26
    IntervalOriginal = 3219   # Sample interval original recording
27
    Samples = 3221            # Number of samples per data trace
28
    SamplesOriginal = 3223    # Number of samples original recording
29
    Format = 3225             # Data sample format code
30
    
31
    # Extended fields for large files
32
    ExtTraces = 3261          # Extended number of data traces per ensemble
33
    ExtAuxTraces = 3265       # Extended number of auxiliary traces per ensemble
34
    ExtSamples = 3269         # Extended number of samples per data trace
35
    ExtSamplesOriginal = 3289 # Extended number of samples original recording
36
    ExtEnsembleFold = 3293    # Extended ensemble fold
37
    
38
    # SEG-Y revision and format
39
    SEGYRevision = 3501       # SEG Y format revision number
40
    SEGYRevisionMinor = 3502  # SEG Y format revision minor
41
    TraceFlag = 3503          # Fixed length trace flag
42
    ExtendedHeaders = 3505    # Number of 3200-byte extended textual headers
43
    
44
    # Processing and sorting
45
    SortingCode = 3229        # Trace sorting code
46
    VerticalSum = 3231        # Vertical sum code
47
    CorrelatedTraces = 3249   # Correlated data traces
48
    BinaryGainRecovery = 3251 # Binary gain recovered
49
    AmplitudeRecovery = 3253  # Amplitude recovery method
50
    MeasurementSystem = 3255  # Measurement system
51
    
52
    # Sweep parameters (for vibroseis)
53
    SweepFrequencyStart = 3233 # Sweep frequency at start (Hz)
54
    SweepFrequencyEnd = 3235   # Sweep frequency at end (Hz)
55
    SweepLength = 3237         # Sweep length (ms)
56
    Sweep = 3239              # Sweep type code
57
    SweepChannel = 3241       # Trace number of sweep channel
58
    SweepTaperStart = 3243    # Sweep trace taper length at start (ms)
59
    SweepTaperEnd = 3245      # Sweep trace taper length at end (ms)
60
    Taper = 3247              # Taper type
61
    
62
    # Signal polarity
63
    ImpulseSignalPolarity = 3257 # Impulse signal polarity
64
    VibratoryPolarity = 3259     # Vibratory polarity code
65
```
66

67
**Usage Example:**
68

69
```python
70
with segyio.open('data.sgy') as f:
71
    # Read binary header fields
72
    sample_count = f.bin[segyio.BinField.Samples]
73
    sample_rate = f.bin[segyio.BinField.Interval]
74
    data_format = f.bin[segyio.BinField.Format]
75
    trace_count = f.bin[segyio.BinField.Traces]
76
    
77
    print(f"File contains {trace_count} traces")
78
    print(f"Sample rate: {sample_rate} microseconds")
79
    print(f"Samples per trace: {sample_count}")
80
    print(f"Data format code: {data_format}")
81
    
82
    # Modify binary header (if file opened for writing)
83
    if not f.readonly:
84
        f.bin[segyio.BinField.JobID] = 12345
85
        f.bin[segyio.BinField.LineNumber] = 100
86
```
87

88
### Trace Header Access
89

90
Access to trace-level header fields that contain positioning information, acquisition parameters, and trace-specific metadata.
91

92
```python { .api }
93
class TraceField:
94
    """Trace header field byte offset constants."""
95
    
96
    # Trace sequencing
97
    TRACE_SEQUENCE_LINE = 1    # Trace sequence number within line
98
    TRACE_SEQUENCE_FILE = 5    # Trace sequence number within file
99
    FieldRecord = 9            # Original field record number
100
    TraceNumber = 13           # Trace number within field record
101
    EnergySourcePoint = 17     # Energy source point number
102
    
103
    # CDP/CMP information
104
    CDP = 21                   # CDP ensemble number
105
    CDP_TRACE = 25             # Trace number within CDP ensemble
106
    CDP_X = 181               # CDP X coordinate
107
    CDP_Y = 185               # CDP Y coordinate
108
    
109
    # 3D geometry
110
    INLINE_3D = 189           # Inline number (3D surveys)
111
    CROSSLINE_3D = 193        # Crossline number (3D surveys)
112
    
113
    # Source and receiver positions
114
    SourceX = 73              # Source coordinate X
115
    SourceY = 77              # Source coordinate Y
116
    GroupX = 81               # Group coordinate X
117
    GroupY = 85               # Group coordinate Y
118
    offset = 37               # Distance from source to receiver group
119
    
120
    # Timing and sampling
121
    TRACE_SAMPLE_COUNT = 115  # Number of samples in this trace
122
    TRACE_SAMPLE_INTERVAL = 117 # Sample interval for this trace (microseconds)
123
    DelayRecordingTime = 109  # Delay recording time (ms)
124
    
125
    # Trace identification and type
126
    TraceIdentificationCode = 29 # Trace identification code
127
    
128
    # Elevations and corrections
129
    SourceElevation = 45      # Source elevation
130
    GroupElevation = 41       # Receiver group elevation
131
    SourceDepth = 49          # Source depth below surface
132
    GroupWaterDepth = 61      # Water depth at receiver group
133
    SourceWaterDepth = 57     # Water depth at source
134
    
135
    # Scaling factors  
136
    ElevationScalar = 69      # Elevation scalar
137
    CoordinateScalar = 71     # Coordinate scalar
138
    
139
    # Additional fields available (80+ total constants)
140
    # Including: timing, filtering, processing, measurement units, 
141
    # transduction constants, and extended 3D geometry fields
142
```
143

144
**Usage Example:**
145

146
```python
147
with segyio.open('3d_data.sgy') as f:
148
    # Read trace header for first trace  
149
    header = f.header[0]
150
    inline = header[segyio.TraceField.INLINE_3D]
151
    crossline = header[segyio.TraceField.CROSSLINE_3D]
152
    cdp = header[segyio.TraceField.CDP]
153
    
154
    print(f"First trace: IL={inline}, XL={crossline}, CDP={cdp}")
155
    
156
    # Read multiple trace headers
157
    headers = f.header[0:10]
158
    for i, hdr in enumerate(headers):
159
        il = hdr[segyio.TraceField.INLINE_3D] 
160
        xl = hdr[segyio.TraceField.CROSSLINE_3D]
161
        print(f"Trace {i}: IL={il}, XL={xl}")
162
    
163
    # Read coordinates
164
    source_x = header[segyio.TraceField.SourceX]
165
    source_y = header[segyio.TraceField.SourceY]
166
    cdp_x = header[segyio.TraceField.CDP_X]
167
    cdp_y = header[segyio.TraceField.CDP_Y]
168
    
169
    # Apply coordinate scaling if needed
170
    coord_scalar = header[segyio.TraceField.CoordinateScalar]
171
    if coord_scalar < 0:
172
        scale_factor = -1.0 / coord_scalar
173
    else:
174
        scale_factor = coord_scalar
175
        
176
    actual_x = cdp_x * scale_factor
177
    actual_y = cdp_y * scale_factor
178
```
179

180
### Sample Format Codes
181

182
Enumeration of data sample format codes used in the binary header Format field.
183

184
```python { .api }
185
class SegySampleFormat:
186
    """Data sample format codes."""
187
    
188
    IBM_FLOAT_4_BYTE = 1           # 4-byte IBM floating point (most common legacy)
189
    SIGNED_INTEGER_4_BYTE = 2      # 4-byte two's complement integer
190
    SIGNED_SHORT_2_BYTE = 3        # 2-byte two's complement integer
191
    FIXED_POINT_WITH_GAIN_4_BYTE = 4 # 4-byte fixed-point with gain
192
    IEEE_FLOAT_4_BYTE = 5          # 4-byte IEEE floating point (most common modern)
193
    IEEE_FLOAT_8_BYTE = 6          # 8-byte IEEE floating point
194
    SIGNED_CHAR_3_BYTE = 7         # 3-byte two's complement integer
195
    SIGNED_CHAR_1_BYTE = 8         # 1-byte two's complement integer
196
    SIGNED_INTEGER_8_BYTE = 9      # 8-byte two's complement integer
197
    UNSIGNED_INTEGER_4_BYTE = 10   # 4-byte unsigned integer
198
    UNSIGNED_SHORT_2_BYTE = 11     # 2-byte unsigned integer
199
    UNSIGNED_INTEGER_8_BYTE = 12   # 8-byte unsigned integer
200
    UNSIGNED_INTEGER_3_BYTE = 15   # 3-byte unsigned integer
201
    UNSIGNED_CHAR_1_BYTE = 16      # 1-byte unsigned integer
202
```
203

204
### Trace Sorting Format
205

206
Enumeration of trace sorting format codes used in the binary header SortingCode field.
207

208
```python { .api }
209
class TraceSortingFormat:
210
    """Trace sorting format codes."""
211
    
212
    UNKNOWN_SORTING = 0    # Unknown or unsorted
213
    CROSSLINE_SORTING = 1  # Crossline sorted (fast crossline, slow inline)
214
    INLINE_SORTING = 2     # Inline sorted (fast inline, slow crossline)
215
```
216

217
**Usage Example:**
218

219
```python
220
with segyio.open('data.sgy') as f:
221
    format_code = f.bin[segyio.BinField.Format]
222
    
223
    if format_code == segyio.SegySampleFormat.IBM_FLOAT_4_BYTE:
224
        print("IBM floating point data")
225
    elif format_code == segyio.SegySampleFormat.IEEE_FLOAT_4_BYTE:
226
        print("IEEE floating point data")
227
    
228
    sorting = f.bin[segyio.BinField.SortingCode]
229
    if sorting == segyio.TraceSortingFormat.INLINE_SORTING:
230
        print("File is inline sorted")
231
    elif sorting == segyio.TraceSortingFormat.CROSSLINE_SORTING:
232
        print("File is crossline sorted")
233
```
234

235
## Text Header Access
236

237
Access to EBCDIC textual headers containing human-readable file description and processing history.
238

239
```python
240
with segyio.open('data.sgy') as f:
241
    # Read main textual header (EBCDIC)
242
    text_header = f.text[0]
243
    print(text_header)
244
    
245
    # Read extended textual headers (if present)
246
    if f.ext_headers > 0:
247
        for i in range(1, f.ext_headers + 1):
248
            ext_header = f.text[i]
249
            print(f"Extended header {i}:")
250
            print(ext_header)
251
```
252

253
## Common Header Operations
254

255
### Coordinate Transformations
256

257
```python
258
def apply_coordinate_scaling(coordinate, scalar):
259
    """Apply SEG-Y coordinate scaling factor."""
260
    if scalar == 0:
261
        return coordinate
262
    elif scalar < 0:
263
        return coordinate / (-scalar)
264
    else:
265
        return coordinate * scalar
266

267
# Usage
268
with segyio.open('data.sgy') as f:
269
    header = f.header[0]
270
    
271
    cdp_x = header[segyio.TraceField.CDP_X]
272
    cdp_y = header[segyio.TraceField.CDP_Y]
273
    scalar = header[segyio.TraceField.CoordinateScalar]
274
    
275
    actual_x = apply_coordinate_scaling(cdp_x, scalar)
276
    actual_y = apply_coordinate_scaling(cdp_y, scalar)
277
```
278

279
### Survey Geometry Analysis
280

281
```python
282
def analyze_geometry(filename):
283
    """Analyze SEG-Y file geometry from headers."""
284
    with segyio.open(filename) as f:
285
        # Get inline/crossline ranges
286
        ilines = set()
287
        xlines = set()
288
        
289
        for i in range(min(1000, f.tracecount)):  # Sample first 1000 traces
290
            header = f.header[i]
291
            ilines.add(header[segyio.TraceField.INLINE_3D])
292
            xlines.add(header[segyio.TraceField.CROSSLINE_3D])
293
        
294
        return {
295
            'inline_range': (min(ilines), max(ilines)),
296
            'crossline_range': (min(xlines), max(xlines)),
297
            'inline_count': len(ilines),
298
            'crossline_count': len(xlines)
299
        }
300
```