segyio 1.9.13__cp313-cp313-win32.whl

segyio/__init__.py

@@ -0,0 +1,99 @@
+"""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):
+        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
+from .create import create
+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,89 @@
+from . import Enum
+
+class BinField(Enum):
+    """Trace header field enumerator
+
+    See also
+    -------
+    segyio.su : Seismic unix aliases for header fields
+    """
+
+    JobID = 3201
+    LineNumber = 3205
+    ReelNumber = 3209
+    Traces = 3213
+    AuxTraces = 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 = 3261
+    ExtAuxTraces = 3265
+    ExtSamples = 3269
+    ExtSamplesOriginal = 3289
+    ExtEnsembleFold = 3293
+    Unassigned1 = 3261
+    SEGYRevision = 3501
+    SEGYRevisionMinor = 3502
+    TraceFlag = 3503
+    ExtendedHeaders = 3505
+    Unassigned2 = 3507
+
+keys = {
+    'JobID'                 : 3201,
+    'LineNumber'            : 3205,
+    'ReelNumber'            : 3209,
+    'Traces'                : 3213,
+    'AuxTraces'             : 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'             : 3261,
+    'ExtAuxTraces'          : 3265,
+    'ExtSamples'            : 3269,
+    'ExtSamplesOriginal'    : 3289,
+    'ExtEnsembleFold'       : 3293,
+    'Unassigned1'           : 3301,
+    'SEGYRevision'          : 3501,
+    'SEGYRevisionMinor'     : 3502,
+    'TraceFlag'             : 3503,
+    'ExtendedHeaders'       : 3505,
+    'Unassigned2'           : 3507,
+}

segyio/create.py

@@ -0,0 +1,257 @@
+import datetime
+import numpy
+import segyio
+
+from . import TraceSortingFormat
+
+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):
+    """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
+
+    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
+
+    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'
+
+
+    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
+    """
+
+    from . import _segyio
+
+    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)
+
+    endians = {
+        'lsb': 256, # (1 << 8)
+        'little': 256,
+        'msb': 0,
+        'big': 0,
+    }
+    endian = spec.endian if hasattr(spec, 'endian') else 'big'
+    if endian is None:
+        endian = 'big'
+
+    if endian not in endians:
+        problem = 'unknown endianness {}, expected one of: '
+        opts = ' '.join(endians.keys())
+        raise ValueError(problem.format(endian) + opts)
+
+    fd = _segyio.segyiofd(str(filename), 'w+', endians[endian])
+    fd.segymake(
+        samples = len(samples),
+        tracecount = tracecount,
+        format = int(spec.format),
+        ext_headers = int(ext_headers),
+    )
+
+    f = segyio.SegyFile(fd,
+            filename = str(filename),
+            mode = 'w+',
+            iline = int(spec.iline),
+            xline = int(spec.xline),
+            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)
+
+    f.bin.update(
+        ntrpr    = tracecount,
+        nart     = tracecount,
+        hdt      = interval,
+        dto      = interval,
+        hns      = len(samples),
+        nso      = len(samples),
+        format   = int(spec.format),
+        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
+        f.bin.update(
+            exthns = len(samples),
+            extnso = len(samples),
+            rev    = 2
+        )
+
+    return f

segyio/depth.py

@@ -0,0 +1,180 @@
+try:
+    from collections.abc import Sequence # noqa
+except ImportError:
+    from collections import Sequence # noqa
+
+import numpy as np
+try: from future_builtins import zip
+except ImportError: pass
+from .trace import Sequence
+from .utils import castarray
+
+class Depth(Sequence):
+    """
+    The Depth implements the array interface, where every array element, the
+    depth, is a numpy.ndarray of a horizontal cut of the volume. As all arrays
+    it can be random accessed, iterated over, and read strided. Please note
+    that SEG-Y data is laid out trace-by-trace on disk, so accessing horizontal
+    cuts (fixed z-coordinates in a cartesian grid) is *very* inefficient.
+
+    This mode works even on unstructured files, because it is not reliant on
+    in/crosslines to be sensible. Please note that in the case of unstructured
+    depth slicing, the array shape == tracecount.
+
+    Notes
+    -----
+    .. versionadded:: 1.1
+
+    .. versionchanged:: 1.6
+        common list operations (Sequence)
+
+    .. versionchanged:: 1.7.1
+       enabled for unstructured files
+
+    .. warning::
+        Accessing the file by depth (fixed z-coordinate) is inefficient because
+        of poor locality and many reads. If you read more than a handful
+        depths, consider using a faster mode.
+    """
+
+    def __init__(self, fd):
+        super(Depth, self).__init__(len(fd.samples))
+        self.filehandle = fd.xfd
+        self.dtype = fd.dtype
+
+        if fd.unstructured:
+            self.shape = fd.tracecount
+            self.offsets = 1
+        else:
+            self.shape = (len(fd.fast), len(fd.slow))
+            self.offsets = len(fd.offsets)
+
+    def __getitem__(self, i):
+        """depth[i]
+
+        ith depth, a horizontal cross-section of the file, starting at 0.
+        depth[i] returns a numpy.ndarray, and changes to this array will *not*
+        be reflected on disk.
+
+        When i is a slice, a generator of numpy.ndarray is returned.
+
+        The depth slices are returned as a fast-by-slow shaped array, i.e. an
+        inline sorted file with 10 inlines and 5 crosslines has the shape
+        (10,5). If the file is unsorted, the array shape == tracecount.
+
+        Be aware that this interface uses zero-based indices (like traces) and
+        *not keys* (like ilines), so you can *not* use the values file.samples
+        as indices.
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        depth : numpy.ndarray of dtype or generator of numpy.ndarray of dtype
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        .. warning::
+            The segyio 1.5 and 1.6 series, and 1.7.0, would return the depth_slice in the
+            wrong shape for most files. Since segyio 1.7.1, the arrays have the
+            correct shape, i.e. fast-by-slow. The underlying data was always
+            fast-by-slow, so a numpy array reshape can fix programs using the
+            1.5 and 1.6 series.
+
+        Behaves like [] for lists.
+
+        Examples
+        --------
+        Read a single cut (one sample per trace):
+
+        >>> x = f.depth_slice[199]
+
+        Copy every depth slice into a list:
+
+        >>> l = [numpy.copy(x) for x in depth[:]]
+
+        Every third depth:
+
+        >>> for d in depth[::3]:
+        ...     (d * 6).mean()
+
+        Read up to 250:
+
+        >>> for d in depth[:250]:
+        ...     d.mean()
+
+        >>> len(ilines), len(xlines)
+        (1, 6)
+        >>> f.depth_slice[0]
+        array([[0.  , 0.01, 0.02, 0.03, 0.04, 0.05]], dtype=float32)
+        """
+
+        try:
+            i = self.wrapindex(i)
+            buf = np.empty(self.shape, dtype=self.dtype)
+            return self.filehandle.getdepth(i, buf.size, self.offsets, buf)
+
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'depth indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                x = np.empty(self.shape, dtype=self.dtype)
+                y = np.copy(x)
+
+                for j in range(*indices):
+                    self.filehandle.getdepth(j, x.size, self.offsets, x)
+                    x, y = y, x
+                    yield y
+
+            return gen()
+
+    def __setitem__(self, depth, val):
+        """depth[i] = val
+
+        Write the ith depth, a horizontal cross-section, of the file, starting
+        at 0. It accepts any array_like, but `val` must be at least as big as
+        the underlying data slice.
+
+        If `val` is longer than the underlying trace, `val` is essentially truncated.
+
+        Parameters
+        ----------
+        i   : int or slice
+        val : array_like
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists.
+
+        Examples
+        --------
+        Copy a depth:
+
+        >>> depth[4] = other[19]
+
+        Copy consecutive depths, and assign to a sub volume (inject a sub cube
+        into the larger volume):
+
+        >>> depth[10:50] = other[:]
+
+        Copy into every other depth from an iterable:
+
+        >>> depth[::2] = other
+        """
+        if isinstance(depth, slice):
+            for i, x in zip(range(*depth.indices(len(self))), val):
+                self[i] = x
+            return
+
+        val = castarray(val, dtype = self.dtype)
+        self.filehandle.putdepth(depth, val.size, self.offsets, val)