SpaceConverter#

class cdiutils.SpaceConverter(geometry, det_calib_params=None, energy=None, roi=None, shape=None, q_lab_shift=None, q_lab_matrix=None, direct_lab_matrix=None, direct_lab_voxel_size=None)[source]#

Bases: object

BCDI-critical class for coordinate system transformations.

Handles conversions between detector, reciprocal lab (q-space), and direct lab frames using xrayutilities. Essential for BCDI strain calculations, where accurate orthogonalisation preserves physical displacement fields.

The class manages three coordinate systems: - Detector frame: raw (i,j,k) pixel indices (non-orthogonal) - Reciprocal lab: orthogonal q-space (units: Angstroms-1) - Direct lab: orthogonal real-space (units: nm)

See also

user_guide/coordinate_systems.rst for CXI/XU conventions.

Coordinate Transformations

Utility Methods

__init__(geometry, det_calib_params=None, energy=None, roi=None, shape=None, q_lab_shift=None, q_lab_matrix=None, direct_lab_matrix=None, direct_lab_voxel_size=None)[source]#

Initialise the space converter.

Parameters:

  • geometry (Geometry) – beamline geometry (goniometer circles, detector orientation).

  • det_calib_params (dict) – detector calibration (cch1, cch2, distance, pwidth1, pwidth2) in pixels and mm. Critical for accurate q-space mapping.

  • energy (float) – X-ray energy in eV.

  • roi (list) – region of interest [row_start, row_end, col_start, col_end] applied to detector data.

  • shape (tuple) – data shape (nz, ny, nx) in detector frame.

  • q_lab_shift (tuple) – shift applied to centre Bragg peak at origin in reciprocal space (Angstroms-1).

  • q_lab_matrix (ndarray) – transformation matrix for q-space interpolation (internal use).

  • direct_lab_matrix (ndarray) – transformation matrix for direct-space interpolation (internal use).

  • direct_lab_voxel_size (tuple) – voxel size in direct lab frame (nm).

property direct_lab_voxel_size#
property shape#
to_dict()[source]#

Serialise converter state to dictionary.

to_file(dump_path)[source]#

Save converter configuration to HDF5 file.

Preserves all transformation matrices and calibration parameters, allowing reconstruction of converter state without recomputing q-space transitions (expensive operation).

Parameters:

dump_path (str) – output HDF5 file path (.h5 extension added if missing).

classmethod from_file(path)[source]#

Load converter from HDF5 file.

Factory method that reconstructs SpaceConverter instance with all transformation matrices and calibration parameters, avoiding expensive recomputation of q-space transitions.

Parameters:

path (str) – input HDF5 file path.

Returns:

SpaceConverter instance with restored state.

Return type:

SpaceConverter

init_q_space(sample_outofplane_angle, sample_inplane_angle, detector_outofplane_angle, detector_inplane_angle, det_calib_params=None, roi=None)[source]#

Initialise q-space mapping using xrayutilities.

Computes q-space coordinates for each detector pixel given goniometer angles. This is the foundation for all BCDI coordinate transformations. Requires accurate detector calibration (cch1, cch2, distance, pixel sizes) to preserve physical strain calculations.

Parameters:

  • sample_outofplane_angle (float | ndarray) – out-of-plane rotation (e.g. om, theta, eta) in degrees. Can be 1D array (rocking curve scan).

  • sample_inplane_angle (float | ndarray) – in-plane rotation (e.g. phi, chi, gamma) in degrees.

  • detector_outofplane_angle (float | ndarray) – detector out-of-plane angle (e.g. delta, tth) in degrees.

  • detector_inplane_angle (float | ndarray) – detector in-plane angle (e.g. nu, gamma) in degrees.

  • det_calib_params (dict) – detector calibration dict with keys ‘cch1’, ‘cch2’, ‘distance’, ‘pwidth1’, ‘pwidth2’.

  • roi (list) – region of interest [row_start, row_end, col_start, col_end].

index_det_to_q_lab(ijk)[source]#

Convert detector index to q-space coordinates.

Parameters:

ijk (tuple) – detector pixel index (i, j, k).

Returns:

(qx, qy, qz) coordinates in Å⁻¹.

Return type:

tuple

index_cropped_det_to_q_lab(ijk)[source]#

Convert cropped detector index to q-space coordinates.

index_det_to_index_of_q_lab(ijk, interpolation_method='cdiutils')[source]#

Transition an index from the full detector frame to the index-of-q lab frame

index_cropped_det_to_index_of_q_lab(ijk)[source]#

Transition an index from the cropped detector frame to the index-of-q lab frame

static dspacing(q_lab_coordinates)[source]#

Compute d-spacing from q-space coordinates.

d-spacing is the lattice plane separation: d = 2π / |q|.

Parameters:

q_lab_coordinates (ndarray | list | tuple) – (qx, qy, qz) in Å⁻¹.

Returns:

d-spacing in Ångströms.

Return type:

float

classmethod lattice_parameter(q_lab_coordinates, hkl)[source]#

Compute lattice parameter from Bragg peak position.

Uses formula: a = d * sqrt(h² + k² + l²) for cubic crystals.

Parameters:

  • q_lab_coordinates (ndarray | list | tuple) – (qx, qy, qz) at Bragg peak in Å⁻¹.

  • hkl (ndarray | list | tuple) – Miller indices of the reflection.

Returns:

Lattice parameter in Ångströms.

Return type:

float

static do_transition(ijk, transition_matrix)[source]#

Transform a (i, j, k) tuple into the corresponding (qx, qy, qz) values based the transition matrix

init_interpolator(direct_lab_voxel_size=None, space='direct', shift_voxel=None, verbose=False)[source]#

Initialise interpolators for orthogonalisation.

Prepares linear transformation matrices for converting non-orthogonal detector data to orthogonal grids. For BCDI strain analysis, accurate voxel size calibration is essential to preserve displacement field magnitudes.

Parameters:

  • direct_lab_voxel_size (tuple | float) – target voxel size in direct space (nm). If None, auto-computed from reciprocal extent. Can be scalar (isotropic) or 3-tuple (anisotropic).

  • space (str) – which interpolator(s) to initialise: ‘reciprocal’ (q-space), ‘direct’ (real-space), or ‘both’.

  • shift_voxel (tuple) – Bragg peak centre in detector frame (i,j,k). Used to centre reciprocal space at (0,0,0). Default: centre of array.

  • verbose (bool) – print auto-computed voxel size.

orthogonalise_to_q_lab(data, method='cdiutils', shift_voxel=None)[source]#

Orthogonalise detector data to reciprocal lab frame (q-space).

BCDI-critical transformation that converts non-orthogonal detector pixels to regular reciprocal grid. Choice of method affects interpolation quality and speed.

Parameters:

  • data (ndarray) – 3D detector data (nz, ny, nx) with rocking curve along first axis.

  • method (str) – ‘cdiutils’ (fast linear interpolation) or ‘xu’ (xrayutilities.FuzzyGridder3D, slower but handles irregular grids better).

  • shift_voxel (tuple) – Bragg peak centre (i,j,k) for centring at origin. Default: centre of array.

Returns:

Orthogonalised 3D array in q lab frame.

Return type:

ndarray

orthogonalise_to_direct_lab(direct_space_data, direct_lab_voxel_size=None)[source]#

Orthogonalise reconstructed object to direct lab frame.

Transformation that converts BCDI reconstruction (in non-orthogonal detector frame) to orthogonal real-space. Essential for accurate strain calculations, where voxel size determines displacement field calibration.

Parameters:

  • direct_space_data (ndarray) – 3D complex-valued reconstruction (amplitude * exp(i*phase)).

  • direct_lab_voxel_size (tuple | ndarray | list | float) – target voxel size (nm). If provided, reinitialises interpolator. Can be scalar or 3-tuple.

Returns:

Orthogonalised 3D complex array in direct lab frame.

Return type:

ndarray

get_transformation_matrix(shift_voxel=None)[source]#

Compute transformation matrix for detector to q-space mapping.

Returns linear transformation converting (i,j,k) detector indices to (qx,qy,qz) coordinates.

Parameters:

shift_voxel (tuple | None) – Bragg peak centre (i,j,k). Default: array centre.

Returns:

3x3 transformation matrix.

Return type:

ndarray

get_q_space_transitions(arrangement='list')[source]#

Get q-space coordinates from xrayutilities mapping.

Parameters:

arrangement (str) – ‘list’ (three 1D arrays) or ‘cubinates’ (4D array with shape (nz,ny,nx,3)).

Returns:

Q-space coordinate grid.

get_xu_q_lab_regular_grid(arrangement='list')[source]#

Get regular q lab grid from xrayutilities.FuzzyGridder3D.

Only available after calling orthogonalise_to_q_lab with method=’xu’.

Parameters:

arrangement (str) – ‘list’ (three 1D axes) or ‘cubinates’ (4D meshgrid).

Returns:

Regular q-space grid.

get_q_lab_regular_grid(arrangement='list')[source]#

Get regular q lab grid from cdiutils interpolator.

Only available after init_interpolator with space=’reciprocal’ or ‘both’.

Parameters:

arrangement (str) – ‘list’ (three 1D axes) or ‘cubinates’ (3D meshgrid with shape (nz,ny,nx,3)).

Returns:

Regular q-space grid in Angstrom-1.

get_direct_lab_regular_grid(arrangement='list')[source]#

Get regular direct lab grid from cdiutils interpolator.

Only available after init_interpolator with space=’direct’ or ‘both’.

Parameters:

arrangement (str) – ‘list’ (three 1D axes) or ‘cubinates’ (3D meshgrid).

Returns:

Regular real-space grid in nm.

get_q_norm_histogram(q_lab_data)[source]#

Compute radial profile data for q-space histogram.

Calculates |q| magnitude for each voxel and returns sorted (|q|, intensity) pairs for 1D radial averaging.

Parameters:

q_lab_data (ndarray) – 3D intensity array in orthogonalised q lab frame.

Returns:

Tuple of (sorted_q_norms, sorted_intensities) as 1D arrays.

Return type:

tuple[ndarray, ndarray]

support_transfer(support, voxel_size, convert_to_xu=False)[source]#

Transfer support from direct lab to reconstruction frame.

Interpolates support defined in orthogonal direct lab frame (e.g. from previous analysis) onto non-orthogonal reconstruction frame. Used to initialise BCDI phase retrieval with prior knowledge.

Parameters:

  • support (ndarray) – binary mask in direct lab frame.

  • voxel_size (tuple) – voxel size of input support in nm.

  • convert_to_xu (bool) – convert support from CXI to XU convention before interpolation.

Returns:

Support array in detector frame.

Return type:

ndarray

static run_detector_calibration(detector_calibration_frames, detector_outofplane_angle, detector_inplane_angle, energy, xu_detector_circles, pixel_size_x=5.5e-05, pixel_size_y=5.5e-05, sdd_estimate=None, show=True, verbose=True)[source]#

Calibrate detector parameters using xrayutilities (BCDI-critical).

Determines detector calibration (cch1, cch2, distance, tilt, etc.) from direct beam scans. Critical for accurate q-space mapping in BCDI strain calculations.

Parameters:

  • detector_calibration_frames (ndarray) – 3D array of direct beam images (nangles, ny, nx).

  • detector_outofplane_angle (float) – out-of-plane detector angles during scan (degrees).

  • detector_inplane_angle (float) – in-plane detector angles during scan (degrees).

  • energy (float) – X-ray energy in eV.

  • xu_detector_circles (list) – detector circle names in XU convention (e.g. [‘z-’, ‘y-’] for ID01).

  • pixel_size_x (float) – detector pixel size along x in metres (default: 55 µm for Eiger).

  • pixel_size_y (float) – detector pixel size along y in metres (default: 55 µm).

  • sdd_estimate (float) – initial sample-detector distance in metres. If None, auto-estimated from beam motion.

  • show (bool) – plot calibration diagnostic plots.

  • verbose (bool) – print calibration parameters.

Returns:

cch1, cch2, pwidth1, pwidth2, distance, tiltazimuth, tilt, detrot.

Return type:

Dictionary with keys

Example

>>> # ID01 detector calibration
>>> params = converter.run_detector_calibration(
...     calibration_scan_data,
...     delta_angles,
...     nu_angles,
...     energy=9000,
...     xu_detector_circles=['z-', 'y-']
... )

See Also#

Geometry : Beamline geometry configuration BcdiPipeline : Uses SpaceConverter for coordinate transformations