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.

Blockfiles are by default loaded in a “copy-on-write” manner using numpy.memmap . For blockfiles load takes the mmap_mode keyword argument enabling loading the file using a different mode. However, note that lazy loading does not support in-place writing (i.e lazy loading and the “r+” mode are incompatible).

Note

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

API functions#

rsciio.blockfile.file_reader(filename, lazy=False, mmap_mode=None, 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.

mmap_mode{None, “r+”, “r”, “w+”, “c”}, default=None

Argument passed to numpy.memmap. A memory-mapped array is stored on disk, and not directly loaded into memory. However, it can be accessed and sliced like any ndarray. Lazy loading does not support in-place writing (i.e lazy loading and the "r+" mode are incompatible). If None (default), the value is "r" when lazy=True, otherwise it is "c".

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.