Skip to main content
`Ctrl`+`K`

# 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', endianness='<')

  Read a blockfile.

  Parameters:
    filename `python: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. 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.

    chunks `python:tuple`, `python:int`, `python:dict` or `python:str`, default=”auto”

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

    endianness `python:str`, default=”<”

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

  Returns:
    `python:list` of `python: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, endianness='<')

  Write signal to blockfile.

  Parameters:
    filename `python:str`, `pathlib.Path`

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

    signal `python: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 `python:str`, 2-tuple of `python:float`, 2-tuple of `python: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.

    navigator `python:str` or numpy: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_progressbar bool, default=True

      Whether to show the progressbar or not.

    endianness `python:str`, default=”<”

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