geometry
CrystFEL's geometry utilities.
This module contains functions and classes that manipulate geometry information.
TypeBeam
Bases: TypedDict
A dictionary storing information about the x-ray beam.
Attributes:
| Name | Type | Description |
|---|---|---|
photon_energy |
float
|
The photon energy of the beam in eV. |
photon_energy_from |
str
|
The internal path to the photon energy information in an HDF5 data file, in case the beam energy information is extracted from it. |
photon_energy_scale |
float
|
The scaling factor to be applied to the photon energy, in case the provided energy value is not in eV. |
TypePanel
Bases: TypedDict
A dictionary storing information about a detector panel.
Attributes:
| Name | Type | Description |
|---|---|---|
cnx |
float
|
The x coordinate of the corner of the panel in the detector reference system. |
cny |
float
|
The y coordinate of the corner of the panel in the detector reference system. |
clen |
float
|
The perpendicular distance, as reported by the facility, of the sample interaction point from the corner of the panel. |
clen_from |
str
|
The internal path to the |
coffset |
float
|
The offset to be applied to the |
mask |
str
|
The internal path, in an HDF5 data file, to the mask data for the panel. |
mask_file |
str
|
The name of the HDF5 data file in which the mask data for the panel can be found. |
satmap |
str
|
The internal path, in an HDF5 data file, to the per-pixel saturation map for the panel. |
satmap_file |
str
|
The name of the HDF5 data file in which the per-pixel saturation map for the panel can be found. |
res |
float
|
The size of the pixels that make up the the panel (in pixels per meter). |
badrow |
str
|
The readout direction for the panel, for filtering out clusters of
peaks. The value corresponding to this key must be either |
no_index |
bool
|
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 |
float
|
The number of ADUs per photon for the panel. |
max_adu |
float
|
The ADU value above which a pixel of the panel should be considered unreliable. |
data |
str
|
The internal path, in an HDF5 data file, to the data block where the panel data is stored. |
adu_per_eV |
float
|
The number of ADUs per eV of photon energy for the panel. |
dim_structure |
List[Union[int, str, None]]
|
A description of the internal layout of the data block storing the panel's data. The value corresponding to this key is a list of strings which define the role of each axis in the data block. See the crystfel_geometry man page for a detailed explanation. |
fsx |
float
|
The fs->x component of the matrix used to transform pixel indexes into detector reference system coordinates. |
fsy |
float
|
The fs->y component of the matrix used to transform pixel indexes into detector reference system coordinates. |
fsz |
float
|
The fs->z component of the matrix used to transform pixel indexes into detector reference system coordinates. |
ssx |
float
|
The ss->x component of the matrix used to transform pixel indexes into detector reference system coordinates. |
ssy |
float
|
The ss->y component of the matrix used to transform pixel indexes into detector reference system coordinates. |
ssz |
float
|
The ss->z component of the matrix used to transform pixel indexes into detector reference system coordinates. |
rail_x |
float
|
The x component, in the detector reference system, of the direction of the rail along which the detector moves. |
rail_y |
float
|
The y component, in the detector reference system, of the direction of the rail along which the detector moves. |
rail_z |
float
|
The z component, in the detector reference system, of the direction of the rail along which the detector moves. |
clen_for_centering |
float
|
The perpendicular distance of the origin of the detector reference system from the interaction point, as reported by the facility, |
xfs |
float
|
The x->fs component of the matrix used to transform detector reference system coordinates into pixel indexes. |
yfs |
float
|
The y->fs component of the matrix used to transform detector reference system coordinates into pixel indexes. |
xss |
float
|
The x->ss component of the matrix used to transform detector reference system coordinates into pixel indexes. |
yss |
float
|
The y->ss component of the matrix used to transform detector reference system coordinates into pixel indexes. |
orig_min_fs |
int
|
The initial fs index of the panel data in the data block where it is stored. |
orig_max_fs |
int
|
The final (inclusive) fs index of the panel data in the data block where it is stored. |
orig_min_ss |
int
|
The initial ss index of the panel data in the data block where it is stored. |
orig_max_ss |
int
|
The final (inclusive) fs index of the panel data in the data block where it is stored. |
w |
int
|
The width of the panel in pixels. |
h |
int
|
The height of the panel in pixels. |
TypeBadRegion
Bases: TypedDict
A dictionary storing information about a bad region of a detector.
Attributes:
| Name | Type | Description |
|---|---|---|
panel |
str
|
The name of the panel in which the bad region lies. |
min_x |
float
|
The initial x coordinate of the bad region in the detector reference system. |
max_x |
float
|
The final x coordinate of the bad region in the detector reference system. |
min_y |
float
|
The initial y coordinate of the bad region in the detector reference system. |
max_y |
float
|
The final y coordinate of the bad region in the detector reference system. |
min_fs |
int
|
The initial fs index of the bad region in the block where the panel data is stored. |
max_fs |
int
|
The final (inclusive) fs index of the bad region in the block where the panel data is stored. |
min_ss |
int
|
The initial ss index of the bad region in the block where the panel data is stored. |
max_ss |
int
|
The final (inclusive) ss index of the bad region in the block where the panel data is stored. |
is_fsss |
int
|
Whether the fs,ss definition of the bad region (as opposed to the x,y-based one) should be considered. In the first case, the min_fs, max_fs, min_ss, and max_ss entries in this dictionary will define the bad region. In the second case, the min_x, max_x, min_y, and max_y entries will. If the value corresponding to this key is 1, the fs,ss-based definition will be considered valid. Otherwise, the x,y definition will be used. |
TypeDetector
Bases: TypedDict
A dictionary storing information about a detector.
Attributes:
| Name | Type | Description |
|---|---|---|
panels |
Dict[str, TypePanel]
|
The panels in the detector. The value corresponding to this key is dictionary containing information about the panels that make up the detector. In the dictionary, the keys are the panel names, and the values are TypePanel dictionaries. |
bad |
Dict[str, TypeBadRegion]
|
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 bad region names, and the values are TypeBadRegion dictionaries. |
mask_bad |
int
|
The value used in a bad pixel mask to label a pixel as bad. |
mask_good |
int
|
The value used in a bad pixel mask to label a pixel as good. |
rigid_groups |
Dict[str, List[str]]
|
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 dictionary, the keys are names of rigid groups and the values are lists storing the names of the panels belonging to each group. |
rigid_group_collections |
Dict[str, List[str]]
|
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 dictionary, the keys are names of rigid group collections and the values are lists storing the names of the rigid groups belonging to the each collection. |
furthest_out_panel |
str
|
The name of the panel which contains the pixel that is the furthest away from the center of the detector reference system. |
furthest_out_fs |
float
|
The fs coordinate, within its panel, of the pixel that is the furthest away from the center of the detector reference system. |
furthest_out_ss |
float
|
The ss coordinate, within its panel, of the pixel that is the furthest away from the center of the detector reference system. |
furthest_in_panel |
str
|
The name of the panel which contains the closest pixel to the center of the detector reference system. |
furthest_in_fs |
float
|
The fs coordinate, within its panel, of the closest pixel to the center of the detector reference system. |
furthest_in_ss |
float
|
The ss coordinate, within its panel, of the closest pixel to the center of the detector reference system. |
TypeDetectorLayoutInformation
Bases: TypedDict
Detector layout information for the peakfinder8 algorithm.
This typed dictionary stores information about the internal data layout of a
detector data frame (number and size of ASICs, etc.). The information
is needed by the
Peakfinder8PeakDetection
algorithm, and is usually retrieved via the
get_layout_info
function.
Attributes:
| Name | Type | Description |
|---|---|---|
asic_nx |
int
|
The fs size in pixels of each detector panel in the data frame. |
asic_ny |
int
|
The ss size in pixels of each detector panel in the data frame. |
nasics_x |
int
|
The number of detector panels along the fs axis of the data frame. |
nasics_y |
int
|
The number of detector panels along the ss axis of the data frame. |
TypePixelMaps
Bases: TypedDict
A dictionary storing a set of pixel maps
This dictionary stores a set of look-up pixels maps. Each map stores, for each pixel in a detector data frame, the value of a specific coordinate. All coordinates in this set of maps are assumed to be relative to the detector's reference system.
Attributes:
| Name | Type | Description |
|---|---|---|
x |
NDArray[numpy.float_]
|
A pixel map for the x coordinate. |
y |
NDArray[numpy.float_]
|
A pixel map for the y coordinate. |
z |
NDArray[numpy.float_]
|
A pixel map for the z coordinate. |
radius |
NDArray[numpy.float_]
|
A pixel map storing the distance of each pixel from the center of the detector reference system. |
phi |
NDArray[numpy.float_]
|
A pixel map storing, for each pixel, the amplitude of the angle drawn by the pixel, the center of the detector reference system, and the x axis. |
TypeVisualizationPixelMaps
Bases: TypedDict
TODO: Fix documentation
A dictionary storing a set of pixel maps used for visualization.
This dictionary stores a set of look-up pixels maps. Each map stores, for each pixel in a detector data frame, the value of a specific coordinate. This set of pixel maps is supposed to be used for visualization: all coordinates are assumed to refer to a cartesian reference system mapped on a 2D array storing pixel information, with origin in the top left corner of the array
Attributes:
| Name | Type | Description |
|---|---|---|
x |
NDArray[numpy.int_]
|
A pixel map for the x coordinate. |
y |
NDArray[numpy.int_]
|
A pixel map for the y coordinate. |
GeometryInformation
See documentation for the __init__ function.
__init__(*, geometry_description, geometry_format)
Detector geometry information.
This class stores the all the information describing the geometry of an area detector. It is initialized with a block of text containing the description of the geometry of thr detector (usually the content of a geometry file), and with a string specifying the format of the provided information.
Once the class has been initialized, methods can be invoked to recover information about the geometry: lookup-pixel maps, detector's pixel size, etc.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry_description |
List[str]
|
a block of text describing the detector's geometry |
required |
geometry_format |
str
|
a string describing the format of the provided geometry description. Currently the following formats are supported:
|
required |
Raises:
| Type | Description |
|---|---|
OmGeometryError
|
Raised if the format of the provided geometry information is not supported. |
from_file(*, geometry_filename, geometry_format=None)
classmethod
Reads geometry description from file.
This class method initializes the GeometryInformation class from a file, rather than from a block of text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geometry_filename |
str
|
the relative or absolute path to file containing the description of the geometry of an area detector |
required |
geometry_format |
Union[str, None]
|
a string describing the format of the geometry description. Currently the following formats are supported:
|
None
|
Raises:
| Type | Description |
|---|---|
OmGeometryError
|
Raised if the format of the geometry file cannot be inferred from the file's extension. |
get_pixel_maps()
Retrieves pixel maps.
This function retrieves look-up pixel maps storing coordinate information for each pixel of a detector data frame.
Returns:
| Type | Description |
|---|---|
TypePixelMaps
|
The set of look-up pixel maps. |
get_layout_info()
Retrieves detector layout information for the peakfinder8 algorithm.
This function retrieves information about the internal layout of a detector data frame (number and size of ASICs, etc.). This information is needed by the peakfinder8 peak detection algorithm.
Returns:
| Type | Description |
|---|---|
TypeDetectorLayoutInformation
|
Internal layout of a detector data frame. |
get_detector_distance_offset()
Retrieves detector distance offset information.
This function retrieves the offset that should be added to the nominal detector distance provided by the facility to obtain the real detector distance (i.e., the distance between the sample interaction point and the area detector where data is recorded. This value is often stored together with the geometry information, but if it is not available, the function returns None.
Returns:
| Type | Description |
|---|---|
float
|
The detector distance offset in meters, or None if the information is not |
float
|
available. |
get_pixel_size()
Retrieves the size of an area detector pixel.
This function retrieves information about the size of each pixel making up an area detector. All pixels in the detector are assumed to have the same size, and have a square shape. The value returned by this function describes the length of the side of each pixel.
Returns:
| Type | Description |
|---|---|
float
|
Length of the pixel's side in meters. |
DataVisualizer
See documentation for the __init__ function.
__init__(*, pixel_maps)
Visualization of detector data with geometry applied.
This class stores all the information needed to display detector data with geometry applied to it. Once the class has been initialized, it can be invoked to retrieve visualization look-up pixel maps and other information needed to display the data. A detector frame is assumed to be visualized in the form of a 2D image showing an approximate representation of the physical layout of the detector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pixel_maps |
TypePixelMaps
|
A set of look-up pixel maps storing coordinate information for each pixel in detector data frame. |
required |
get_pixel_maps()
Retrieves pixel maps.
This function just returns the pixel maps that were used to initialize the class.
Returns:
| Type | Description |
|---|---|
TypePixelMaps
|
A set of look-up pixel maps storing coordinate information for each pixel |
TypePixelMaps
|
in detector data frame. |
get_visualization_pixel_maps()
Retrieves visualization pixel maps.
This function retrieves a set of visualization look-up pixel maps. These pixel maps store the information needed to display a detector data frame. with geometry information applied to it, in the form of a 2D image.
Returns:
| Type | Description |
|---|---|
TypeVisualizationPixelMaps
|
A set of look-up pixel maps storing the information needed to display a |
TypeVisualizationPixelMaps
|
detector data frame as a 2D image. |
get_min_array_shape_for_visualization()
Retrieves the minimum shape of an array that can store a detector frame image.
Computes the minimum size of an array that can hold the pixel information for the image representation of a detector data frame. The size of the array is enough to include the full representation of the data frame with geometry applied. The size of the array also calculated assuming that the center of the detector's reference system is kept at the center of the detector image.
Returns:
| Type | Description |
|---|---|
int
|
The minimum shape, in numpy format, of an array storing the image |
int
|
representation of a detector data frame. |
visualize_data(*, data, array_for_visualization=None)
Applies geometry information to a detector data frame.
This function applies the geometry information stored by the class to a provided detector data frame. It returns a 2D array storing the pixel information of an image representing the data frame with geometry applied.
If a pre-existing visualization array is provided, with exactly the shape returned by the get_min_array_shape_for_visualization function, this function can used it to store the pixel information. Otherwise the function creates a new array with the appropriate shape.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
Union[NDArray[numpy.int_], NDArray[numpy.float_]]
|
The detector data frame on which geometry should be applied. |
required |
array_for_visualization |
Union[NDArray[numpy.int_], NDArray[numpy.float_], None]
|
Either a pre-existing array of the correct size, in which case the array is used to store the pixel information of the detector data frame image, or None. If the value of this argument is None, an array with the appropriate shape is generated by the function. Optional. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
Union[NDArray[numpy.int_], NDArray[numpy.float_]]
|
An array containing pixel information for the image representation of the |
Union[NDArray[numpy.int_], NDArray[numpy.float_]]
|
provided detector data frame. |
Raises:
| Type | Description |
|---|---|
OmWrongArrayShape
|
Raised if the provided array has the wrong shape and cannot be used to store the pixel information. |