Blockfile#

RosettaSciIO can read and write the blockfile format from NanoMegas ASTAR software. It is used to store a series of diffraction patterns from scanning precession electron diffraction (SPED) measurements, with a limited set of metadata. The header of the blockfile contains information about centering and distortions of the diffraction patterns, but is not applied to the signal during reading. Blockfiles only support data values of type np.uint8 (integers in range 0-255).

Warning

While Blockfiles are supported, it is a proprietary format, and future versions of the format might therefore not be readable. Complete interoperability with the official software can neither be guaranteed.

Note

To use the intensity_scaling functionality, the optional dependency scikit-image is required.

API functions#

rsciio.blockfile.file_reader(filename, lazy=False, chunks='auto', endianess='<')#

Read a blockfile.

Parameters:
filenamestr, pathlib.Path

Filename of the file to read or corresponding pathlib.Path.

lazybool, default=False

Whether to open the file lazily or not. The file will stay open until closed in compute() or closed manually. get_file_handle() can be used to access the file handler and close it manually.

chunkstuple, int, dict or str, default=”auto”

The chunks used when reading the data lazily. This argument is passed to the dask.array.core.normalize_chunks() function.

endianessstr, default=”<”

"<" or ">", depending on how the bits are written to the file.

Returns:
list of dict

List of dictionaries containing the following fields:

  • ‘data’ – multidimensional numpy.ndarray or dask.array.Array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the parsed metadata

  • ‘original_metadata’ – dictionary containing the full metadata tree from the input file

When the file contains several datasets, each dataset will be loaded as separate dictionary.

rsciio.blockfile.file_writer(filename, signal, intensity_scaling=None, navigator='navigator', show_progressbar=True, endianess='<')#

Write signal to blockfile.

Parameters:
filenamestr, pathlib.Path

Filename of the file to write to or corresponding pathlib.Path.

signaldict

Dictionary containing the signal object. Should contain the following fields:

  • ‘data’ – multidimensional numpy array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the metadata tree

intensity_scalingstr, 2-tuple of float, 2-tuple of int

If the signal datatype is not numpy.ubyte, casting to this datatype without intensity rescaling results in overflow errors (default behavior) This argument provides intensity scaling strategies and the options are:

  • 'dtype': the limits of the datatype of the dataset, e.g. 0-65535 for numpy.ushort, are mapped onto 0-255, respectively. Does not work for float data types.

  • 'minmax': the minimum and maximum in the dataset are mapped to 0-255.

  • 'crop': everything below 0 and above 255 is set to 0 and 255, respectively

  • 2-tuple of floats or ints: the intensities between these values are scaled between 0-255, everything below is 0 and everything above is 255.

navigatorstr or array_like

A .blo file also saves a virtual bright field image for navigation. This option determines what kind of data is stored for this image. By default this is set to 'navigator', which results in using the hyperspy.api.signals.BaseSignal.navigator attribute if used with HyperSpy. Otherwise, it is calculated during saving which can take some time for large datasets. Alternatively, an array-like of the right shape may also be provided. If set to None, a zero array is stored in the file.

show_progressbarbool, default=True

Whether to show the progressbar or not.

endianessstr, default=”<”

"<" or ">", depending on how the bits are written to the file.