segyio 2.0.0a1__cp312-cp312-win_amd64.whl

segyio/__init__.py

@@ -0,0 +1,101 @@
+"""segyio
+
+Welcome to segyio. For help, examples and reference, type ``help(function)`` in
+your favourite python interpreter, or ``pydoc function`` in the unix console.
+
+The segyio library attempts to be easy to use efficently for prototyping and
+interaction with possibly large segy files. File reading and writing is
+streaming, with large file support out of the box and without hassle. For a
+quick start on reading files, type ``help(segyio.open)``.
+
+An open segy file is interacted with in modes. For a reference with examples,
+please type ``help(segyio.segy)``, look at the online documentation at
+segyio.readthedocs.io, or run ``help()`` on the object returned by
+``segyio.open``.. For documentation on individual modes, please
+refer to the individual modes with ``help(f.[mode])``, where ``f`` is an open
+file handle.
+
+The available modes are:
+    * text, for textual headers including extended headers
+    * bin, for the binary header
+    * header, for the trace headers
+    * trace, for trace data
+    * iline, for inline biased operations
+    * xline, for crossline biased operations
+    * depth_slice, for depth biased operations
+    * gather, for gather/intersaction biased operations
+
+The primary data type is the numpy.ndarray. All examples use ``np`` for the
+numpy namespace. That means that any function that returns a trace, a set of
+samples or even full lines, returns a numpy.ndarray. This enables quick and
+easy mathematical operations on the data you care about.
+
+Segyio is designed to blend into regular python code, so python concepts that
+map to segy operations are written to behave similarly. That means that
+sequences of data support list lookup, slicing (``f.trace[0:10:2]``), ``for x
+in`` etc. Please refer to the individual modes' documentation for a more
+extensive set of examples.
+
+For all slicing operations that segyio provides the underlying buffer is
+reused, so if you want to keep the data between iterations it is necessary to
+manually copy the data, e.g. ``numpy.copy()``. Please refer to the examples.
+"""
+
+
+class Enum(object):
+    def __init__(self, enum_value):
+        super(Enum, self).__init__()
+        self._value = int(enum_value)
+
+    def __int__(self):
+        return int(self._value)
+
+    def __str__(self):
+        for k, v in self.__class__.__dict__.items():
+            if isinstance(v, int) and self._value == v:
+                return k
+        return "Unknown Enum"
+
+    def __repr__(self):
+        return str(self)
+
+    def __hash__(self):
+        return hash(self._value)
+
+    def __eq__(self, other):
+        if other is None:
+            return False
+        try:
+            o = int(other)
+        except ValueError:
+            return super(Enum, self).__eq__(other)
+        else:
+            return self._value == o
+
+    def __ne__(self, other):
+        return not self == other
+
+    @classmethod
+    def enums(cls):
+        result = []
+        for k, v in cls.__dict__.items():
+            if isinstance(v, int) and not str.startswith(k, "_"):
+                result.append(cls(v))
+
+        return sorted(result, key=int)
+
+
+from .binfield import BinField
+from .segysampleformat import SegySampleFormat
+from .tracesortingformat import TraceSortingFormat
+from .tracefield import TraceField
+from . import su
+from .open import open, open_with, open_from_memory
+from .create import create, create_with
+from .segy import SegyFile, spec
+from .tools import dt, sample_indexes, create_text_header, native
+from .tools import collect, cube
+
+__copyright__  = 'Copyright 2016, Statoil ASA'
+__license__    = 'GNU Lesser General Public License version 3'
+__status__     = 'Production'

segyio/binfield.py

@@ -0,0 +1,153 @@
+import warnings
+from . import Enum
+
+class TracesWrapper:
+    def __get__(self, instance, owner):
+        warnings.warn(
+            "Traces is deprecated and will be removed in a future version."
+            "Please use EnsembleTraces instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return 3213
+
+class AuxTracesWrapper:
+    def __get__(self, instance, owner):
+        warnings.warn(
+            "AuxTraces is deprecated and will be removed in a future version."
+            "Please use AuxEnsembleTraces instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return 3215
+
+class ExtTracesWrapper:
+    def __get__(self, instance, owner):
+        warnings.warn(
+            "ExtTraces is deprecated and will be removed in a future version."
+            "Please use ExtEnsembleTraces instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return 3261
+
+class ExtAuxTracesWrapper:
+    def __get__(self, instance, owner):
+        warnings.warn(
+            "ExtAuxTraces is deprecated and will be removed in a future version."
+            "Please use ExtAuxEnsembleTraces instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return 3265
+
+
+class BinField(Enum):
+    """Trace header field enumerator
+
+    See also
+    -------
+    segyio.su : Seismic unix aliases for header fields
+    """
+
+    JobID = 3201
+    LineNumber = 3205
+    ReelNumber = 3209
+    Traces = TracesWrapper()  # Deprecated, use EnsembleTraces
+    EnsembleTraces = 3213
+    AuxTraces = AuxTracesWrapper()  # Deprecated, use AuxEnsembleTraces
+    AuxEnsembleTraces = 3215
+    Interval = 3217
+    IntervalOriginal = 3219
+    Samples = 3221
+    SamplesOriginal = 3223
+    Format = 3225
+    EnsembleFold = 3227
+    SortingCode = 3229
+    VerticalSum = 3231
+    SweepFrequencyStart = 3233
+    SweepFrequencyEnd = 3235
+    SweepLength = 3237
+    Sweep = 3239
+    SweepChannel = 3241
+    SweepTaperStart = 3243
+    SweepTaperEnd = 3245
+    Taper = 3247
+    CorrelatedTraces = 3249
+    BinaryGainRecovery = 3251
+    AmplitudeRecovery = 3253
+    MeasurementSystem = 3255
+    ImpulseSignalPolarity = 3257
+    VibratoryPolarity = 3259
+    ExtTraces = ExtTracesWrapper()  # Deprecated, use ExtEnsembleTraces
+    ExtEnsembleTraces = 3261
+    ExtAuxTraces = ExtAuxTracesWrapper()  # Deprecated, use ExtAuxEnsembleTraces
+    ExtAuxEnsembleTraces = 3265
+    ExtSamples = 3269
+    ExtInterval = 3273
+    ExtIntervalOriginal = 3281
+    ExtSamplesOriginal = 3289
+    ExtEnsembleFold = 3293
+    IntConstant = 3297
+    Unassigned1 = 3301
+    SEGYRevision = 3501
+    SEGYRevisionMinor = 3502
+    TraceFlag = 3503
+    ExtendedHeaders = 3505
+    MaxAdditionalTraceHeaders = 3507
+    SurveyType = 3509
+    TimeBasisCode = 3511
+    NrTracesInStream = 3513
+    FirstTraceOffset = 3521
+    NrTrailerRecords = 3529
+    Unassigned2 = 3533
+
+keys = {
+    'JobID'                     : 3201,
+    'LineNumber'                : 3205,
+    'ReelNumber'                : 3209,
+    'EnsembleTraces'            : 3213,
+    'AuxEnsembleTraces'         : 3215,
+    'Interval'                  : 3217,
+    'IntervalOriginal'          : 3219,
+    'Samples'                   : 3221,
+    'SamplesOriginal'           : 3223,
+    'Format'                    : 3225,
+    'EnsembleFold'              : 3227,
+    'SortingCode'               : 3229,
+    'VerticalSum'               : 3231,
+    'SweepFrequencyStart'       : 3233,
+    'SweepFrequencyEnd'         : 3235,
+    'SweepLength'               : 3237,
+    'Sweep'                     : 3239,
+    'SweepChannel'              : 3241,
+    'SweepTaperStart'           : 3243,
+    'SweepTaperEnd'             : 3245,
+    'Taper'                     : 3247,
+    'CorrelatedTraces'          : 3249,
+    'BinaryGainRecovery'        : 3251,
+    'AmplitudeRecovery'         : 3253,
+    'MeasurementSystem'         : 3255,
+    'ImpulseSignalPolarity'     : 3257,
+    'VibratoryPolarity'         : 3259,
+    'ExtEnsembleTraces'         : 3261,
+    'ExtAuxEnsembleTraces'      : 3265,
+    'ExtSamples'                : 3269,
+    'ExtInterval'               : 3273,
+    'ExtIntervalOriginal'       : 3281,
+    'ExtSamplesOriginal'        : 3289,
+    'ExtEnsembleFold'           : 3293,
+    'IntConstant'               : 3297,
+    'Unassigned1'               : 3301,
+    'SEGYRevision'              : 3501,
+    'SEGYRevisionMinor'         : 3502,
+    'TraceFlag'                 : 3503,
+    'ExtendedHeaders'           : 3505,
+    'MaxAdditionalTraceHeaders' : 3507,
+    'SurveyType'                : 3509,
+    'TimeBasisCode'             : 3511,
+    'NrTracesInStream'          : 3513,
+    'FirstTraceOffset'          : 3521,
+    'NrTrailerRecords'          : 3529,
+    'Unassigned2'               : 3533,
+}

segyio/create.py

@@ -0,0 +1,314 @@
+import datetime
+import numpy
+import segyio
+
+from . import TraceSortingFormat
+from .utils import (
+    FileDatasourceDescriptor,
+    StreamDatasourceDescriptor,
+    to_c_endianness,
+    to_c_encoding
+)
+
+def default_text_header(iline, xline, offset):
+    lines = {
+        1: "DATE %s" % datetime.date.today().isoformat(),
+        2: "AN INCREASE IN AMPLITUDE EQUALS AN INCREASE IN ACOUSTIC IMPEDANCE",
+        3: "Written by libsegyio (python)",
+        11: "TRACE HEADER POSITION:",
+        12: "  INLINE BYTES %03d-%03d    | OFFSET BYTES %03d-%03d" % (iline, iline + 4, int(offset), int(offset) + 4),
+        13: "  CROSSLINE BYTES %03d-%03d |" % (xline, xline + 4),
+        15: "END EBCDIC HEADER",
+    }
+    rows = segyio.create_text_header(lines)
+    rows = bytearray(rows, 'ascii')  # mutable array of bytes
+    rows[-1] = 128  # \x80 -- Unsure if this is really required...
+    return bytes(rows)  # immutable array of bytes that is compatible with strings
+
+
+def structured(spec):
+    if not hasattr(spec, 'ilines' ): return False
+    if not hasattr(spec, 'xlines' ): return False
+    if not hasattr(spec, 'offsets'): return False
+
+    if spec.ilines  is None: return False
+    if spec.xlines  is None: return False
+    if spec.offsets is None: return False
+
+    if not list(spec.ilines):  return False
+    if not list(spec.xlines):  return False
+    if not list(spec.offsets): return False
+
+    return True
+
+def create(filename, spec, layout_xml = None):
+    """Create a new segy file.
+
+    Create a new segy file with the geometry and properties given by `spec`.
+    This enables creating SEGY files from your data. The created file supports
+    all segyio modes, but has an emphasis on writing. The spec must be
+    complete, otherwise an exception will be raised. A default, empty spec can
+    be created with ``segyio.spec()``.
+
+    Very little data is written to the file, so just calling create is not
+    sufficient to re-read the file with segyio. Rather, every trace header and
+    trace must be written to the file to be considered complete.
+
+    Create should be used together with python's ``with`` statement. This ensure
+    the data is written. Please refer to the examples.
+
+    The ``segyio.spec()`` function will default sorting, offsets and everything
+    in the mandatory group, except format and samples, and requires the caller
+    to fill in *all* the fields in either of the exclusive groups.
+
+    If any field is missing from the first exclusive group, and the tracecount
+    is set, the resulting file will be considered unstructured. If the
+    tracecount is set, and all fields of the first exclusive group are
+    specified, the file is considered structured and the tracecount is inferred
+    from the xlines/ilines/offsets. The offsets are defaulted to ``[1]`` by
+    ``segyio.spec()``.
+
+    Parameters
+    ----------
+    filename : str
+        Path to file to create
+    spec : segyio.spec
+        Structure of the segy file
+    layout_xml: bytearray
+        SEG-Y revision 2.1 D8 xml layout. Note that this layout is used only
+        during file creation and is not stored in the file.
+
+    Returns
+    -------
+    file : segyio.SegyFile
+        An open segyio file handle, similar to that returned by `segyio.open`
+
+    See also
+    --------
+    segyio.spec : template for the `spec` argument
+
+
+    Notes
+    -----
+
+    .. versionadded:: 1.1
+
+    .. versionchanged:: 1.4
+       Support for creating unstructured files
+
+    .. versionchanged:: 1.8
+       Support for creating lsb files
+
+    .. versionchanged:: 2.0
+       Support for SEG-Y revision 2.1
+
+    The ``spec`` is any object that has the following attributes
+
+    Mandatory::
+
+        iline   : int or segyio.BinField
+        xline   : int or segyio.BinField
+        samples : array of int
+        format  : { 1, 5 }
+            1 = IBM float, 5 = IEEE float
+
+    Exclusive::
+
+        ilines  : array_like of int
+        xlines  : array_like of int
+        offsets : array_like of int
+        sorting : int or segyio.TraceSortingFormat
+
+        OR
+
+        tracecount : int
+
+    Optional::
+
+        ext_headers : int
+        endian : str { 'big', 'msb', 'little', 'lsb' }
+            defaults to 'big'
+        encoding : {'ebcdic', 'ascii'}
+            defaults to 'ebcdic'.
+
+
+    Examples
+    --------
+
+    Create a file:
+
+    >>> spec = segyio.spec()
+    >>> spec.ilines  = [1, 2, 3, 4]
+    >>> spec.xlines  = [11, 12, 13]
+    >>> spec.samples = list(range(50))
+    >>> spec.sorting = 2
+    >>> spec.format  = 1
+    >>> with segyio.create(path, spec) as f:
+    ...     ## fill the file with data
+    ...     pass
+    ...
+
+    Copy a file, but shorten all traces by 50 samples:
+
+    >>> with segyio.open(srcpath) as src:
+    ...     spec = segyio.spec()
+    ...     spec.sorting = src.sorting
+    ...     spec.format = src.format
+    ...     spec.samples = src.samples[:len(src.samples) - 50]
+    ...     spec.ilines = src.ilines
+    ...     spec.xline = src.xlines
+    ...     with segyio.create(dstpath, spec) as dst:
+    ...         dst.text[0] = src.text[0]
+    ...         dst.bin = src.bin
+    ...         # this is writing a sparse file, which might be slow on some
+    ...         # systems
+    ...         dst.header = src.header
+    ...         dst.trace = src.trace
+
+     Copy a file, but shift samples time by 50:
+
+    >>> with segyio.open(srcpath) as src:
+    ...     delrt = 50
+    ...     spec = segyio.spec()
+    ...     spec.samples = src.samples + delrt
+    ...     spec.ilines = src.ilines
+    ...     spec.xline = src.xlines
+    ...     with segyio.create(dstpath, spec) as dst:
+    ...         dst.text[0] = src.text[0]
+    ...         dst.bin = src.bin
+    ...         dst.header = src.header
+    ...         dst.header = { TraceField.DelayRecordingTime: delrt }
+    ...         dst.trace = src.trace
+
+    Copy a file, but shorten all traces by 50 samples (since v1.4):
+
+    >>> with segyio.open(srcpath) as src:
+    ...     spec = segyio.tools.metadata(src)
+    ...     spec.samples = spec.samples[:len(spec.samples) - 50]
+    ...     with segyio.create(dstpath, spec) as dst:
+    ...         dst.text[0] = src.text[0]
+    ...         dst.bin = src.bin
+    ...         dst.header = src.header
+    ...         dst.trace = src.trace
+    """
+    return _create(FileDatasourceDescriptor(filename, "w+"), spec, layout_xml)
+
+
+def create_with(stream, spec, minimize_requests_number=True, layout_xml = None):
+    """
+    Creates a segy file on stream.
+
+    Function behaves the same as `segyio.create`, but outputs data to a
+    finite stream instead of a file. Stream's close() will be called when
+    SegyFile is closed.
+
+    Note that `segyio.create_with` can be very slow. `segyio.create` is
+    generally a preferred option when speed matters.
+
+    Parameters
+    ----------
+
+    stream : file-like object
+        Data destination. It is up to the user to assure stream is opened in w+b mode.
+    spec : segyio.spec
+        Structure of the segy file
+    minimize_requests_number : bool
+        Configuration for some internal algorithms. True to minimize number of
+        requests to the stream at the cost of higher memory usage. False to
+        minimize memory usage at the cost of more requests to the stream.
+    layout_xml: bytearray
+        SEG-Y revision 2.1 D8 xml layout. Note that this layout is used only
+        during file creation and is not stored in the file.
+    """
+    return _create(
+        StreamDatasourceDescriptor(
+            stream,
+            minimize_requests_number
+        ),
+        spec,
+        layout_xml
+    )
+
+
+def _create(datasource_descriptor, spec, layout_xml):
+    if not structured(spec):
+        tracecount = spec.tracecount
+    else:
+        tracecount = len(spec.ilines) * len(spec.xlines) * len(spec.offsets)
+
+    ext_headers = spec.ext_headers if hasattr(spec, 'ext_headers') else 0
+    samples = numpy.asarray(spec.samples)
+
+    traceheader_count = spec.traceheader_count if hasattr(spec, 'traceheader_count') else 1
+
+    endian = spec.endian if hasattr(spec, 'endian') else 'big'
+    if endian is None:
+        endian = 'big'
+
+    encoding = spec.encoding if hasattr(spec, 'encoding') else 'ebcdic'
+    if encoding is None:
+        encoding = 'ebcdic'
+
+    fd = datasource_descriptor.make_segyfile_descriptor()
+    fd.segymake(
+        samples = len(samples),
+        tracecount = tracecount,
+        endianness=to_c_endianness(endian),
+        encoding=to_c_encoding(encoding),
+        format = int(spec.format),
+        ext_headers = int(ext_headers),
+        traceheader_count = traceheader_count,
+        layout_xml = layout_xml
+    )
+
+    # note: even if iline/xline are overridden, file is already created with
+    # standard iline/xline position, so those can mismatch
+
+    f = segyio.SegyFile(fd,
+            datasource_descriptor,
+            endian = endian,
+    )
+
+    f._samples       = samples
+
+    if structured(spec):
+        sorting = spec.sorting if hasattr(spec, 'sorting') else None
+        if sorting is None:
+            sorting = TraceSortingFormat.INLINE_SORTING
+        f.interpret(spec.ilines, spec.xlines, spec.offsets, sorting)
+
+    f.text[0] = default_text_header(f._il, f._xl, segyio.TraceField.offset)
+
+    if len(samples) == 1:
+        interval = int(samples[0] * 1000)
+    else:
+        interval = int((samples[1] - samples[0]) * 1000)
+
+    binary_header = {}
+    binary_header.update(
+        ntrpr    = 1,
+        hdt      = interval,
+        dto      = interval,
+        format   = int(spec.format),
+        fold     = 1,
+        tsort    = 4,
+        exth     = ext_headers,
+    )
+
+    if len(samples) > 2**16 - 1:
+        # when using the ext-samples field, also set rev2, even though it's a
+        # soft lie and files aren't really compliant
+        binary_header.update(
+            exthns = len(samples),
+            extnso = len(samples),
+            rev    = 2
+        )
+    else:
+        binary_header.update(
+            hns = len(samples),
+            nso = len(samples),
+        )
+
+    f.bin.update(**binary_header)
+
+    return f