hyperspy.io_plugins.bruker module

class hyperspy.io_plugins.bruker.BCF_reader(filename, instrument=None)

Bases: hyperspy.io_plugins.bruker.SFS_reader

Class to read bcf (Bruker hypermapping) file.

Inherits SFS_reader and all its attributes and methods.

Attributes: filename

Methods: check_index_valid, parse_hypermap

The class instantiates HyperHeader class as self.header attribute where all metadata, sum eds spectras, (SEM) images are stored.

add_filename_to_general(item)

hypy helper method

check_index_valid(index)

check and return if index is valid

parse_hypermap(index=None, downsample=1, cutoff_at_kV=None, lazy=False)

Unpack the Delphi/Bruker binary spectral map and return numpy array in memory efficient way.

Pure python/numpy implementation – slow, or cython/memoryview/numpy implimentation if compilied and present (fast) is used.

Arguments: index – the index of hypermap in bcf if there is more than one

hyper map in file.

downsample – downsampling factor (integer). Diferently than

block_reduce from skimage.measure, the parser populates reduced array by suming results of pixels, thus having lower memory requiriments. (default 1)

cutoff_at_kV – value in keV to truncate the array at. Helps reducing

size of array. (default None)

lazy – return dask.array (True) or numpy.array (False) (default False)

Returns: numpy or dask array of bruker hypermap, with (y,x,E) shape.

class hyperspy.io_plugins.bruker.Container

Bases: object

class hyperspy.io_plugins.bruker.EDXSpectrum(spectrum)

Bases: object

energy_to_channel(energy, kV=True)

convert energy to channel index, optional kwarg ‘kV’ (default: True) should be set to False if given energy units is in V

class hyperspy.io_plugins.bruker.HyperHeader(xml_str, indexes, instrument=None)

Bases: object

Wrap Bruker HyperMaping xml header into python object.

Arguments: xml_str – the uncompressed to be provided with extracted Header xml from bcf. indexes – list of indexes of available datasets

Methods: estimate_map_channels, estimate_map_depth

If Bcf is version 2, the bcf can contain stacks of hypermaps - thus header part can contain multiply sum eds spectras and it’s metadata per hypermap slice which can be selected using index. Bcf can record number of imagery from different imagining detectors (BSE, SEI, ARGUS, etc…): access to imagery is throught image index.

calc_real_time()

calculate and return real time for whole hypermap in seconds

estimate_map_channels(index=0)

estimate minimal size of energy axis so any spectra from any pixel would not be truncated.

Arguments: index – index of the map if multiply hypermaps are present in the same bcf.

Returns: optimal channel number

estimate_map_depth(index=0, downsample=1, for_numpy=False)

estimate minimal dtype of array using cumulative spectra of the all pixels so that no data would be truncated.

Arguments: index – index of the hypermap if multiply hypermaps are

present in the same bcf. (default 0)

downsample – downsample factor (should be integer; default 1) for_numpy – False produce unsigned, True signed (or unsigned) types:

if hypermap will be loaded using the pure python function where numpy’s inplace integer addition will be used – the dtype should be signed; if cython implementation will be used (default), then any returned dtypes can be safely unsigned. (default False)

Returns: numpy dtype large enought to use in final hypermap numpy array.

The method estimates the value from sum eds spectra, dividing the maximum energy pulse value from raster x and y and to be on the safe side multiplying by 2.

gen_hspy_item_dict_basic()

get_acq_instrument_dict(detector=False, **kwargs)

return python dictionary with aquisition instrument mandatory data

get_spectra_metadata(index=0)

return objectified xml with spectra metadata Arguments: index – index of hypermap/spectra (default 0)

class hyperspy.io_plugins.bruker.SFSTreeItem(item_raw_string, parent)

Bases: object

Class to manage one internal sfs file.

Reading, reading in chunks, reading and extracting, reading without extracting even if compression is pressent.

Attributes: item_raw_string – the bytes from sfs file table describing the file parent – the item higher hierarchicaly in the sfs file tree

Methods: read_piece, setup_compression_metadata, get_iter_and_properties, get_as_BytesIO_string

get_as_BytesIO_string()

Get the whole file as io.BytesIO object (in memory!).

get_iter_and_properties()

Generate and return the iterator of data chunks and properties of such chunks such as size and count.

Method detects if data is compressed and uses iterator with decompression involved, else uses simple iterator of chunks.

Returns

(iterator, chunk_size, number_of_chunks)

read_piece(offset, length)

Read and returns raw byte string of the file without applying any decompression.

Arguments: offset: seek value length: length of the data counting from the offset

Returns: io.ByteIO object

setup_compression_metadata()

parse and setup the number of compression chunks

and uncompressed chunk size as class attributes.

Sets up attributes: self.uncompressed_blk_size, self.no_of_compr_blk

class hyperspy.io_plugins.bruker.SFS_reader(filename)

Bases: object

Class to read sfs file. SFS is AidAim software’s(tm) single file system. The class provides basic reading capabilities of such container. It is capable to read compressed data in zlib, but SFS can contain other compression which is not implemented here. It is also not able to read encrypted sfs containers.

This class can be used stand alone or inherited in construction of file readers using sfs technolgy.

Attributes: filename

Methods: get_file

get_file(path)

Return the SFSTreeItem (aka internal file) object from sfs container.

Arguments: path – internal file path in sfs file tree. Path accepts only

standard - forward slash for directories.

Returns: object (SFSTreeItem), which can be read into byte stream, in chunks or whole using objects methods.

Example: to get “file” object ‘kitten.png’ in folder ‘catz’ which resides in root directory of sfs, you would use:

>>> instance_of_SFSReader.get_file('catz/kitten.png')

See also: SFSTreeItem

hyperspy.io_plugins.bruker.bcf_hyperspectra(obj_bcf, index=None, downsample=None, cutoff_at_kV=None, lazy=False)

Return hyperspy required list of dict with eds hyperspectra and metadata.

hyperspy.io_plugins.bruker.bcf_images(obj_bcf)

return hyperspy required list of dict with sem images and metadata.

hyperspy.io_plugins.bruker.bcf_reader(filename, select_type=None, index=None, downsample=1, cutoff_at_kV=None, instrument=None, lazy=False)

Reads a bruker bcf file and loads the data into the appropriate class, then wraps it into appropriate hyperspy required list of dictionaries used by hyperspy.api.load() method.

Keyword arguments: select_type – One of: spectrum_image, image. If none specified, then function

loads everything, else if specified, loads either just sem imagery, or just hyper spectral mapping data (default None).

index – index of dataset in bcf v2 can be None integer and ‘all’

(default None); None will select first available mapping if more than one. ‘all’ will return all maps if more than one present; integer will return only selected map.

downsample – the downsample ratio of hyperspectral array (downsampling

height and width only), can be integer from 1 to inf, where ‘1’ means no downsampling will be applied (default 1).

cutoff_at_kV – if set (can be int of float >= 0) can be used either, to

crop or enlarge energy range at max values. (default None)

instrument – str, either ‘TEM’ or ‘SEM’. Default is None.

hyperspy.io_plugins.bruker.default_extension = 0

hyperspy.io_plugins.bruker.description = "the proprietary format used by Bruker's\nEsprit(R) software to save hypermaps together with 16bit SEM imagery,\nEDS spectra and metadata describing the dimentions of the data and\nSEM/TEM (limited) parameters"

hyperspy.io_plugins.bruker.dictionarize(t)

hyperspy.io_plugins.bruker.fast_unbcf = False

hyperspy.io_plugins.bruker.file_extensions = ('bcf', 'spx')

hyperspy.io_plugins.bruker.file_reader(filename, *args, **kwds)

hyperspy.io_plugins.bruker.fix_dec_patterns = re.compile(b'(>-?\\d+),(\\d*([Ee]-?\\d*)?<)')

hyperspy.io_plugins.bruker.format_name = 'bruker composite file bcf'

hyperspy.io_plugins.bruker.full_support = False

hyperspy.io_plugins.bruker.gen_detector_node(spectrum)

hyperspy.io_plugins.bruker.gen_elem_list(the_dict)

hyperspy.io_plugins.bruker.gen_iso_date_time(node)

hyperspy.io_plugins.bruker.get_mapping(mode)

hyperspy.io_plugins.bruker.guess_mode(hv)

there is no way to determine what kind of instrument was used from metadata: TEM or SEM. However simple guess can be made using the acceleration voltage, assuming that SEM is <= 30kV or TEM is >30kV

hyperspy.io_plugins.bruker.interpret(string)

interpret any string and return casted to appropriate dtype python object

hyperspy.io_plugins.bruker.parse_line(line_string)

standardize line describtion.

Bruker saves line description in all caps and omits the type if only one exists instead of using alfa

hyperspy.io_plugins.bruker.py_parse_hypermap(virtual_file, shape, dtype, downsample=1)

Unpack the Delphi/Bruker binary spectral map and return numpy array in memory efficient way using pure python implementation. (Slow!)

The function is long and complicated due to complexity of Delphi packed array. Whole parsing is placed in one function to reduce overhead of python function calls. For cleaner parsing logic, please, see fast cython implementation at hyperspy/io_plugins/unbcf_fast.pyx

The method is only meant to be used if for some reason c (generated with cython) version of the parser is not compiled.

virtual_file – virtual file handle returned by SFS_reader instance

or by object inheriting it (e.g. BCF_reader instance)

shape – numpy shape dtype – numpy dtype downsample – downsample factor

note!: downsample, shape and dtype are interconnected and needs to be properly calculated otherwise wrong output or segfault is expected

numpy array of bruker hypermap, with (y, x, E) shape.

hyperspy.io_plugins.bruker.reads_images = True

hyperspy.io_plugins.bruker.reads_spectrum = True

hyperspy.io_plugins.bruker.reads_spectrum_image = True

hyperspy.io_plugins.bruker.spx_reader(filename, lazy=False)

hyperspy.io_plugins.bruker.st = {1: 'B', 2: 'B', 4: 'H', 8: 'I', 16: 'Q'}

hyperspy.io_plugins.bruker.warn_once = True

hyperspy.io_plugins.bruker.writes = False