hyperspy.io_plugins package


hyperspy.io_plugins.bcf module

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

Bases: hyperspy.io_plugins.bcf.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.


hypy helper method


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.bcf.Container

Bases: object

class hyperspy.io_plugins.bcf.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.bcf.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.


calculate and return real time for whole hypermap in seconds


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.

get_acq_instrument_dict(detector=False, **kwargs)

return python dictionary with aquisition instrument mandatory data


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

class hyperspy.io_plugins.bcf.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 the whole file as io.BytesIO object (in memory!).


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


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


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


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

hyperspy.io_plugins.bcf.file_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. 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.


interpret any string and return casted to appropriate dtype python object


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.bcf.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.blockfile module

hyperspy.io_plugins.blockfile.file_reader(filename, endianess='<', mmap_mode=None, lazy=False, **kwds)
hyperspy.io_plugins.blockfile.file_writer(filename, signal, **kwds)

Returns a header pre-populated with default values.

hyperspy.io_plugins.blockfile.get_header_from_signal(signal, endianess='<')

hyperspy.io_plugins.dens module

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

hyperspy.io_plugins.digital_micrograph module

class hyperspy.io_plugins.digital_micrograph.DigitalMicrographReader(f)

Bases: object

Class to read Gatan Digital Micrograph (TM) files.

Currently it supports versions 3 and 4.

dm_version, endian, tags_dict
parse_file, parse_header, get_image_dictionaries

Returns the image dictionaries of all images in the file except the thumbnails.

Return type:dict, None

Reads and returns the element type and length of the array.

The position in the file must be just after the array encoded dtype.


Reads and returns the length of the string.

The position in the file must be just after the string encoded dtype.


Reads and returns the struct definition tuple.

The position in the file must be just after the struct encoded dtype.


Parse the root TagGroup of the given DM3 file f. Returns the tuple (is_sorted, is_open, n_tags). endian can be either ‘big’ or ‘little’.

parse_tags(ntags, group_name='root', group_dict={})

Parse the DM file into a dictionary.

read_array(size, enc_eltype, extra=None, skip=False)

Read an array, defined by iarray, from file f with a given endianness (byte order). endian can be either ‘big’ or ‘little’.


Parse the data of the given DM3 file f with the given endianness (byte order). The infoArray iarray specifies how to read the data. Returns the tuple (file address, data). The tag data is stored in the platform’s byte order: ‘little’ endian for Intel, PC; ‘big’ endian for Mac, Motorola. If skip != 0 the data is actually skipped.

read_string(length, skip=False)
Read a string defined by the infoArray iarray from
file f with a given endianness (byte order).

endian can be either ‘big’ or ‘little’.

If it’s a tag name, each char is 1-Byte; if it’s a tag data, each char is 2-Bytes Unicode,

read_struct(definition, skip=False)

Read a struct, defined by iarray, from file f with a given endianness (byte order). Returns a list of 2-tuples in the form (fieldAddress, fieldValue). endian can be either ‘big’ or ‘little’.

simple_type = (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
class hyperspy.io_plugins.digital_micrograph.ImageObject(imdict, file, order='C', record_by=None)

Bases: object

hyperspy.io_plugins.digital_micrograph.file_reader(filename, record_by=None, order=None, lazy=False, optimize=True)

Reads a DM3 file and loads the data into the appropriate class. data_id can be specified to load a given image within a DM3 file that contains more than one dataset.

  • record_by (Str) – One of: SI, Signal2D
  • order (Str) – One of ‘C’ or ‘F’
  • lazy (bool, default False) – Load the signal lazily.
  • %s

hyperspy.io_plugins.edax module

hyperspy.io_plugins.edax.file_reader(filename, record_by='spectrum', endianess='<', **kwargs)
  • filename (str) – Name of file to read
  • record_by (str) – EDAX EDS data is always recorded by ‘spectrum’, so this parameter is not used
  • endianess (char) – Byte-order of data to read
  • **kwargs – Additional keyword arguments supplied to the readers
hyperspy.io_plugins.edax.get_ipr_dtype_list(endianess='<', version=333)

Get the data type list for an IPR image description file. Further information about the file format is available here.

Table of header tags:
  • version: 2 byte unsigned short; Current version number: 334
  • imageType: 2 byte unsigned short; 0=empty; 1=electron; 2=xmap; 3=disk; 4=overlay
  • label: 8 byte char array; Image label
  • sMin: 2 byte unsigned short; Min collected signal
  • sMax: 2 byte unsigned short; Max collected signal
  • color: 2 byte unsigned short; color: 0=gray; 1=R; 2=G; 3=B; 4=Y; 5=M; 6=C; 8=overlay
  • presetMode: 2 byte unsigned short; 0=clock; 1=live
  • presetTime: 4 byte unsigned long; Dwell time for x-ray (millisec)
  • dataType: 2 byte unsigned short; 0=ROI; 1=Net intensity; 2=K ratio; 3=Wt%; 4=Mthin2
  • timeConstantOld: 2 byte unsigned short; Amplifier pulse processing time [usec]
  • reserved1: 2 byte short; Not used
  • roiStartChan: 2 byte unsigned short; ROI starting channel
  • roiEndChan: 2 byte unsigned short; ROI ending channel
  • userMin: 2 byte short; User Defined Min signal range
  • userMax: 2 byte short; User Defined Max signal range
  • iADC: 2 byte unsigned short; Electron detector number: 1; 2; 3; 4
  • reserved2: 2 byte short; Not used
  • iBits: 2 byte unsigned short; conversion type: 8; 12 (not used)
  • nReads: 2 byte unsigned short; No. of reads per point
  • nFrames: 2 byte unsigned short; No. of frames averaged (not used)
  • fDwell: 4 byte float; Dwell time (not used)
  • accV: 2 byte unsigned short; V_acc in units of 100V
  • tilt: 2 byte short; Sample tilt [deg]
  • takeoff: 2 byte short; Takeoff angle [deg]
  • mag: 4 byte unsigned long; Magnification
  • wd: 2 byte unsigned short; Working distance [mm]
  • mppX: 4 byte float; Microns per pixel in X direction
  • mppY: 4 byte float; Microns per pixel in Y direction
  • nTextLines: 2 byte unsigned short; *No. of comment lines *
  • charText: (4 x 32) byte character array; Comment text
  • reserved3: 4 byte float; Not used
  • nOverlayElements: 2 byte unsigned short; No. of overlay elements
  • overlayColors: 16 array of 2 byte unsigned short; Overlay colors

# These two are specific to V334 of the file format, and are omitted # for compatibility with V333 of the IPR format - timeConstantNew: 4 byte float; Amplifier time constant [usec] - reserved4: 2 array of 4 byte float; Not used

  • endianess (char) – byte-order used to read the data
  • version (float) – version of .ipr file to read (only 333 and 334 have been tested) Default is 333 to be as backwards-compatible as possible, but the file version can be read from the file anyway, so this parameter should always be set programmatically

dtype_list – List of the data tags and data types that will be used by numpy to read an IPR file.

Return type:


hyperspy.io_plugins.edax.get_spc_dtype_list(load_all=False, endianess='<', version=0.61)

Get the data type list for an SPC spectrum. Further information about the file format is available here.

  • load_all (bool) – Switch to control if all the data is loaded, or if just the important pieces of the signal will be read (speeds up loading time)
  • endianess (char) – byte-order used to read the data
  • version (float) – version of spc file to read (only 0.61 and 0.70 have been tested) Default is 0.61 to be as backwards-compatible as possible, but the file version can be read from the file anyway, so this parameter should always be set programmatically
  • of header tags (Table) –
    • fVersion: 4 byte float; File format Version
    • aVersion: 4 byte float; Application Version
    • fileName: 8 array of 1 byte char; File name w/o ‘.spc’ extension (OLD)
    • collectDateYear: 2 byte short; Year the spectrum was collected
    • collectDateDay: 1 byte char; Day the spectrum was collected
    • collectDateMon: 1 byte char; Month the spectrum was collected
    • collectTimeMin: 1 byte char; Minute the spectrum was collected
    • collectTimeHour: 1 byte char; Hour the spectrum was collected
    • collectTimeHund: 1 byte char; Hundredth second the spectrum was collected
    • collectTimeSec: 1 byte char; Second the spectrum was collected
    • fileSize: 4 byte long; Size of spectrum file in bytes
    • dataStart: 4 byte long; Start of spectrum data in bytes offset from 0 of file
    • numPts: 2 byte short; Number of spectrum pts
    • intersectingDist: 2 byte short; Intersecting distance * 100 (mm)
    • workingDist: 2 byte short; Working distance * 100
    • scaleSetting: 2 byte short; Scale setting distance * 100
    • filler1: 24 byte;
    • spectrumLabel: 256 array of 1 byte char; Type label for spectrum, 0-39=material type, 40-255=sample
    • imageFilename: 8 array of 1 byte char; Parent Image filename
    • spotX: 2 byte short; Spot X in parent image file
    • spotY: 2 byte short; Spot Y in parent image file
    • imageADC: 2 byte short; Image ADC value 0-4095
    • discrValues: 5 array of 4 byte long; Analyzer Discriminator Values
    • discrEnabled: 5 array of 1 byte unsigned char; Discriminator Flags (0=Disabled,1=Enabled)
    • pileupProcessed: 1 byte char; Pileup Processed Flag (0=No PU,1=Static PU, 2=Dynamic PU,…)
    • fpgaVersion: 4 byte long; Firmware Version.
    • pileupProcVersion: 4 byte long; Pileup Processing Software Version
    • NB5000CFG: 4 byte long; Defines Hitachi NB5000 Dual Stage Cfg 0=None, 10=Eucentric Crossx,11= Eucentric Surface 12= Side Entry - Side 13 = Side Entry - Top
    • filler2: 12 byte;
    • evPerChan: 4 byte long; EV/channel
    • ADCTimeConstant: 2 byte short; ADC Time constant
    • analysisType: 2 byte short; Preset mode 1=clock, 2=count, 3=none, 4=live, 5=resume
    • preset: 4 byte float; Analysis Time Preset value
    • maxp: 4 byte long; Maximum counts of the spectrum
    • maxPeakCh: 4 byte long; Max peak channel number
    • xRayTubeZ: 2 byte short; XRF
    • filterZ: 2 byte short; XRF
    • current: 4 byte float; XRF
    • sampleCond: 2 byte short; XRF Air= 0, Vacuum= 1, Helium= 2
    • sampleType: 2 byte short; Bulk or thin
    • xrayCollimator: 2 byte unsigned short; 0=None, 1=Installed
    • xrayCapilaryType: 2 byte unsigned short; 0=Mono, 1=Poly
    • xrayCapilarySize: 2 byte unsigned short; Range : 20 – 5000 Microns
    • xrayFilterThickness: 2 byte unsigned short; Range : 0 – 10000 Microns
    • spectrumSmoothed: 2 byte unsigned short; 1= Spectrum Smoothed, Else 0
    • detector_Size_SiLi: 2 byte unsigned short; Eagle Detector 0=30mm, 1=80mm
    • spectrumReCalib: 2 byte unsigned short; 1= Peaks Recalibrated, Else 0
    • eagleSystem: 2 byte unsigned short; 0=None, 2=Eagle2, 3=Eagle3, 4-Xscope
    • sumPeakRemoved: 2 byte unsigned short; 1= Sum Peaks Removed, Else 0
    • edaxSoftwareType: 2 byte unsigned short; 1= Team Spectrum, Else 0
    • filler3: 6 byte;
    • escapePeakRemoved: 2 byte unsigned short; 1=Escape Peak Was Removed, Else 0
    • analyzerType: 4 byte unsigned long; Hardware type 1=EDI1, 2=EDI2, 3=DPP2, 31=DPP-FR, 32=DPP-FR2, 4=DPP3, 5= APOLLO XLT/XLS/DPP-4 (EDPP)
    • startEnergy: 4 byte float; Starting energy of spectrum
    • endEnergy: 4 byte float; Ending energy of spectrum
    • liveTime: 4 byte float; LiveTime
    • tilt: 4 byte float; Tilt angle
    • takeoff: 4 byte float; Take off angle
    • beamCurFact: 4 byte float; Beam current factor
    • detReso: 4 byte float; Detector resolution
    • detectType: 4 byte unsigned long; Detector Type: 1=Std-BE, 2=UTW, 3=Super UTW, 4=ECON 3/4 Open, 5=ECON 3/4 Closed, 6=ECON 5/6 Open, 7=ECON 5/6 Closed, 8=TEMECON; Add + 10 For Sapphire SiLi Detectors, (11-18), which started shipping in 1996. 30 = APOLLO 10 SDD, 31=APOLLO XV, 32 = APOLLO 10+, 40 = APOLLO 40 SDD ,50 = APOLLO-X, 51=APOLLO-XP, 52 = APOLLO-XL, 53 = APOLLO XL-XRF, 60 =APOLLO-XLT-LS, 61 =APOLLO-XLT-NW, 62 =APOLLO-XLT-SUTW
    • parThick: 4 byte float; Parlodion light shield thickness
    • alThick: 4 byte float; Aluminum light shield thickness
    • beWinThick: 4 byte float; Be window thickness
    • auThick: 4 byte float; Gold light shield thickness
    • siDead: 4 byte float; Si dead layer thickness
    • siLive: 4 byte float; Si live layer thickness
    • xrayInc: 4 byte float; X-ray incidence angle
    • azimuth: 4 byte float; Azimuth angle of detector
    • elevation: 4 byte float; Elevation angle of detector
    • bCoeff: 4 byte float; K-line B coefficient
    • cCoeff: 4 byte float; K-line C coefficient
    • tailMax: 4 byte float; Tail function maximum channel
    • tailHeight: 4 byte float; Tail height adjustment percentage
    • kV: 4 byte float; Acc voltage
    • apThick: 4 byte float; Ap window thickness
    • xTilt: 4 byte float; x tilt angle for mDX
    • yTilt: 4 byte float; y tilt angle for mDX
    • yagStatus: 4 byte unsigned long; 0 = N/A, 1 = YAG OUT, 2 = YAG IN
    • filler4: 24 byte;
    • rawDataType: 2 byte unsigned short; TEM or SEM data
    • totalBkgdCount: 4 byte float; Accumulated background counts
    • totalSpectralCount: 4 byte unsigned long; Accumulated spectrum counts
    • avginputCount: 4 byte float; Average spectral counts
    • stdDevInputCount: 4 byte float; Standard deviation of spectral counts
    • peakToBack: 2 byte unsigned short; Peak to background setting. 0 = off, 1 = low, 2 = medium, 3 = high, 4 = user selected
    • peakToBackValue: 4 byte float; Peak to back value
    • filler5: 38 byte;
    • numElem: 2 byte short; Number of peak id elements 0-48
    • at: 48 array of 2 byte unsigned short; atomic numbers for peak id elems
    • line: 48 array of 2 byte unsigned short; line numbers for peak id elems
    • energy: 48 array of 4 byte float; float energy of identified peaks
    • height: 48 array of 4 byte unsigned long; height in counts of id’ ed peaks
    • spkht: 48 array of 2 byte short; sorted peak height of id’ ed peaks
    • filler5_1: 30 byte;
    • numRois: 2 byte short; Number of ROI’s defined 0-48
    • st: 48 array of 2 byte short; Start channel # for each ROI
    • end: 48 array of 2 byte short; End channel # for each ROI
    • roiEnable: 48 array of 2 byte short; ROI enable/disable flags
    • roiNames: (24 x 8) array of 1 byte char; 8 char name for eah ROI
    • filler5_2: 1 byte;
    • userID: 80 array of 1 byte char; User ID (Vision S/W) - Overlapping
    • filler5_3: 111 byte;
    • sRoi: 48 array of 2 byte short; sorted ROI heights
    • scaNum: 48 array of 2 byte short; SCA number assigned for each ROI
    • filler6: 12 byte;
    • backgrdWidth: 2 byte short; Background width
    • manBkgrdPerc: 4 byte float; Percentage to move manual background down
    • numBkgrdPts: 2 byte short; Number of background points (2-64)
    • backMethod: 4 byte unsigned long; Background method 1=auto, 2=manual
    • backStEng: 4 byte float; Starting energy of background
    • backEndEng: 4 byte float; Ending energy of background
    • bg: 64 array of 2 byte short; Channel # of background point
    • bgType: 4 byte unsigned long; Background type. 1 = curve, 2 = linear.
    • concenKev1: 4 byte float; First concentration background point
    • concenKev2: 4 byte float; Second concentration background point
    • concenMethod: 2 byte short; 0 = Off, 1 = On
    • jobFilename: 32 array of 1 byte char; Vision Job Filename
    • filler7: 16 byte;
    • numLabels: 2 byte short; Number of displayed labels
    • label: (10 x 32) array 1 byte char; 32 character labels on the spectrum
    • labelx: 10 array of 2 byte short; x position of label in terms of channel #
    • labely: 10 array of 4 byte long; y position of label in terms of counts
    • zListFlag: 4 byte long; Flag to indicate if Z List was written
    • bgPercents: 64 array of 4 byte float; Percentage to move background point up and down.
    • IswGBg: 2 byte short; = 1 if new backgrd pts exist
    • BgPoints: 5 array of 4 byte float; Background points
    • IswGConc: 2 byte short; = 1 if given concentrations exist
    • numConcen: 2 byte short; Number of elements (up to 24)
    • ZList: 24 array of 2 byte short; Element list for which given concentrations exist
    • GivenConc: 24 array of 4 byte float; Given concentrations for each element in Zlist
    • filler8: 598 byte;
    • s: 4096 array of 4 byte long; counts for each channel
    • longFileName: 256 array of 1 byte char; Long filename for 32 bit version
    • longImageFileName: 256 array of 1 byte char; Associated long image file name
    • ADCTimeConstantNew: 4 byte float; Time constant: 2.5… 100 OR 1.6… 102.4 us

    # the following datatypes are only included for version 0.70:

    • filler9: 60 byte;
    • numZElements: 2 byte short; number of Z List elements for quant
    • zAtoms: 48 array of 2 byte short; Z List Atomic numbers
    • zShells: 48 array of 2 byte short; Z List Shell numbers

dtype_list – List of the data tags and data types that will be used by numpy to read an SPC file header.

Return type:



Get the data type list for an SPD map. Further information about the file format is available here.

Table of header tags:
  • tag: 16 byte char array; File ID tag (“MAPSPECTRA_DATA”)
  • version: 4 byte long; File version
  • nSpectra: 4 byte long; Number of spectra in file
  • nPoints: 4 byte long; Number of map pixels in X direction
  • nLines: 4 byte long; Number of map pixels in Y direction
  • nChannels: 4 byte long; Number of channels per spectrum
  • countBytes: 4 byte long; Number of count bytes per channel
  • dataOffset: 4 byte long; File offset in bytes for data start
  • nFrames: 4 byte long; Number of frames in live spectrum mapping
  • fName: 120 byte char array; File name of electron image acquired during mapping
Parameters:endianess (byte-order used to read the data) –
Returns:dtype_list – List of the data tags and data types that will be used by numpy to read an SPD file header.
Return type:list
hyperspy.io_plugins.edax.spc_reader(filename, endianess='<', load_all_spc=False, **kwargs)

Read data from an SPC spectrum specified by filename.

  • filename (str) – Name of SPC file to read
  • endianess (char) – Byte-order of data to read
  • load_all_spc (bool) – Switch to control if all of the .spc header is read, or just the important parts for import into HyperSpy
  • **kwargs – Remaining arguments are passed to the Numpy memmap function

list with dictionary of signal information to be passed back to hyperspy.io.load_with_reader

Return type:


hyperspy.io_plugins.edax.spd_reader(filename, endianess='<', nav_units=None, spc_fname=None, ipr_fname=None, load_all_spc=False, **kwargs)

Read data from an SPD spectral map specified by filename.

  • filename (str) – Name of SPD file to read
  • endianess (char) – Byte-order of data to read
  • nav_units ('nm', 'um', or None) – Default navigation units for EDAX data is in microns, so this is the default unit to save in the signal. Can also be specified as ‘nm’, which will output a signal with nm scale instead.
  • spc_fname (None or str) – Name of file from which to read the spectral calibration. If data was exported fully from EDAX TEAM software, an .spc file with the same name as the .spd should be present. If None, the default filename will be searched for. Otherwise, the name of the .spc file to use for calibration can be explicitly given as a string.
  • ipr_fname (None or str) – Name of file from which to read the spatial calibration. If data was exported fully from EDAX TEAM software, an .ipr file with the same name as the .spd (plus a “_Img” suffix) should be present. If None, the default filename will be searched for. Otherwise, the name of the .ipr file to use for spatial calibration can be explicitly given as a string.
  • load_all_spc (bool) – Switch to control if all of the .spc header is read, or just the important parts for import into HyperSpy
  • kwargs** – Remaining arguments are passed to the Numpy memmap function

list with dictionary of signal information to be passed back to hyperspy.io.load_with_reader

Return type:


hyperspy.io_plugins.emd module

class hyperspy.io_plugins.emd.EMD(signals=None, user=None, microscope=None, sample=None, comments=None)

Bases: object

Class for storing electron microscopy datasets.

The EMD class can hold an arbitrary amount of datasets in the signals dictionary. These are saved as HyperSpy Signal instances. Global metadata are saved in four dictionaries (user, microscope, sample, comments). To print relevant information about the EMD instance use the log_info() function. EMD instances can be loaded from and saved to emd-files, an hdf5 standard developed at Lawrence Berkeley National Lab (https://emdatasets.com/).


dictionary – Dictionary which contains all datasets as Signal instances.


dictionary – Dictionary which contains user related metadata.


dictionary – Dictionary which contains microscope related metadata.


dictionary – Dictionary which contains sample related metadata.


dictionary – Dictionary which contains additional commentary metadata.

add_signal(signal, name=None, metadata=None)

Add a HyperSpy signal to the EMD instance and make sure all metadata is present.

  • signal (Signal) – HyperSpy signal which should be added to the EMD instance.
  • name (string, optional) – Name of the (used as a key for the signals dictionary). If not specified, signal.metadata.General.title will be used. If this is an empty string, both name and signal title are set to ‘dataset’ per default. If specified, name overwrites the signal title.
  • metadata (dictionary) – Dictionary which holds signal specific metadata which will be added to the signal.

Return type:



This is the preferred way to add signals to the EMD instance. Directly adding to the signals dictionary is possible but does not make sure all metadata are correct. This method is also called in the standard constructor on all entries in the signals dictionary!

classmethod load_from_emd(filename, lazy=False)

Construct EMD object from an emd-file.

  • filename (string) – The name of the emd-file from which to load the signals. Standard format is ‘*.emd’.
  • False (bool, optional) – If False (default) loads data to memory. If True, enables loading only if requested.

emd – A EMD object containing the loaded signals.

Return type:



Print all relevant information about the EMD instance.


Save EMD data in a file with emd(hdf5)-format.

Parameters:filename (string, optional) – The name of the emd-file in which to store the signals. The default is ‘datacollection.emd’.
Return type:None
hyperspy.io_plugins.emd.file_reader(filename, log_info=False, lazy=False, **kwds)
hyperspy.io_plugins.emd.file_writer(filename, signal, signal_metadata=None, user=None, microscope=None, sample=None, comments=None, **kwds)

hyperspy.io_plugins.fei module

hyperspy.io_plugins.fei.dimension_array_dtype(n, DescriptionLength, UnitsLength)
hyperspy.io_plugins.fei.emi_reader(filename, dump_xml=False, **kwds)
hyperspy.io_plugins.fei.emixml2dtb(et, dictree)
hyperspy.io_plugins.fei.file_reader(filename, *args, **kwds)
hyperspy.io_plugins.fei.get_axes_from_position(header, data)

Compute the size, scale and offset of a linear axis from coordinates.

This function assumes rastering on a regular grid for the full size of each dimension before rastering over another one. Fox example: a11, a12, a13, a21, a22, a23 for a 2x3 grid.

Parameters:position (numpy array.) – Position coordinates of the axis. Normally as in PositionX/Y of the ser file.
Return type:dictionary with size, scale, offeset keys.
hyperspy.io_plugins.fei.get_data_dtype_list(file, offset, record_by)
hyperspy.io_plugins.fei.load_only_data(filename, array_shape, record_by, num_axes, data=None)
hyperspy.io_plugins.fei.parse_ExperimentalDescription(et, dictree)
hyperspy.io_plugins.fei.parse_TrueImageHeaderInfo(et, dictree)

Read 4 bytes as little endian integer in file


Read 8 bytes as little endian integer in file


Read 2 bytes as little endian integer in file

hyperspy.io_plugins.fei.ser_reader(filename, objects=None, *args, **kwds)

Reads the information from the file and returns it in the HyperSpy required format.

hyperspy.io_plugins.hspy module

hyperspy.io_plugins.hspy.dict2hdfgroup(dictionary, group, **kwds)
hyperspy.io_plugins.hspy.file_reader(filename, backing_store=False, lazy=False, **kwds)
hyperspy.io_plugins.hspy.file_writer(filename, signal, *args, **kwds)
hyperspy.io_plugins.hspy.get_signal_chunks(shape, dtype, signal_axes=None)

Function that claculates chunks for the signal, preferably at least one chunk per signal space.

  • shape (tuple) – the shape of the dataset to be sored / chunked
  • dtype ({dtype, string}) – the numpy dtype of the data
  • signal_axes ({None, iterable of ints}) – the axes defining “signal space” of the dataset. If None, the default h5py chunking is performed.
hyperspy.io_plugins.hspy.hdfgroup2dict(group, dictionary=None, lazy=False)
hyperspy.io_plugins.hspy.hdfgroup2signaldict(group, lazy=False)
hyperspy.io_plugins.hspy.overwrite_dataset(group, data, key, signal_axes=None, chunks=None, **kwds)
hyperspy.io_plugins.hspy.write_signal(signal, group, **kwds)

hyperspy.io_plugins.image module

hyperspy.io_plugins.image.file_reader(filename, **kwds)

Read data from any format supported by PIL.

Parameters:filename (str) –
hyperspy.io_plugins.image.file_writer(filename, signal, file_format='png', **kwds)

Writes data to any format supported by PIL

  • filename (str) –
  • signal (a Signal instance) –
  • file_format (str) – The fileformat defined by its extension that is any one supported by PIL.

hyperspy.io_plugins.mrc module

hyperspy.io_plugins.mrc.file_reader(filename, endianess='<', **kwds)
hyperspy.io_plugins.mrc.get_data_type(index, endianess='<')

hyperspy.io_plugins.msa module

hyperspy.io_plugins.msa.file_reader(filename, encoding='latin-1', **kwds)
hyperspy.io_plugins.msa.file_writer(filename, signal, format=None, separator=', ', encoding='latin-1')
hyperspy.io_plugins.msa.parse_msa_string(string, filename=None)

Parse an EMSA/MSA file content.

  • string (string or file object) – It must complain with the EMSA/MSA standard.
  • filename (string or None) – The filename.
  • Returns
  • --------
  • file_data_list (list) – The list containts a dictionary that contains the parsed information. It can be used to create a :class:BaseSignal using :func:hyperspy.io.dict2signal.

hyperspy.io_plugins.netcdf module

hyperspy.io_plugins.netcdf.file_reader(filename, *args, **kwds)
hyperspy.io_plugins.netcdf.nc_hyperspy_reader_0dot1(ncfile, filename, *args, **kwds)

hyperspy.io_plugins.protochips module

class hyperspy.io_plugins.protochips.ProtochipsCSV(filename, header_line_number=10)

Bases: object

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

hyperspy.io_plugins.ripple module

hyperspy.io_plugins.ripple.file_reader(filename, rpl_info=None, encoding='latin-1', mmap_mode='c', *args, **kwds)

Parses a Lispix (http://www.nist.gov/lispix/) ripple (.rpl) file and reads the data from the corresponding raw (.raw) file; or, read a raw file if the dictionary rpl_info is provided.

This format is often uses in EDS/EDX experiments.

Images and spectral images or data cubes that are written in the (Lispix) raw file format are just a continuous string of numbers.

Data cubes can be stored image by image, or spectrum by spectrum. Single images are stored row by row, vector cubes are stored row by row (each row spectrum by spectrum), image cubes are stored image by image.

All of the numbers are in the same format, such as 16 bit signed integer, IEEE 8-byte real, 8-bit unsigned byte, etc.

The “raw” file should be accompanied by text file with the same name and “.rpl” extension. This file lists the characteristics of the raw file so that it can be loaded without human intervention.

Alternatively, dictionary ‘rpl_info’ containing the information can be given.

Some keys are specific to HyperSpy and will be ignored by other software.

RPL stands for “Raw Parameter List”, an ASCII text, tab delimited file in which HyperSpy reads the image parameters for a raw file.


key type description

———- ———— ——————– # Mandatory keys: width int # pixels per row height int # number of rows depth int # number of images or spectral pts offset int # bytes to skip data-type str # ‘signed’, ‘unsigned’, or ‘float’ data-length str # bytes per pixel ‘1’, ‘2’, ‘4’, or ‘8’ byte-order str # ‘big-endian’, ‘little-endian’, or ‘dont-care’ record-by str # ‘image’, ‘vector’, or ‘dont-care’ # X-ray keys: ev-per-chan int # optional, eV per channel detector-peak-width-ev int # optional, FWHM for the Mn K-alpha line # HyperSpy-specific keys depth-origin int # energy offset in pixels depth-scale float # energy scaling (units per pixel) depth-units str # energy units, usually eV depth-name str # Name of the magnitude stored as depth width-origin int # column offset in pixels width-scale float # column scaling (units per pixel) width-units str # column units, usually nm width-name str # Name of the magnitude stored as width height-origin int # row offset in pixels height-scale float # row scaling (units per pixel) height-units str # row units, usually nm height-name str # Name of the magnitude stored as height signal str # Type of the signal stored, e.g. EDS_SEM convergence-angle float # TEM convergence angle in mrad collection-angle float # EELS spectrometer collection semi-angle in mrad beam-energy float # TEM beam energy in keV elevation-angle float # Elevation angle of the EDS detector azimuth-angle float # Elevation angle of the EDS detector live-time float # Live time per spectrum energy-resolution float # Resolution of the EDS (FHWM of MnKa) tilt-stage float # The tilt of the stage date str # date in ISO 8601 time str # time in ISO 8601 title str # title of the signal to be stored


When ‘data-length’ is 1, the ‘byte order’ is not relevant as there is only one byte per datum, and ‘byte-order’ should be ‘dont-care’.

When ‘depth’ is 1, the file has one image, ‘record-by’ is not relevant and should be ‘dont-care’. For spectral images, ‘record-by’ is ‘vector’. For stacks of images, ‘record-by’ is ‘image’.

Floating point numbers can be IEEE 4-byte, or IEEE 8-byte. Therefore if data-type is float, data-length MUST be 4 or 8.

The rpl file is read in a case-insensitive manner. However, when providing a dictionary as input, the keys MUST be lowercase.

Comment lines, beginning with a semi-colon ‘;’ are allowed anywhere.

The first non-comment in the rpl file line MUST have two column names: ‘name_1’<TAB>’name_2’; any name would do e.g. ‘key’<TAB>’value’.

Parameters can be in ANY order.

In the rpl file, the parameter name is followed by ONE tab (spaces are ignored) e.g.: ‘data-length’<TAB>‘2’

In the rpl file, other data and more tabs can follow the two items on each row, and are ignored.

Other keys and values can be included and are ignored.

Any number of spaces can go along with each tab.

hyperspy.io_plugins.ripple.file_writer(filename, signal, encoding='latin-1', *args, **kwds)

Parse information from ripple (.rpl) file. Accepts file object ‘fp. Returns dictionary rpl_info.

hyperspy.io_plugins.ripple.read_raw(rpl_info, fp, mmap_mode='c')

Read the raw file object ‘fp’ based on the information given in the ‘rpl_info’ dictionary.

  • rpl_info (dict) – A dictionary containing the keywords as parsed by read_rpl
  • fp
  • mmap_mode ({None, 'r+', 'r', 'w+', 'c'}, optional) –
  • not None, then memory-map the file, using the given mode (If) –
  • numpy.memmap) The mode has no effect for pickled or ((see) –
  • files. (zipped) –
  • memory-mapped array is stored on disk, and not directly loaded (A) –
  • memory. However, it can be accessed and sliced like any (into) –
  • Memory mapping is especially useful for accessing (ndarray.) –
  • fragments of large files without reading the entire file (small) –
  • memory. (into) –
hyperspy.io_plugins.ripple.write_raw(filename, signal, record_by)

Writes the raw file object

filename : string
the filename, either with the extension or without it
record_by : string
‘vector’ or ‘image’
hyperspy.io_plugins.ripple.write_rpl(filename, keys_dictionary, encoding='ascii')

hyperspy.io_plugins.semper_unf module

class hyperspy.io_plugins.semper_unf.SemperFormat(data, title='', offsets=(0.0, 0.0, 0.0), scales=(1.0, 1.0, 1.0), units=(<undefined>, <undefined>, <undefined>), metadata=None)

Bases: object

Class for importing and exporting SEMPER .unf-files.

The SemperFormat class represents a SEMPER binary file format with a header, which holds additional information. .unf-files can be saved and read from files.


ndarray (N=3) – The phase map or magnetization information in a 3D array (with one slice).


string – Title of the file (not to be confused with the filename).


tuple (N=3) of floats – Offset shifts (in nm) of the grid origin (does not have to start at 0) in x, y, z.


tuple (N=3) of floats – Grid spacing (nm per pixel) in x, y, z.


tuple (N=3) of strings – Units of the grid in x, y, z.


dictionary – A dictionary of all flags and metadata present in the .unf-file.

HEADER_DTYPES = [('NCOL', '<i2'), ('NROW', '<i2'), ('NLAY', '<i2'), ('ICLASS', '<i2'), ('IFORM', '<i2'), ('IFLAG', '<i2'), ('IFORM', '<i2')]
ICLASS_DICT = {1: 'image', 2: 'macro', 3: 'fourier', 4: 'spectrum', 5: 'correlation', 6: <undefined>, 7: 'walsh', 8: 'position list', 9: 'histogram', 10: 'display look-up table'}
ICLASS_DICT_INV = {'image': 1, 'macro': 2, 'fourier': 3, 'spectrum': 4, 'correlation': 5, <undefined>: 6, 'walsh': 7, 'position list': 8, 'histogram': 9, 'display look-up table': 10}
IFORM_DICT = {0: <class 'numpy.int8'>, 1: <class 'numpy.int16'>, 2: <class 'numpy.float32'>, 3: <class 'numpy.complex64'>, 4: <class 'numpy.int32'>}
IFORM_DICT_INV = {<class 'numpy.int8'>: 0, <class 'numpy.int16'>: 1, <class 'numpy.float32'>: 2, <class 'numpy.complex64'>: 3, <class 'numpy.int32'>: 4}
LABEL_DTYPES = [('SEMPER', ('<i2', 6)), ('NCOL', ('<i2', 2)), ('NROW', ('<i2', 2)), ('NLAY', ('<i2', 2)), ('ICCOLN', ('<i2', 2)), ('ICROWN', ('<i2', 2)), ('ICLAYN', ('<i2', 2)), ('ICLASS', '<i2'), ('IFORM', '<i2'), ('IWP', '<i2'), ('DATE', ('<i2', 6)), ('NCRANG', '<i2'), ('RANGE', ('<i2', 27)), ('IPLTYP', '<i2'), ('NCOLH', '<i2'), ('NROWH', '<i2'), ('NLAYH', '<i2'), ('ICCOLNH', '<i2'), ('ICROWNH', '<i2'), ('ICLAYNH', '<i2'), ('REALCO', '<i2'), ('NBLOCK', '<i2'), ('FREE', ('<i2', 3)), ('DATAV6', ('<i2', 4)), ('DATAV7', ('<i2', 4)), ('DZV5', ('<i2', 4)), ('Z0V4', ('<i2', 4)), ('DYV3', ('<i2', 4)), ('Y0V2', ('<i2', 4)), ('DXV1', ('<i2', 4)), ('X0V0', ('<i2', 4)), ('NTITLE', '<i2'), ('TITLE', ('<i2', 144)), ('XUNIT', ('<i2', 4)), ('YUNIT', ('<i2', 4)), ('ZUNIT', ('<i2', 4))]
classmethod from_signal(signal)

Import a SemperFormat object from a Signal object.

Parameters:signal (Signal) – The signal which should be imported.
Return type:None
classmethod load_from_unf(filename, lazy=False)

Load a .unf-file into a SemperFormat object.

Parameters:filename (string) – The name of the unf-file from which to load the data. Standard format is ‘*.unf’.
Returns:semper – SEMPER file format object containing the loaded information.
Return type:SemperFormat (N=1)

log important flag information of the SemperFormat object.

Return type:None
save_to_unf(filename='semper.unf', skip_header=False)

Save a SemperFormat to a file.

  • filename (string, optional) – The name of the unf-file to which the data should be written.
  • skip_header (boolean, optional) – Determines if the header, title and label should be skipped (useful for some other programs). Default is False.

Return type:



Export a SemperFormat object to a Signal object.

Returns:signal – The exported signal.
Return type:Signal
hyperspy.io_plugins.semper_unf.file_reader(filename, **kwds)
hyperspy.io_plugins.semper_unf.file_writer(filename, signal, **kwds)
hyperspy.io_plugins.semper_unf.pack_to_intbytes(fmt, value)

Pack a value into a byte list using format fmt and represent it as int (range 0-255).

hyperspy.io_plugins.semper_unf.unpack_from_intbytes(fmt, byte_list)

Read in a list of bytes (as int with range 0-255) and unpack them with format fmt.

hyperspy.io_plugins.tiff module

class hyperspy.io_plugins.tiff.Metadata(original_metadata)

Bases: object

hyperspy.io_plugins.tiff.file_reader(filename, record_by='image', force_read_resolution=False, **kwds)

Read data from tif files using Christoph Gohlke’s tifffile library. The units and the scale of images saved with ImageJ or Digital Micrograph is read. There is limited support for reading the scale of files created with Zeiss and FEI SEMs.

  • filename (str) –
  • record_by ({'image'}) – Has no effect because this format only supports recording by image.
  • force_read_resolution (Bool) – Default: False. Force reading the x_resolution, y_resolution and the resolution_unit of the tiff tags. See http://www.awaresystems.be/imaging/tiff/tifftags/resolutionunit.html
  • optional (**kwds,) –
hyperspy.io_plugins.tiff.file_writer(filename, signal, export_scale=True, extratags=[], **kwds)

Writes data to tif using Christoph Gohlke’s tifffile library

  • filename (str) –
  • signal (a BaseSignal instance) –
  • export_scale (bool) – default: True Export the scale and the units (compatible with DM and ImageJ) to appropriate tags. If the scikit-image version is too old, use the hyperspy embedded tifffile library to allow exporting the scale and the unit.

hyperspy.io_plugins.unbcf_fast module

class hyperspy.io_plugins.unbcf_fast.DataStream

Bases: object


Module contents