epdfsuite.filereader

Functions

`add_detector`(camera_key, pixel_size, ...[, ...])	Add a new detector entry to the in-memory library and persist it to disk.
`extract_camera_type`(metadata[, detector_lib])	Identify the camera type from HyperSpy metadata using regex alias matching.
`extract_wavelength`([metadata, voltage_kv])	Determine the relativistic electron wavelength from metadata or voltage.
`get_detector_params`(camera_key[, detector_lib])	Return the parameters of a detector from the library, without alias entries.
`load_data`(file[, normalize, verbose])	Load a DM4 image file and return detector metadata and the image array.

epdfsuite.filereader.extract_camera_type(metadata, detector_lib={'Alpine': {'aliases': ['alpine'], 'binning': 1, 'description': 'Gatan Alpine direct detection camera', 'image_height': 3072, 'image_width': 4608, 'pixel_size': 5}, 'Alpine Vista': {'aliases': ['alpine.*vista', 'alpinevista'], 'binning': 1, 'description': 'Gatan Alpine Vista direct detection camera', 'image_height': 4092, 'image_width': 5760, 'pixel_size': 5}, 'ClearView': {'aliases': ['clearview'], 'binning': 1, 'description': 'Gatan ClearView high-performance scintillator camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 9}, 'Gatan 80X Metro': {'aliases': ['80x.*metro', '80x.*metr', 'metro'], 'binning': 1, 'description': 'Gatan 80X Metro direct electron detector', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'K2 IS': {'aliases': ['k2(?!.*base)', '^k2$'], 'binning': 1, 'description': 'Gatan K2 IS direct electron detector', 'image_height': 3712, 'image_width': 3840, 'pixel_size': 5.0}, 'K3 Base': {'aliases': ['k3.*base', 'k3base'], 'binning': 1, 'description': 'Gatan K3 Base direct electron detector', 'image_height': 3072, 'image_width': 4608, 'pixel_size': 5}, 'K3 IS': {'aliases': ['k3.*is', 'k3is', 'k3(?!.*base)', '^k3$'], 'binning': 1, 'description': 'Gatan K3 IS direct electron detector', 'image_height': 3456, 'image_width': 3456, 'pixel_size': 5}, 'Metro': {'aliases': ['metro(?!.*300)'], 'binning': 1, 'description': 'Gatan Metro in-situ counting camera (60-200 kV)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'Metro 300': {'aliases': ['metro.*300', 'metro300'], 'binning': 1, 'description': 'Gatan Metro 300 in-situ counting camera (120-300 kV)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'OneView': {'aliases': ['oneview(?!.*is)', '^oneview$'], 'binning': 1, 'description': 'Gatan OneView sCMOS camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}, 'OneView IS': {'aliases': ['oneview.*is', 'oneviewis'], 'binning': 1, 'description': 'Gatan OneView IS sCMOS camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}, 'Orius SC1000': {'aliases': ['orius.*sc1000', 'sc1000'], 'binning': 1, 'description': 'Gatan Orius SC1000 CCD camera', 'image_height': 4008, 'image_width': 2672, 'pixel_size': 9}, 'Orius SC200D': {'aliases': ['orius', 'sc200d'], 'binning': 1, 'description': 'Gatan Orius SC200D CCD camera', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 7.4}, 'Orius SC600': {'aliases': ['orius.*sc600', 'sc600'], 'binning': 1, 'description': 'Gatan Orius SC600 CCD camera', 'image_height': 2672, 'image_width': 2672, 'pixel_size': 9}, 'Rio 16': {'aliases': ['rio.*16', 'rio16', 'rio'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 16 megapixels', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 9}, 'Rio 4': {'aliases': ['rio.*4', 'rio4'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 4 megapixels', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 9}, 'Rio 9': {'aliases': ['rio.*9', 'rio9'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 9 megapixels', 'image_height': 3072, 'image_width': 3072, 'pixel_size': 9}, 'Stela': {'aliases': ['stela'], 'binning': 1, 'description': 'Gatan Stela hybrid-pixel camera', 'image_height': 512, 'image_width': 512, 'pixel_size': 55}, 'Ultrascan': {'aliases': ['ultrascan(?!.*(1000|4000))', '^ultrascan$'], 'binning': 1, 'description': 'Gatan Ultrascan CCD camera (2k)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 14.0}, 'Ultrascan 1000': {'aliases': ['ultrascan.*1000', 'us1000'], 'binning': 1, 'description': 'Gatan Ultrascan 1000 CCD camera', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 14}, 'Ultrascan 4000': {'aliases': ['ultrascan.*4000', 'us4000'], 'binning': 1, 'description': 'Gatan Ultrascan 4000 CCD camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}})[source]

Identify the camera type from HyperSpy metadata using regex alias matching.

First attempts an exact match of the image title against library keys, then falls back to case-insensitive regex search over each detector’s alias list.

Parameters:

metadata (HyperSpy metadata object) – Metadata loaded from a DM4 (or other HyperSpy-supported) file.
detector_lib (dict, optional) – Detector library to search. Defaults to the built-in DETECTOR_LIBRARY.

Returns:

camera_key (str or None) – Key of the matched detector in detector_lib, or None if not found.
camera_title (str or None) – Raw title string found in the metadata, or None if unavailable.

epdfsuite.filereader.extract_wavelength(metadata=None, voltage_kv=None)[source]

Determine the relativistic electron wavelength from metadata or voltage.

Searches the metadata recursively for a wavelength, beam energy, or accelerating voltage field. If a direct wavelength is found (0.001–1 Å) it is returned immediately. Otherwise the wavelength is computed from the voltage using the relativistic de Broglie relation:

\[\lambda = \frac{h}{\sqrt{2 m_e e V \left(1 + \frac{eV}{2 m_e c^2}\right)}}\]

Parameters:

metadata (HyperSpy metadata object, optional) – Metadata from a DM4 file. If None, voltage_kv must be provided.
voltage_kv (float, optional) – Accelerating voltage in kV. Overrides the voltage found in metadata if both are provided.

Returns:

wavelength (float or None) – Electron wavelength in Å, or None if neither voltage nor wavelength could be determined.

epdfsuite.filereader.get_detector_params(camera_key, detector_lib={'Alpine': {'aliases': ['alpine'], 'binning': 1, 'description': 'Gatan Alpine direct detection camera', 'image_height': 3072, 'image_width': 4608, 'pixel_size': 5}, 'Alpine Vista': {'aliases': ['alpine.*vista', 'alpinevista'], 'binning': 1, 'description': 'Gatan Alpine Vista direct detection camera', 'image_height': 4092, 'image_width': 5760, 'pixel_size': 5}, 'ClearView': {'aliases': ['clearview'], 'binning': 1, 'description': 'Gatan ClearView high-performance scintillator camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 9}, 'Gatan 80X Metro': {'aliases': ['80x.*metro', '80x.*metr', 'metro'], 'binning': 1, 'description': 'Gatan 80X Metro direct electron detector', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'K2 IS': {'aliases': ['k2(?!.*base)', '^k2$'], 'binning': 1, 'description': 'Gatan K2 IS direct electron detector', 'image_height': 3712, 'image_width': 3840, 'pixel_size': 5.0}, 'K3 Base': {'aliases': ['k3.*base', 'k3base'], 'binning': 1, 'description': 'Gatan K3 Base direct electron detector', 'image_height': 3072, 'image_width': 4608, 'pixel_size': 5}, 'K3 IS': {'aliases': ['k3.*is', 'k3is', 'k3(?!.*base)', '^k3$'], 'binning': 1, 'description': 'Gatan K3 IS direct electron detector', 'image_height': 3456, 'image_width': 3456, 'pixel_size': 5}, 'Metro': {'aliases': ['metro(?!.*300)'], 'binning': 1, 'description': 'Gatan Metro in-situ counting camera (60-200 kV)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'Metro 300': {'aliases': ['metro.*300', 'metro300'], 'binning': 1, 'description': 'Gatan Metro 300 in-situ counting camera (120-300 kV)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 5}, 'OneView': {'aliases': ['oneview(?!.*is)', '^oneview$'], 'binning': 1, 'description': 'Gatan OneView sCMOS camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}, 'OneView IS': {'aliases': ['oneview.*is', 'oneviewis'], 'binning': 1, 'description': 'Gatan OneView IS sCMOS camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}, 'Orius SC1000': {'aliases': ['orius.*sc1000', 'sc1000'], 'binning': 1, 'description': 'Gatan Orius SC1000 CCD camera', 'image_height': 4008, 'image_width': 2672, 'pixel_size': 9}, 'Orius SC200D': {'aliases': ['orius', 'sc200d'], 'binning': 1, 'description': 'Gatan Orius SC200D CCD camera', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 7.4}, 'Orius SC600': {'aliases': ['orius.*sc600', 'sc600'], 'binning': 1, 'description': 'Gatan Orius SC600 CCD camera', 'image_height': 2672, 'image_width': 2672, 'pixel_size': 9}, 'Rio 16': {'aliases': ['rio.*16', 'rio16', 'rio'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 16 megapixels', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 9}, 'Rio 4': {'aliases': ['rio.*4', 'rio4'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 4 megapixels', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 9}, 'Rio 9': {'aliases': ['rio.*9', 'rio9'], 'binning': 1, 'description': 'Gatan Rio CMOS camera 9 megapixels', 'image_height': 3072, 'image_width': 3072, 'pixel_size': 9}, 'Stela': {'aliases': ['stela'], 'binning': 1, 'description': 'Gatan Stela hybrid-pixel camera', 'image_height': 512, 'image_width': 512, 'pixel_size': 55}, 'Ultrascan': {'aliases': ['ultrascan(?!.*(1000|4000))', '^ultrascan$'], 'binning': 1, 'description': 'Gatan Ultrascan CCD camera (2k)', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 14.0}, 'Ultrascan 1000': {'aliases': ['ultrascan.*1000', 'us1000'], 'binning': 1, 'description': 'Gatan Ultrascan 1000 CCD camera', 'image_height': 2048, 'image_width': 2048, 'pixel_size': 14}, 'Ultrascan 4000': {'aliases': ['ultrascan.*4000', 'us4000'], 'binning': 1, 'description': 'Gatan Ultrascan 4000 CCD camera', 'image_height': 4096, 'image_width': 4096, 'pixel_size': 15}})[source]

Return the parameters of a detector from the library, without alias entries.

Parameters:

camera_key (str) – Key name of the detector in detector_lib.
detector_lib (dict, optional) – Detector library to query. Defaults to DETECTOR_LIBRARY.

Returns:

params (dict or None) – Copy of the detector parameter dictionary (pixel_size, image_width, image_height, binning, description), or None if camera_key is not found.

epdfsuite.filereader.load_data(file, normalize=True, verbose=True)[source]

Load a DM4 image file and return detector metadata and the image array.

Identifies the camera type and wavelength from the file metadata, optionally normalises the raw counts by the exposure time, and prints a summary of the detected instrument parameters.

Parameters:

file (str) – Path to the DM4 image file.
normalize (bool, optional) – If True (default), divide the image by the exposure time (s) to obtain a count-rate image. Has no effect if the exposure time cannot be found in the metadata.
verbose (bool, optional) – If True (default), print loaded file info and detector parameters.

Returns:

detector_info (dict) – Dictionary with keys: camera_type, camera_title, pixel_size (µm), image_width (px), image_height (px), binning, description, wavelength (Å), exposure_time (s, if found).
raw_image (ndarray) – 2D float array of the image, normalised by exposure time if requested.

epdfsuite.filereader.add_detector(camera_key, pixel_size, image_width, image_height, binning=1, description='', aliases=None)[source]

Add a new detector entry to the in-memory library and persist it to disk.

The entry is appended to the global DETECTOR_LIBRARY dictionary and immediately written back to camera_library.py.

Parameters:

camera_key (str) – Unique identifier for the detector (e.g. 'K3_300kV').
pixel_size (float) – Physical pixel size in micrometres (µm).
image_width (int) – Full-frame image width in pixels.
image_height (int) – Full-frame image height in pixels.
binning (int, optional) – Hardware binning factor applied at acquisition. Default is 1.
description (str, optional) – Human-readable description of the detector.
aliases (list of str, optional) – List of regex patterns (case-insensitive) used to match this detector from image title strings in metadata. Default is [].

Returns:

success (bool) – True if the detector was added, False if camera_key already exists in the library.