The geometry Module#

This module contains the implementation of the functions to manipulate geometry information.

compute_pix_maps(geometry: TypeDetector) → PixelMaps#

Computes pixel maps from CrystFEL geometry information.

This function takes as input some geometry information read from a CrystFEL file, and returns a set of pre-computed pixel maps.

The origin and the orientation of the reference system for the pixel maps are set according to the same conventions as CrystFEL:

The center of the reference system is the beam interaction point.
+z is the beam direction, and points along the beam (i.e. away from the source).
+y points towards the zenith (ceiling).
+x completes the right-handed coordinate system.

Parameters:

geometry (TypeDetector) – a CrystFEL geometry object (A TypeDetector objects returned by the load_crystfel_geometry() function).

Returns:

a namedtuple storing the the pixel maps. It contains:

an attribute named ‘x’ whose value is a pixel map for the x coordinate.
an attribute named ‘y’ whose value is a pixel map for the y coordinate.
an attribute named ‘z’ whose value is a pixel map for the z coordinate.
an attribute named ‘r’ whose value is a pixel map storing the distance of each pixel from the center of the reference system.
an attribute named ‘phi’ whose value is a pixel map storing the amplitude of the angle between each pixel, the center of the reference system, and the x axis.

Return type:

PixelMaps

compute_visualization_pix_maps(geometry: TypeDetector) → PixelMaps#

Computes pixel maps for data visualization from CrystFEL geometry information.

This function takes as input some geometry information read from a CrystFEL file, and returns a set of pre-computed pixel maps that can be used to display data in an ImageView widget (from the PyQtGraph library).

These pixel maps are different from the ones generated by the compute_pix_maps() function. The main differences are:

The origin of the reference system is not the beam interaction point, but the top left corner of the array used to visualize the data.
Only the x and y pixel maps are available. The other entries in the returned named tuple (z, r and phi) are set to None.

Parameters:

geometry (Dict[str, Any]) – a CrystFEL geometry object (A dictionary returned by the load_crystfel_geometry() function).

Returns:

a namedtuple storing the the pixel maps.

an attribute named ‘.x’ whose value is a pixel map for the x coordinate.
an attribute named ‘.y’ whose value is a pixel map for the y coordinate.

Return type:

PixelMaps

apply_geometry_to_data(data: ndarray, geometry: TypeDetector) → ndarray#

Applies CrystFEL geometry information to some data.

This function takes as input some geometry information read from a CrystFEL file, and some data on which to apply the information. It returns an array that can be displayed using libraries like matplotlib or PyQtGraph.

The shape of the returned array is big enough to display all the pixel values in the input data, and is symmetric around the center of the reference system (i.e: the beam interaction point).

These restrictions often cause the returned array to be bigger than the minimum size needed to store the physical layout of the pixels in the detector, particularly if the detector is not centered at the beam interaction point.

Parameters:

data (numpy.ndarray) – the data on which the geometry information should be applied.
geometry (TypeDetector) – a CrystFEL geometry object (A TypeDetector object returned by the load_crystfel_geometry() function).

Returns:

an array containing the data with the geometry information applied.

Return type:

numpy.ndarray

This module contains Python re-implementations of some functions from the CrystFEL software package.

class CrystFELGeometry(detector: TypeDetector, beam: TypeBeam, hdf5_peak_path: Optional[str])#

Bases: tuple

Create new instance of CrystFELGeometry(detector, beam, hdf5_peak_path)

detector: TypeDetector#: Alias for field number 0

beam: TypeBeam#: Alias for field number 1

hdf5_peak_path: Optional[str]#: Alias for field number 2

load_crystfel_geometry(file: Union[str, PathLike, StringIO, TextIOWrapper]) → CrystFELGeometry#

Loads a CrystFEL geometry file.

This function is a re-implementation of the get_detector_geometry_2 function from CrystFEL. It reads information from a CrystFEL geometry file, which uses a key/value language, fully documented in the relevant man page. This function returns objects whose content matches CrystFEL’s internal representation of the information in the file (see the libcrystfel/src/detector.h and the libcrystfel/src/image.c files from CrystFEL’s source code for more information).

The code of this function is currently synchronized with the code of the function ‘get_detector_geometry_2’ in CrystFEL at commit cff9159b4bc6.

Parameters:

file (Union[str, PathLike, StringIO, TextIOWrapper]) – Either the path to a CrystFEL geometry file, or a text file handler object.

Returns:

a tuple with the information loaded from the file.

The first entry in the tuple is a dictionary storing information strictly related to the detector geometry. The following is a brief description of the key/value pairs in the dictionary.

Detector-related key/pairs

panels the panels in the detector. The value corresponding to this key is a dictionary containing information about the panels that make up the detector. In the dictionary, the keys are the panel names, and the values are further dictionaries storing information about the panels.

bad: the bad regions in the detector. The value corresponding to this key is a dictionary containing information about the bad regions in the detector. In the dictionary, the keys are the bad region names, and the values are further dictionaries storing information about the bad regions.

mask_bad: the value used in a mask to label a pixel as bad.

mask_good: the value used in a mask to label a pixel as good.

rigid_groups: the rigid groups of panels in the detector. The value corresponding to this key is a dictionary containing information about the rigid groups in the detector. In the dictionary, the keys are the names of the rigid groups and the values are lists storing the names of the panels belonging to eachgroup.

rigid_groups_collections: the collections of rigid groups of panels in the detector. The value corresponding to this key is a dictionary containing information about the rigid group collections in the detector. In the dictionary, the keys are the names of the rigid group collections and the values are lists storing the names of the rigid groups belonging to the collections.

furthest_out_panel: the name of the panel where the furthest away pixel from the center of the reference system can be found.

furthest_out_fs: the fs coordinate, within its panel, of the furthest away pixel from the center of the reference system.

furthest_out_ss: the ss coordinate, within its panel, of the furthest away pixel from the center of the reference system.

furthest_in_panel: the name of the panel where the closest pixel to the center of the reference system can be found.

furthest_in_fs: the fs coordinate, within its panel, of the closest pixel to the center of the reference system.

furthest_in_ss: the ss coordinate, within its panel, of the closest pixel to the center of the reference system.

Panel-related key/pairs

cnx: the x location of the corner of the panel in the reference system.

cny: the y location of the corner of the panel in the reference system.

clen: the distance, as reported by the facility, of the sample interaction point from the corner of the first pixel in the panel .

clen_from: the location of the clen information in a data file, in case the information must be extracted from it.

coffset: the offset to be applied to the clen value to determine the real distance of the panel from the interaction point.

mask: the location of the mask data for the panel in a data file.

mask_file: the data file in which the mask data for the panel can be found.

satmap: the location of the per-pixel saturation map for the panel in a data file.

satmap_file: the data file in which the per-pixel saturation map for the panel can be found.

res: the resolution of the panel in pixels per meter.

badrow: the readout direction for the panel, for filtering out clusters of peaks. The value corresponding to this key is either ‘x’ or ‘y’.

no_index: wether the panel should be considered entirely bad. The panel will be considered bad if the value corresponding to this key is non-zero.

adu_per_photon: the number of detector intensity units per photon for the panel.

max_adu: the detector intensity unit value above which a pixel of the panel should be considered unreliable.

data: the location, in a data file, of the data block where the panel data is stored.

adu_per_eV: the number of detector intensity units per eV of photon energy for the panel.

dim_structure: a description of the structure of the data block for the panel. The value corresponding to this key is a list of strings describing the meaning of each axis in the data block. See the crystfel_geometry man page for a detailed explanation.

fsx: the fs->x component of the matrix transforming pixel indexes to detector reference system coordinates.

fsy: the fs->y component of the matrix transforming pixel indexes to detector reference system coordinates.

fsz: the fs->z component of the matrix transforming pixel indexes to detector reference system coordinates.

ssx: the ss->x component of the matrix transforming pixel indexes to detector reference system coordinates.

ssy: the ss->y component of the matrix transforming pixel indexes to detector reference system coordinates.

ssz: the ss->z component of the matrix transforming pixel indexes to detector reference system coordinates.

rail_x: the x component, with respect to the reference system, of the direction of the rail along which the detector can be moved.

rail_y: the y component, with respect to the reference system, of the direction of the rail along which the detector can be moved.

rail_z: the z component, with respect to the reference system, of the direction of the rail along which the detector can be moved.

clen_for_centering: the value of clen at which the beam hits the detector at the origin of the reference system.

xfs: the x->fs component of the matrix transforming detector reference system coordinates to pixel indexes.

yfs: the y->fs component of the matrix transforming detector reference system coordinates to pixel indexes.

xss: the x->ss component of the matrix transforming detector reference system coordinates to pixel indexes.

yss: the y->ss component of the matrix transforming detector reference system coordinates to pixel indexes.

orig_min_fs: the initial fs index of the location of the panel data in the data block where it is stored.

orig_max_fs: the final fs index of the location of the panel data in the data block where it is stored.

orig_min_ss: the initial ss index of the location of the panel data in the data block where it is stored.

orig_max_ss: the final fs index of the location of the panel data in the data block where it is stored.

w: the width of the panel in pixels.

h: the width of the panel in pixels.

Bad region-related key/value pairs

panel: the name of the panel in which the bad region lies.

min_x: the initial x coordinate of the bad region in the detector reference system.

max_x: the final x coordinate of the bad region in the detector referencesystem.

min_y: the initial y coordinate of the bad region in the detector reference system.

max_y: the final y coordinate of the bad region in the detector reference system.

min_fs: the initial fs index of the location of the bad region in the block where the panel data is stored.

max_fs: the final fs index of the location of the bad region in the block where the panel data is stored.

min_ss: the initial ss index of the location of the bad region in the block where the panel data is stored.

max_ss: the final ss index of the location of the bad region in the block where the panel data is stored.

is_fsss: whether the fs,ss definition of the bad region is the valid one (as opposed to the x,y-based one). If the value corresponding to this key is True, the fs,ss-based definition of the bad region should be considered the valid one. Otherwise, the definition in x,y coordinates must be honored.

The second entry in the tuple is a dictionary storing information related to the beam properties. The following is a brief description of the key/value pairs in the dictionary.

photon_energy: the photon energy of the beam in eV.

photon_energy_from: the location of the photon energy information in a data file, in case the information must be extracted from it.

photon_energy_scale: the scaling factor to be applied to the photon energy, in case the provided energy value is not in eV.

The third entry in the tuple is a string storing the HDF5 path where information about detected Bragg peaks can be found in a data file. If the CrystFEL geometry file does not provide this information, an empty string is returned.

Return type:

Tuple[TypeDetector, TypeBeam, Union[str, None]]

CFELPyUtils named tuples.

This module contains a collection of named tuples used throughout the CFELPyUtils library.

class PixelMaps(x, y, z, r, phi)#

Bases: tuple

Pixel maps that store geometry information.

Parameters:

x (numpy.ndarray) – pixel map for the x coordinate.
y (numpy.ndarray) – pixel map for the y coordinate.
z (numpy.ndarray) – pixel map for the z coordinate.
r (numpy.ndarray) – pixel map storing the distance of each pixel from the center of the reference system.
phi (numpy.ndarray) – pixel map storing the amplitude of the angle between each pixel, the center of the reference system, and the x axis.

phi#: Alias for field number 4

r#: Alias for field number 3

x#: Alias for field number 0

y#: Alias for field number 1

z#: Alias for field number 2