1# -*- coding: utf-8 -*-
2"""
3obspy.io.mseed - MiniSEED read and write support for ObsPy
4==========================================================
5This module provides read and write support for the `MiniSEED
6<https://ds.iris.edu/ds/nodes/dmc/data/formats/#miniseed>`_ (and the
7data part of full SEED) waveform data format and some other convenient
8methods to handle MiniSEED files. It utilizes
9`libmseed <https://ds.iris.edu/ds/nodes/dmc/software/downloads/libmseed/>`_,
10a C library by Chad Trabant.
11
12.. seealso::
13
14    The format is  defined in the
15    `SEED Manual <https://www.fdsn.org/seed_manual/SEEDManual_V2.4.pdf>`_.
16
17:copyright:
18    The ObsPy Development Team (devs@obspy.org) & Chad Trabant
19:license:
20    GNU Lesser General Public License, Version 3
21    (https://www.gnu.org/copyleft/lesser.html)
22
23Reading
24-------
25
26Reading MiniSEED (and the data part of full SEED files) is handled by using
27ObsPy's standard :func:`~obspy.core.stream.read` function. The format is
28detected automatically.
29
30>>> from obspy import read
31>>> st = read("/path/to/test.mseed")
32>>> st #doctest: +ELLIPSIS
33<obspy.core.stream.Stream object at 0x...>
34>>> print(st)  #doctest: +ELLIPSIS
351 Trace(s) in Stream:
36NL.HGN.00.BHZ | 2003-05-29T02:13:22.043400Z - ... | 40.0 Hz, 11947 samples
37>>> print(st[0].stats) # doctest: +ELLIPSIS
38         network: NL
39         station: HGN
40        location: 00
41         channel: BHZ
42       starttime: 2003-05-29T02:13:22.043400Z
43         endtime: 2003-05-29T02:18:20.693400Z
44   sampling_rate: 40.0
45           delta: 0.025
46            npts: 11947
47           calib: 1.0
48         _format: MSEED
49           mseed: ...
50
51MiniSEED specific metadata is stored in ``stats.mseed``.
52
53>>> for k, v in sorted(st[0].stats.mseed.items()):
54...     print("'%s': %s" % (k, str(v))) # doctest: +NORMALIZE_WHITESPACE
55    'byteorder':  >
56    'dataquality': R
57    'encoding': STEIM2
58    'filesize': 8192
59    'number_of_records':  2
60    'record_length': 4096
61
62The actual data is stored as a :class:`~numpy.ndarray` in the ``data``
63attribute of each trace.
64
65>>> print(st[0].data)
66[2787 2776 2774 ..., 2850 2853 2853]
67
68
69Several key word arguments are available which can be used for example to
70only read certain records from a file or force the header byteorder:
71``starttime``, ``endtime``, ``headonly``, ``sourcename``, ``reclen``,
72``details``, and ``header_byteorder``. They are passed to the
73:meth:`~obspy.io.mseed.core._read_mseed` method so refer to it for details to
74each parameter.
75
76Writing
77-------
78Write data back to disc or a file like object using the
79:meth:`~obspy.core.stream.Stream.write` method of a
80:class:`~obspy.core.stream.Stream` or
81:class:`~obspy.core.trace.Trace` object.
82
83>>> st.write('Mini-SEED-filename.mseed', format='MSEED') #doctest: +SKIP
84
85You can also specify several keyword arguments that change the resulting
86Mini-SEED file: ``reclen``, ``encoding``, ``byteorder``, ``flush``,  and
87``verbose``.
88They are are passed to the :meth:`~obspy.io.mseed.core._write_mseed` method so
89refer to it for details to each parameter.
90
91Refer to the :meth:`~obspy.io.mseed.core._write_mseed` method for details to
92each parameter.
93
94So in order to write a STEIM1 encoded Mini-SEED file with a record length of
95512 byte do the following:
96
97>>> st.write('out.mseed', format='MSEED', reclen=512,  # doctest: +SKIP
98...          encoding='STEIM1')
99
100Many of these can also be set at each Trace`s ``stats.mseed`` attribute which
101allows for per Trace granularity. Values passed to the
102:func:`~obspy.core.stream.read` function have priority.
103
104
105Encoding Support
106----------------
107
108MiniSEED is a format with a large variety of different blockettes,
109byte order issues, and encodings. The capabilities of ``obspy.io.mseed``
110largely coincide with the capabilities of ``libmseed``, which is the de-facto
111standard MiniSEED library and used internally by ObsPy.
112
113In regards to the different encodings for the data part of MiniSEED files
114this means the following:
115
116* Read support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats,
117  STEIM 1 + 2, all GEOSCOPE encodings, the CDSN encoding, the SRO encoding,
118  and the DWWSSN encoding
119* Write support for: ACSII, 16 and 32 bit integers, 32 and 64 bit floats,
120  and STEIM 1 + 2
121* Unsupported: 24 bit integers, US National Network compression,
122  Graefenberg 16 bit gain ranged encoding, IPG - Strasbourg 16 bit gain ranged
123  encoding, STEIM 3, the HGLP encoding, and the RSTN 16 bit gain ranged
124  encoding
125
126Utilities
127---------
128
129This module also contains a couple of utility functions which are useful for
130some purposes. Refer to the documentation of each for details.
131
132+----------------------------------------------------------+--------------------------------------------------------------------------+
133| :func:`~obspy.io.mseed.util.get_start_and_end_time`      | Fast way of getting the temporal bounds of a well-behaved MiniSEED file. |
134+----------------------------------------------------------+--------------------------------------------------------------------------+
135| :func:`~obspy.io.mseed.util.get_flags`                   | Returns information about the flags and timing quality in a file.        |
136+----------------------------------------------------------+--------------------------------------------------------------------------+
137| :func:`~obspy.io.mseed.util.shift_time_of_file`          | Shifts the time of a file preserving all blockettes and flags.           |
138+----------------------------------------------------------+--------------------------------------------------------------------------+
139| :func:`~obspy.io.mseed.util.get_record_information`      | Returns record information about given files and file-like object.       |
140+----------------------------------------------------------+--------------------------------------------------------------------------+
141| :func:`~obspy.io.mseed.util.set_flags_in_fixed_headers`  | Updates a given miniSEED file with some fixed header flags.              |
142+----------------------------------------------------------+--------------------------------------------------------------------------+
143"""
144from __future__ import (absolute_import, division, print_function,
145                        unicode_literals)
146from future.builtins import *  # NOQA
147
148from obspy import ObsPyException, ObsPyReadingError
149
150
151class ObsPyMSEEDError(ObsPyException):
152    pass
153
154
155class ObsPyMSEEDReadingError(ObsPyMSEEDError, ObsPyReadingError):
156    pass
157
158
159class InternalMSEEDError(ObsPyMSEEDError):
160    pass
161
162
163class InternalMSEEDParseTimeError(InternalMSEEDError):
164    pass
165
166
167class InternalMSEEDWarning(UserWarning):
168    pass
169
170
171class ObsPyMSEEDFilesizeTooSmallError(ObsPyMSEEDReadingError):
172    pass
173
174
175class ObsPyMSEEDFilesizeTooLargeError(ObsPyMSEEDReadingError):
176    pass
177
178
179__all__ = ['InternalMSEEDError', 'InternalMSEEDWarning', 'ObsPyMSEEDError',
180           'ObsPyMSEEDFilesizeTooSmallError']
181
182
183if __name__ == '__main__':
184    import doctest
185    doctest.testmod(exclude_empty=True)
186