SEG-Y File

Altay Sansal

Feb 12, 2026

5 min read

SEG-Y Spec: A Conceptual Overview

The SegySpec is a structured model used to define the structure and content of a SEG-Y file. SEG-Y is a standard file format used in the geophysical industry for recording digital seismic data. In essence, this model serves as a blueprint for what a SEG-Y file should look like.

This class and its components provide a specified and flexible way to work with SEG-Y seismic data files programmatically, from defining the file structure and read/write operations, to customization for specialised use cases.

Conceptually a SEG-Y Revision 0 file looks like this on disk.

┌──────────────┐  ┌─────────────┐  ┌────────────────────┐        ┌────────────────────┐
│ Textual File │  │ Binary File │  │       Trace 1      │        │       Trace N      │
│ Header 3200B │─►│ Header 400B │─►│ Header 240B + Data │─ ... ─►│ Header 240B + Data │
└──────────────┘  └─────────────┘  └────────────────────┘        └────────────────────┘

Key Components

This spec model consists of several important components. Each of these components represent a particular section of a SEG-Y file.

SEGY-Standard

This attribute, segy_standard, corresponds to the specific SEG-Y standard that is being used. SEG-Y files can be of different revisions or standards, including custom ones.

It must be set to one of the allowed SegyStandard values.

Text File Header

The text_header stores the information required to parse the textual file header of the SEG-Y file. This includes important metadata that pertains to the seismic data in human-readable format.

Binary File Header

The binary_header item talks about the binary file header of the SEG-Y file. It is a set of structured and important information about the data in the file, stored in binary format for machines to read and process quickly and efficiently.

Binary headers are defined as HeaderSpec and are built by specifying header fields in the HeaderField format.

Extended Text Header

The ext_text_header is an optional attribute that provides space for extra information that can’t be fit within the regular text file header. This extended header can be used for additional human-readable metadata about the data.

Note

Extended text headers are were added in SEG-Y Revision 1.0.

Trace

The trace component is a spec definition for both the trace headers and the associated data. Trace headers contain specific information about each individual seismic trace in the dataset, and the trace data contains the actual numerical seismic data.

See also

TraceSpec

The Customize Method

The customize method is a way for users to tailor an existing SEG-Y spec to meet their specific requirements. It’s an optional tool that provides a way to update the various parts of the spec including the text header, binary header, extended text header, trace header and trace data. Note that the SEGY standard is always set to custom when using this method.

Reference

pydantic model segy.schema.SegySpec

A class defining a SEG-Y file spec.

Show JSON schema

{
   "title": "SegySpec",
   "description": "A class defining a SEG-Y file spec.",
   "type": "object",
   "properties": {
      "segyStandard": {
         "$ref": "#/$defs/SegyStandard",
         "description": "Base SEG-Y Revision."
      },
      "textHeader": {
         "$ref": "#/$defs/TextHeaderSpec",
         "description": "Textual file header spec."
      },
      "binaryHeader": {
         "$ref": "#/$defs/HeaderSpec",
         "description": "Binary file header spec."
      },
      "extTextHeader": {
         "anyOf": [
            {
               "$ref": "#/$defs/ExtendedTextHeaderSpec"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Extended textual header spec."
      },
      "trace": {
         "$ref": "#/$defs/TraceSpec",
         "description": "Trace header + data spec."
      },
      "endianness": {
         "anyOf": [
            {
               "$ref": "#/$defs/Endianness"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Endianness of SEG-Y file."
      }
   },
   "$defs": {
      "Endianness": {
         "description": "Enumeration class with three possible endianness values.\n\nAttributes:\n    BIG: Big endian.\n    LITTLE: Little endian.\n\nExamples:\n    >>> endian = Endianness.BIG\n    >>> print(endian.symbol)\n    >",
         "enum": [
            "big",
            "little"
         ],
         "title": "Endianness",
         "type": "string"
      },
      "ExtendedTextHeaderSpec": {
         "description": "A class representing spec for SEG-Y extended textual headers.",
         "properties": {
            "spec": {
               "$ref": "#/$defs/TextHeaderSpec",
               "description": "Extended text header spec."
            },
            "count": {
               "default": 0,
               "description": "Number of extended text headers.",
               "minimum": 0,
               "title": "Count",
               "type": "integer"
            },
            "offset": {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Starting byte offset.",
               "title": "Offset"
            }
         },
         "required": [
            "spec"
         ],
         "title": "ExtendedTextHeaderSpec",
         "type": "object"
      },
      "HeaderField": {
         "description": "A class representing header field spec.\n\nExamples:\n    A named float starting at byte location 9:\n\n    >>> field = HeaderField(\n    >>>     name=\"my_var\",\n    >>>     format=\"float32\",\n    >>>     byte=9,\n    >>> )\n\n    The name, byte, and offset fields will only be used if the structured\n    field is used within the context of a :class:`HeaderSpec`. Offset is\n    calculated automatically from byte location.\n\n    >>> field.name\n    my_var\n    >>> field.byte\n    9\n    >>> field.offset\n    8\n\n    The `dtype` property is inherited from :class:`DataFormat`.\n\n    >>> field.dtype\n    dtype('float32')",
         "properties": {
            "name": {
               "description": "The short name of the field.",
               "title": "Name",
               "type": "string"
            },
            "byte": {
               "description": "Field's start byte location.",
               "minimum": 1,
               "title": "Byte",
               "type": "integer"
            },
            "format": {
               "$ref": "#/$defs/ScalarType",
               "description": "The data type of the field."
            }
         },
         "required": [
            "name",
            "byte",
            "format"
         ],
         "title": "HeaderField",
         "type": "object"
      },
      "HeaderSpec": {
         "description": "A class representing a header specification.\n\nExamples:\n    Let's build a header from scratch!\n\n    We will define three fields with different names, data-types, and\n    start byte locations.\n\n    >>> field1 = HeaderField(\n    >>>     name=\"foo\",\n    >>>     format=\"int32\",\n    >>>     byte=1,\n    >>> )\n    >>> field2 = HeaderField(\n    >>>     name=\"bar\",\n    >>>     format=\"int16\",\n    >>>     byte=5,\n    >>> )\n    >>> field3 = HeaderField(\n    >>>     name=\"fizz\",\n    >>>     format=\"int32\",\n    >>>     byte=17,\n    >>> )\n\n    Note that the fields span the following byte ranges:\n\n    * `field1` between bytes `[0, 4)`\n    * `field2` between bytes `[4, 6)`\n    * `field3` between bytes `[16, 20)`\n\n    The gap between `field2` and `field3` will be padded with `void`. In\n    this case we expect to see an item size of 20-bytes (total length of\n    the header struct).\n\n    >>> header = HeaderSpec(\n    >>>     fields=[field1, field2, field3],\n    >>> )\n\n    Now let's look at its data type:\n\n    >>> header.dtype\n    dtype({'names': ['foo', 'bar', 'fizz'], 'formats': ['<i4', '<i2', '<i4'], 'offsets': [0, 4, 16], 'itemsize': 20})\n\n    If we wanted to pad the end of the struct (to fit a specific byte range),\n    we would provide the item_size in the spec. If we set it to 30, this means\n    that we padded the struct by 10 bytes at the end.\n\n    >>> header = HeaderSpec(\n    >>>     fields=[field1, field2, field3],\n    >>>     item_size=30,\n    >>> )\n\n    Now let's look at its data type:\n\n    >>> header.dtype\n    dtype({'names': ['foo', 'bar', 'fizz'], 'formats': ['<i4', '<i2', '<i4'], 'offsets': [0, 4, 16], 'itemsize': 30})\n\n    To see what's going under the hood, we can look at a lower level numpy\n    description of the `dtype`. Here we observe all the gaps (void types).\n\n    >>> header.dtype.descr\n    [('foo', '<i4'), ('bar', '<i2'), ('', '|V10'), ('fizz', '<i4'), ('', '|V10')]",
         "properties": {
            "fields": {
               "description": "List containing multiple header field spec instances.",
               "items": {
                  "$ref": "#/$defs/HeaderField"
               },
               "title": "Fields",
               "type": "array"
            },
            "itemSize": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Expected size of the struct.",
               "title": "Itemsize"
            },
            "offset": {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Starting byte offset.",
               "title": "Offset"
            },
            "endianness": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Endianness"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Endianness of structured data type."
            }
         },
         "required": [
            "fields"
         ],
         "title": "HeaderSpec",
         "type": "object"
      },
      "ScalarType": {
         "description": "A class representing scalar data types.",
         "enum": [
            "ibm32",
            "int64",
            "int32",
            "int16",
            "int8",
            "uint64",
            "uint32",
            "uint16",
            "uint8",
            "float64",
            "float32",
            "float16",
            "S8"
         ],
         "title": "ScalarType",
         "type": "string"
      },
      "SegyStandard": {
         "description": "Allowed values for SEG-Y standards in SegySpec.",
         "enum": [
            -1.0,
            0.0,
            1.0,
            2.0,
            2.1
         ],
         "title": "SegyStandard",
         "type": "number"
      },
      "TextHeaderEncoding": {
         "description": "Supported textual header encodings.",
         "enum": [
            "ascii",
            "ebcdic"
         ],
         "title": "TextHeaderEncoding",
         "type": "string"
      },
      "TextHeaderSpec": {
         "description": "A class representing spec for SEG-Y textual headers (8-bit).",
         "properties": {
            "rows": {
               "default": 40,
               "description": "Number of rows in text header.",
               "title": "Rows",
               "type": "integer"
            },
            "cols": {
               "default": 80,
               "description": "Number of columns in text header.",
               "title": "Cols",
               "type": "integer"
            },
            "encoding": {
               "$ref": "#/$defs/TextHeaderEncoding",
               "default": "ebcdic",
               "description": "String encoding."
            },
            "offset": {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Starting byte offset.",
               "title": "Offset"
            }
         },
         "title": "TextHeaderSpec",
         "type": "object"
      },
      "TraceDataSpec": {
         "description": "A spec class for trace data (samples).",
         "properties": {
            "format": {
               "$ref": "#/$defs/ScalarType",
               "description": "Format of trace samples."
            },
            "samples": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Number of samples in trace. It can be variable, then it must be read from each trace header.",
               "title": "Samples"
            },
            "interval": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Sample interval of traces",
               "title": "Interval"
            }
         },
         "required": [
            "format"
         ],
         "title": "TraceDataSpec",
         "type": "object"
      },
      "TraceSpec": {
         "description": "A spec class for a trace (header + data).",
         "properties": {
            "header": {
               "$ref": "#/$defs/HeaderSpec",
               "description": "Trace header spec."
            },
            "extHeader": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/HeaderSpec"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Extended trace header spec."
            },
            "data": {
               "$ref": "#/$defs/TraceDataSpec",
               "description": "Trace data spec."
            },
            "offset": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Starting offset of the trace.",
               "title": "Offset"
            },
            "endianness": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Endianness"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Endianness of traces and headers."
            },
            "count": {
               "anyOf": [
                  {
                     "minimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Number of traces.",
               "title": "Count"
            }
         },
         "required": [
            "header",
            "data"
         ],
         "title": "TraceSpec",
         "type": "object"
      }
   },
   "required": [
      "segyStandard",
      "textHeader",
      "binaryHeader",
      "trace"
   ]
}

field segyStandard: SegyStandard [Required]

Base SEG-Y Revision.

field textHeader: TextHeaderSpec [Required]

Textual file header spec.

field binaryHeader: HeaderSpec [Required]

Binary file header spec.

field extTextHeader: ExtendedTextHeaderSpec | None = None

Extended textual header spec.

field trace: TraceSpec [Required]

Trace header + data spec.

field endianness: Endianness | None = None

Endianness of SEG-Y file.

update_offsets()

Update the offsets of the SEG-Y components.

Return type:

None

customize(text_header_spec=None, binary_header_fields=None, ext_text_spec=None, trace_header_fields=None, trace_data_spec=None)

Customize an existing SEG-Y spec.

Parameters:

• text_header_spec (TextHeaderSpec | None) – New text header specification.

• binary_header_fields (list[HeaderField] | None) – List of custom binary header fields.

• ext_text_spec (ExtendedTextHeaderSpec | None) – New extended text header spec.

• trace_header_fields (list[HeaderField] | None) – List of custom trace header fields.

• trace_data_spec (TraceDataSpec | None) – New trace data specification.

• self (SegySpec)

Returns:

A modified SEG-Y spec with “custom” segy standard.

Return type:

SegySpec

pydantic model segy.schema.TextHeaderSpec

A class representing spec for SEG-Y textual headers (8-bit).

Show JSON schema

{
   "title": "TextHeaderSpec",
   "description": "A class representing spec for SEG-Y textual headers (8-bit).",
   "type": "object",
   "properties": {
      "rows": {
         "default": 40,
         "description": "Number of rows in text header.",
         "title": "Rows",
         "type": "integer"
      },
      "cols": {
         "default": 80,
         "description": "Number of columns in text header.",
         "title": "Cols",
         "type": "integer"
      },
      "encoding": {
         "$ref": "#/$defs/TextHeaderEncoding",
         "default": "ebcdic",
         "description": "String encoding."
      },
      "offset": {
         "anyOf": [
            {
               "minimum": 0,
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Starting byte offset.",
         "title": "Offset"
      }
   },
   "$defs": {
      "TextHeaderEncoding": {
         "description": "Supported textual header encodings.",
         "enum": [
            "ascii",
            "ebcdic"
         ],
         "title": "TextHeaderEncoding",
         "type": "string"
      }
   }
}

field rows: int = 40

Number of rows in text header.

field cols: int = 80

Number of columns in text header.

field encoding: TextHeaderEncoding = TextHeaderEncoding.EBCDIC

String encoding.

field offset: int | None = None

Starting byte offset.

Constraints:

• ge = 0

property processor: TextProcessor

Prepare transforms for encoding / decoding.

property dtype: dtype[Any]

Get numpy dtype.

decode(buffer)

Decode EBCDIC or ASCII bytes into string.

Parameters:

buffer (bytes)

Return type:

str

encode(string)

Encode string to EBCDIC or ASCII bytes.

Parameters:

string (str)

Return type:

bytes

property itemsize: int

Number of bytes for the data type.

class segy.schema.SegyStandard

Allowed values for SEG-Y standards in SegySpec.

CUSTOM = -1.0

REV0 = 0.0

REV1 = 1.0

REV2 = 2.0

REV21 = 2.1

pydantic model segy.schema.segy.SegyInfo

Concise and useful information about SEG-Y files.

Show JSON schema

{
   "title": "SegyInfo",
   "description": "Concise and useful information about SEG-Y files.",
   "type": "object",
   "properties": {
      "uri": {
         "description": "URI of the SEG-Y file.",
         "title": "Uri",
         "type": "string"
      },
      "segyStandard": {
         "anyOf": [
            {
               "$ref": "#/$defs/SegyStandard"
            },
            {
               "type": "null"
            }
         ],
         "description": "SEG-Y Revision / Standard. Can also be custom."
      },
      "numTraces": {
         "description": "Number of traces.",
         "title": "Numtraces",
         "type": "integer"
      },
      "samplesPerTrace": {
         "description": "Trace length in number of samples.",
         "title": "Samplespertrace",
         "type": "integer"
      },
      "sampleInterval": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "number"
            }
         ],
         "description": "Sampling rate from binary header.",
         "title": "Sampleinterval"
      },
      "fileSize": {
         "description": "File size in bytes.",
         "title": "Filesize",
         "type": "integer"
      }
   },
   "$defs": {
      "SegyStandard": {
         "description": "Allowed values for SEG-Y standards in SegySpec.",
         "enum": [
            -1.0,
            0.0,
            1.0,
            2.0,
            2.1
         ],
         "title": "SegyStandard",
         "type": "number"
      }
   },
   "required": [
      "uri",
      "segyStandard",
      "numTraces",
      "samplesPerTrace",
      "sampleInterval",
      "fileSize"
   ]
}

field uri: str [Required]

URI of the SEG-Y file.

field segyStandard: SegyStandard | None [Required]

SEG-Y Revision / Standard. Can also be custom.

field numTraces: int [Required]

Number of traces.

field samplesPerTrace: int [Required]

Trace length in number of samples.

field sampleInterval: int | float [Required]

Sampling rate from binary header.

field fileSize: int [Required]

File size in bytes.