1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
.. _mrc-format:
MRC format
----------
The ``.mrc`` format is widely used for tomographic data. The implementation of this plugin
is based on `this specification
<https://www2.mrc-lmb.cam.ac.uk/research/locally-developed-software/image-processing-software/>`_
and has partial support for FEI's custom header.
.. Note::
When reading 4D-STEM data saved by the Velox software, the data are read as a stack
of diffraction patterns, but the ``navigation_shape`` argument can be used to
specify the shape of the navigation space.
.. Note::
For ``.mrc`` files, the :func:`~rsciio.mrc.file_reader` takes the ``mmap_mode``
keyword argument to load the file using a different mode (default is copy-on-write).
However, note that lazy loading does not support in-place writing (i.e lazy loading
and the ``r+`` mode are incompatible).
See also the `format documentation <https://www.ccpem.ac.uk/mrc_format/mrc_format.php>`_
by the Collaborative Computational Project for Electron cryo-Microscopy (CCP-EM).
This plugin does not support writing ``.mrc`` files, which can however be done
using the :ref:`mrcz <mrcz-format>` plugin. No additional feature of the
`mrcz format <https://python-mrcz.readthedocs.io>`_ should be used in order
to write a ``.mrc`` compliant file. In particular, the ``compressor`` argument should
not be passed (Default is ``None``):
.. code-block:: python
>>> import numpy as np
>>> from rsciio import mrcz
>>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
>>> s = hs.signals.Signal2D(data)
>>> s_dict = s.as_dictionary()
>>> mrcz.file_writer('test.mrc', s_dict)
Alternatively, use :meth:`hyperspy.api.signals.BaseSignal.save`, which will pick the
``mrcz`` plugin automatically:
.. code-block:: python
>>> import hyperspy.api as hs
>>> import numpy as np
>>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
>>> s = hs.signals.Signal2D(data)
>>> s.save("data.mrc")
MRC Format (Direct Electron)
----------------------------
Loading from Direct Electron's ``.mrc`` as well as reading the metadata from the .txt file
saved by the software is supported by passing the ``metadata_file`` argument to the
``file_reader`` function. The ``metadata_file`` argument can be a string or a file-like
object. Additionally, the ``metadata_file`` argument can be automatically inferred. This requires
that the file name is of the form ``uniqueid_suffix_movie.mrc`` and that the metadata file is
named ``uniqueid_suffix_info.txt``.
This will automatically set the navigation shape based on the ``Scan - Size X`` and = 256
``Scan - Size Y`` parameters in the metadata file. The navigation shape can be overridden
by passing the ``navigation_shape`` argument to the :func:`~rsciio.mrc.file_reader` function.
Additionally virtual_images/ external detectors can be loaded by passing a list of file names to the
``external_images`` or the ``virtual_images`` parameter. This will also automatically be inferred
if the file names are of the form ``uniqueid_suffix_ext1_extName.mrc`` and
``uniqueid_suffix_1_virtualName.mrc``. The first virtual image will be used as the navigation image
for fast plotting.
.. code-block:: python
>>> import hyperspy.api as hs
# Automatically load metadata_file="20220101_0001_info.txt" and
# any external/virtual images with the same naming convention
>>> hs.load("20220101_0001_movie.mrc")
<Signal2D, title: 20220101_0001_movie, dimensions: (32, 32|256, 256)>
# Load metadata from data_info.txt
>>> hs.load("data.mrc", metadata_file="data_info.txt")
# Load external image 1
>>> s = hs.load(
... "20220101_0001_movie.mrc",
... external_images=["20220101_0001_ext1_Ext #1.mrc"]
... )
>>> s.metadata["General"]["external_detectors"][0]
<Signal2D, title:, dimensions: (|32,32)>
# Will load virtual image 1
>>> s = hs.load(
... "20220101_0001_movie.mrc",
... virtual_images=["20220101_0001_1_Virtual #1.mrc"]
... )
>>> s.metadata["General"]["virtual_images"][0]
<Signal2D, title:, dimensions: (|32,32)>
API functions
^^^^^^^^^^^^^
.. automodule:: rsciio.mrc
:members:
|
