def create_reader(
fh,
encoding=None,
trace_header_format=TraceHeaderRev1,
endian='>',
progress=None,
cache_directory=".segpy",
dimensionality=None):
"""Create a SegYReader based on performing a scan of SEG Y data.
This function is the preferred method for creating SegYReader
objects. It reads basic header information and attempts to build
indexes for traces, CDP numbers (for 2D surveys), and inline and
cross line co-ordinates (for 3D surveys) to facilitate subsequent
random-access to traces.
Args:
fh: A file-like-object open in binary mode positioned such
that the beginning of the reel header will be the next
byte to be read. For disk-based SEG Y files, this is the
beginning of the file.
encoding: An optional text encoding for the textual headers. If
None (the default) a heuristic will be used to guess the
header encoding.
trace_header_format: An optional class defining the layout of the
trace header. Defaults to TraceHeaderRev1.
endian: '>' for big-endian data (the standard and default), '<'
for little-endian (non-standard)
progress: A unary callable which will be passed a number
between zero and one indicating the progress made. If
provided, this callback will be invoked at least once with
an argument equal to one.
cache_directory: The directory for the cache file. Relative paths
are interpreted as being relative to the directory containing
the SEG Y file. Absolute paths are used as is. If
cache_directory is None, caching is disabled.
dimensionality: An optional integer to force the dimensionality of
the created reader. Accepted values are None, 1, 2 and 3. If None
(the default) various heuristics will be used to guess the
dimensionality of the data.
Raises:
ValueError: The file-like object``fh`` is unsuitable for some reason,
such as not being open, not being seekable, not being in
binary mode, or being too short.
Returns:
A SegYReader object. Depending on the exact type of the
SegYReader returned different capabilities may be
available. Inspect the returned object to determine these
capabilities, or be prepared for capabilities not defined in
the SegYReader base class to be unavailable. The underlying
file-like object must remain open for the duration of use of
the returned reader object. It is the caller's responsibility
to close the underlying file.
"""
if hasattr(fh, 'encoding') and fh.encoding is not None:
raise TypeError(
"SegYReader must be provided with a binary mode file object")
if not fh.seekable():
raise TypeError(
"SegYReader must be provided with a seekable file object")
if fh.closed:
raise ValueError(
"SegYReader must be provided with an open file object")
num_file_bytes = file_length(fh)
if num_file_bytes < REEL_HEADER_NUM_BYTES:
raise ValueError(
"SEG Y file {!r} of {} bytes is too short".format(
filename_from_handle(fh),
num_file_bytes))
if endian not in ('<', '>'):
raise ValueError("Unrecognised endian value {!r}".format(endian))
progress_callback = progress if progress is not None else lambda p: None
if not callable(progress_callback):
raise TypeError("create_reader(): progress callback must be callable")
if dimensionality not in (None, 1, 2, 3):
raise ValueError("dimensionality {!r} is not an of 1, 2, 3 or None.".format(dimensionality))
reader = None
cache_file_path = None
if cache_directory is not None:
sha1 = hash_for_file(fh, encoding, trace_header_format, endian)
seg_y_path = filename_from_handle(fh)
cache_file_path = _locate_cache_file(seg_y_path, cache_directory, sha1)
if cache_file_path is not None:
reader = _load_reader_from_cache(cache_file_path, seg_y_path)
if reader is None:
reader = _make_reader(fh, encoding, trace_header_format, endian, progress_callback, dimensionality)
if cache_directory is not None:
_save_reader_to_cache(reader, cache_file_path)
progress_callback(1)
return reader
def create_writer(
fh, encoding=None, trace_header_format=TraceHeaderRev1, endian=">", progress=None, cache_directory=None, fast=False
):
"""Create a SegYWriter (or one of its subclasses) based on performing
a scan of SEG Y data.
This function is the preferred method for creating SegYWriter
objects. It reads basic header information and attempts to build
indexes for traces, CDP numbers (for 2D surveys), and inline and
cross line co-ordinates (for 3D surveys) to facilitate subsequent
random-access to traces.
Args:
fh: A file-like-object open in binary mode positioned such
that the beginning of the reel header will be the next
byte to be read. For disk-based SEG Y files, this is the
beginning of the file.
encoding: An optional text encoding for the textual headers. If
None (the default) a heuristic will be used to guess the
header encoding.
trace_header_format: An optional class defining the layout of the
trace header. Defaults to TraceHeaderRev1.
endian: '>' for big-endian data (the standard and default), '<'
for little-endian (non-standard)
progress: A unary callable which will be passed a number
between zero and one indicating the progress made. If
provided, this callback will be invoked at least once with
an argument equal to one.
cache_directory: The directory for the cache file. Relative paths
are interpreted as being relative to the directory containing
the SEG Y file. Absolute paths are used as is. If
cache_directory is None, caching is disabled.
fast: Boolean flag to try a quick fixed length catalog before inline or
CDP catalogs.
Raises:
ValueError: ``fh`` is unsuitable for some reason, such as not
being open, not being seekable, not being in
binary mode, or being too short.
Returns:
A SegYWriter object. Depending on the exact type of the
SegYWriter returned different capabilities may be
available. Inspect the returned object to determine these
capabilities, or be prepared for capabilities not defined in
the SegYWriter base class to be unavailable. The underlying
file-like object must remain open for the duration of use of
the returned reader object. It is the caller's responsibility
to close the underlying file.
Example:
with open('my_seismic_data.sgy', 'rb') as fh:
reader = create_reader(fh)
print(reader.num_traces())
"""
if hasattr(fh, "encoding") and fh.encoding is not None:
raise TypeError("SegYWriter must be provided with a binary mode file object")
if not fh.seekable():
raise TypeError("SegYWriter must be provided with a seekable file object")
if fh.closed:
raise ValueError("SegYWriter must be provided with an open file object")
num_file_bytes = file_length(fh)
if num_file_bytes < REEL_HEADER_NUM_BYTES:
raise ValueError("SEG Y file {!r} of {} bytes is too short".format(filename_from_handle(fh), num_file_bytes))
if endian not in ("<", ">"):
raise ValueError("Unrecognised endian value {!r}".format(endian))
reader = None
cache_file_path = None
if cache_directory is not None:
sha1 = hash_for_file(fh, encoding, trace_header_format, endian)
seg_y_path = filename_from_handle(fh)
cache_file_path = _locate_cache_file(seg_y_path, cache_directory, sha1)
if cache_file_path is not None:
reader = _load_reader_from_cache(cache_file_path, seg_y_path)
if reader is None:
reader = _make_writer(fh, encoding, trace_header_format, endian, progress, fast=fast)
if cache_directory is not None:
_save_reader_to_cache(reader, cache_file_path)
return reader