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).

API functions#

rsciio.blockfile.file_reader(filename, lazy=False, mmap_mode=None, endianess='<')#

Read a blockfile.

Parameters:

  • filename (str, pathlib.Path) – Filename of the file to read or corresponding pathlib.Path.

  • lazy (bool, Default=False) – Whether to open the file lazily or not.

  • endianess (str, Default="<") – "<" or ">", depending on how the bits are written to the file.

  • mmap_mode ({None, "r+", "r", "w+", "c"}, Default=None) – Argument passed to numpy.memmap(). If None (default), the value is "r" when lazy=True, otherwise it is "c".

Returns:

List of dictionaries containing 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 parsed metadata

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

Return type:

list of dicts

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

Write signal to blockfile.

Parameters:

  • filename (str, pathlib.Path) – Filename of the file to write to or corresponding pathlib.Path.

  • signal (dict) –

    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_scaling (str or 2-Tuple of float/int) –

    If the signal datatype is not numpy.uint8, 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.uint16, 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.

  • navigator (str 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.signal.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_progressbar (bool) – Whether to show the progressbar or not.

  • endianess (str) – '<' (default) or '>' determining how the bits are written to the file