pyextal.roi¶

Region of Interest (ROI) Management.

This module provides classes for defining, managing, and sampling Regions of Interest (ROIs) from experimental and simulated diffraction patterns. It includes base classes and specific implementations for Convergent Beam Electron Diffraction (CBED) and Large Angle Rocking Beam Electron Diffraction (LARBED).

The core functionalities include: - Defining ROIs with geometric shapes. - Generating sampling grids for both simulation and experiment. - Handling coordinate transformations (rotation, scaling, shifting). - Creating interpolation functions for experimental data. - Extracting intensity templates from experimental patterns.

Classes¶

`ROITYPE`	Enumeration for the type of Region of Interest.
`BaseROI`	Base class for defining and managing a Region of Interest (ROI).
`CBEDROI`	A Region of Interest (ROI) class specifically for CBED patterns.
`LARBEDROI`	A Region of Interest (ROI) class specifically for LARBED patterns.

Functions¶

`pix2Tilt`(param, pixsiz)	Converts a pixel displacement to a tilt vector in simulation units.
`split_array_by_lengths`(A, B[, axis])	Splits an array into subarrays of specified lengths.
`rotation`(vec, theta)	Rotates a 2D vector by a given angle.

Module Contents¶

class pyextal.roi.ROITYPE(*args, **kwds)¶

Bases: enum.Enum

Enumeration for the type of Region of Interest.

BASE = 0¶

CBED = 1¶

LARBED = 2¶

class pyextal.roi.BaseROI(dinfo, rotation, gx, gInclude)¶

Base class for defining and managing a Region of Interest (ROI).

This class handles the common functionalities for defining sampling grids for both simulation and experiment, storing experimental intensity data, and managing coordinate transformations. It is intended to be subclassed for specific diffraction techniques like CBED or LARBED.

dinfo¶

The main diffraction information object.

Type:: BaseDiffractionInfo

dp¶

The experimental diffraction pattern.

Type:: np.ndarray

rotation¶

The rotation angle in degrees.

Type:: float

gl¶

The geometric scaling factor.

Type:: float

gInclude¶

A list of Miller indices (h, k, l) for the reflections to be included in the ROI.

Type:: list

gx¶

The vector defining the primary (horizontal) systematic row direction.

Type:: np.ndarray

allshift¶

A global shift applied to all ROIs.

Type:: np.ndarray

indices¶

An array of indices mapping the gInclude reflections to the output of the Bloch wave simulation.

Type:: np.ndarray

pixsiz¶

The pixel size in the simulation space.

Type:: float

initPixsiz¶

The initial pixel size, stored for scaling calculations.

Type:: float

roitype¶

dinfo¶

dp¶

_rotation¶

_gl¶

gInclude¶

gx¶

allshift¶

__str__()¶: Returns a string representation of the ROI object.

abstractmethod initialize()¶

Initializes the Bloch simulation and calculates initial pixel size.

This method sets up the fortran module for the Bloch simulation, stores the resulting parameters in the dinfo object, and calculates the initial pixel size based on the simulation geometry. It should be overridden by subclasses to add technique-specific initializations.

matchIndex()¶: Matches the included reflections to the simulation output indices.

abstractmethod createInterp()¶

Creates an interpolation function for the experimental diffraction pattern.

This method must be implemented by subclasses to handle the specific data format of the diffraction experiment (e.g., a single 2D pattern for CBED, or a stack of 2D patterns for LARBED).

selectROI(regions, mask=None, padding=0)¶

Selects and configures the regions of interest for refinement.

This method defines the geometric regions to be sampled, generates the corresponding sampling grids, and sets up masks to include or exclude specific disks within each region.

The region is defined by three corner points (1, 2, 3) and the number of sampling points along the vectors 1->2 and 1->3.

1-------(n_12 points)-------2
|
(n_13 points)
|
3

Parameters:

regions (np.ndarray) – An array of shape (n_regions, 4, 2) where each row defines a region. The format is [[x1,y1], [x2,y2], [x3,y3], [n_12, n_13]]. Coordinates are relative to the diffraction pattern center.
mask (np.ndarray, optional) – A boolean array of shape (n_regions, n_disks) where a value of 1 includes the disk in the refinement and 0 excludes it. If None, all disks in all regions are included. Defaults to None.
padding (int, optional) – Number of pixels to pad around the ROI, used for probe convolution. Defaults to 0.

updateSimGrid()¶

Updates the simulation grid based on the current geometry.

This method calculates the required tilt angles for each point in the sampling grid and prepares the simGrid attribute for the Bloch wave simulation.

abstractmethod updateExpGrid()¶

Updates the experimental sampling grid and extracts intensity templates.

This method must be implemented by subclasses. It should calculate the coordinates for sampling the experimental data based on the current rotation, scaling, and shift parameters, and then use the interpolation function to extract the intensity values (templates).

abstractmethod transformDP(coordinates)¶

Transforms coordinates from the ROI frame to the original DP frame.

This method must be implemented by subclasses. It should account for the rotation and shifts applied to the diffraction pattern during preprocessing.

Parameters:: coordinates (np.ndarray) – An array of (row, col) coordinates in the (potentially rotated and shifted) ROI frame.

calculatePixelSize()¶: Calculates the pixel size based on the geometric scaling factor gl.

generateGrid(regions)¶

Generates a sampling grid from a set of region definitions.

For each region, it creates a grid of points by linearly interpolating between the corner points.

Parameters:: regions (np.ndarray) – The region definitions, as described in selectROI.
Returns:: A concatenated array of (row, col) coordinates for all sampling points in all regions.
Return type:: np.ndarray

property gl¶

The geometric scaling factor. Recalculates grids upon modification.

Type:: float

property rotation¶

The rotation angle in degrees. Recalculates grids upon modification.

Type:: float

property templates¶

The extracted experimental intensity templates for the ROIs.

Type:: np.ndarray

__add__(other)¶: Adds two ROI objects together. Not yet implemented.

class pyextal.roi.CBEDROI(dinfo, rotation, gx, gInclude, dpCenter, dpSize, gy=None)¶

Bases: BaseROI

A Region of Interest (ROI) class specifically for CBED patterns.

This class extends BaseROI to handle the specific geometry and data associated with a single, large Convergent Beam Electron Diffraction pattern. It manages the alignment of the experimental pattern to a simulation and defines the positions of diffraction disks based on crystallographic vectors.

dpCenter¶

The (row, col) coordinates of the (000) disk center.

Type:: tuple

dpSize¶

The (rows, cols) size of the simulation output.

Type:: tuple

diskshift¶

An array of (row, col) shifts applied individually to each diffraction disk.

Type:: np.ndarray

gCoff¶

A list of tuples containing the projection coefficients of each gInclude vector onto the gx and gy axes.

Type:: list

roitype¶

dpCenter¶

dpSize¶

diskshift¶

gCoff = []¶

initialize()¶

Pre-processes the CBED pattern and initializes the simulation.

This method performs the following steps: 1. Rotates the experimental DP to align the systematic row horizontally. 2. Runs an initial Bloch simulation to get the geometry. 3. Aligns the experimental DP to the simulated DP using phase cross-correlation on their Sobel-filtered edge maps. 4. Crops the aligned experimental DP to match the simulation size. 5. Calculates the initial pixel size.

createInterp()¶: Creates a 2D interpolation function for the entire CBED pattern.

displayROI()¶

Displays the pre-processed CBED pattern and the selected ROIs.

Overlays the defined ROI polygons on the horizontally-aligned experimental diffraction pattern.

transformDP(coordinates)¶

Transforms ROI coordinates back to the original, un-rotated DP frame.

This method calculates the inverse transformation, accounting for the rotation and phase-correlation shift applied during initialization.

Parameters:: coordinates (np.ndarray) – An array of (row, col) coordinates in the horizontally-aligned ROI frame.
Returns:: The corresponding (row, col) coordinates in the original diffraction pattern.
Return type:: np.ndarray

updateExpGrid()¶

Samples the experimental DP to generate intensity templates.

This method calculates the final sampling coordinates for each disk by applying the geometric scaling (gl), rotation, global shift (allshift), and individual disk shifts (diskshift). It then uses the interpolation function to extract the intensity values.

setTilt0(tilt, refPoint)¶

Sets the central tilt of the simulation based on a reference point.

This allows re-centering the simulation’s tilt space (tilt0) to a specific feature (e.g., a zone axis) identified at refPoint in the experimental pattern.

Parameters:

tilt (np.ndarray) – The new tilt vector to be set as the center.
refPoint (tuple) – The (row, col) coordinates in the horizontal DP that correspond to the new tilt.

kt2pixel(kt)¶

Converts a tangential tilt vector (kt) to pixel coordinates.

Parameters:: kt (np.ndarray) – A tilt vector in the simulation’s tangential plane.
Returns:: The corresponding (row, col) pixel coordinates relative to the dpCenter in the horizontally-aligned DP.
Return type:: np.ndarray

pixel2exp(pixel)¶

Converts pixel coordinates to experimental coordinates.

Parameters:: pixel (np.ndarray) – (row, col) pixel coordinates in the horizontal diffraction pattern, relative to dpCenter.
Returns:: The corresponding coordinates in the original experimental diffraction pattern space.
Return type:: np.ndarray

getSampling()¶: Returns the raw sampling coordinates for debugging purposes.

class pyextal.roi.LARBEDROI(dinfo, rotation, gx, gInclude, probe=None)¶

Bases: BaseROI

A Region of Interest (ROI) class specifically for LARBED patterns.

This class extends BaseROI to handle LARBED data, which consists of a stack of images, one for each diffraction disk. It creates a separate

2D

interpolation function for each disk’s image and its corresponding variance map.

Attributes:

diskshift (np.ndarray): An array of (row, col) shifts applied individually: to each diffraction disk.
indices (np.ndarray): An array of indices mapping the gInclude reflections: to the output of the Bloch wave simulation.
varianceMaps (np.ndarray): A stack of variance maps corresponding to the: diffraction pattern images.

interp (list): A list of interpolation functions, one for each disk image. varInterp (list): A list of interpolation functions for the variance maps.

roitype¶

diskshift¶

indices = []¶

initialize()¶: Initializes the simulation parameters from the LARBED .dat file.

createInterp()¶: Creates interpolation functions for each disk image and variance map.

matchIndex()¶

Matches gInclude reflections to simulation and experimental data indices.

This method maps the desired gInclude reflections to both the output order of the Bloch simulation (self.indices) and the order of the images in the experimental data stack (dpIndex), then reorders the dp and varianceMaps arrays accordingly.

displayROI()¶: Displays the LARBED disk images and the selected ROIs.

transformDP(coordinates)¶

Transforms ROI coordinates back to the original, un-rotated DP frame.

Parameters:

coordinates (np.ndarray) – An array of (row, col) coordinates in the
frame. (ROI)

Returns:

The corresponding (row, col) coordinates in the original diffraction pattern image frame.

Return type:

np.ndarray

updateExpGrid()¶: Samples the LARBED images to generate intensity and variance templates.

updateSimGrid()¶

Updates the simulation grid based on the LARBED geometry.

For LARBED, the center of the rocking pattern is assumed to be the center of the image. This method calculates the tilt vectors corresponding to each pixel in the ROI relative to this center.

setTilt0(tilt, refPoint)¶

Sets the central tilt of the simulation based on a reference point.

Parameters:

tilt (np.ndarray) – The new tilt vector to be set as the center.
refPoint (tuple) – The (row, col) coordinates in the LARBED image
tilt. (that correspond to the new)

getSampling()¶: Returns the raw sampling coordinates for debugging purposes.

pyextal.roi.pix2Tilt(param, pixsiz)¶

Converts a pixel displacement to a tilt vector in simulation units.

Parameters:

param (SimParams) – The Bloch simulation parameters object, containing
gh. (the reciprocal lattice vectors gg and)
pixsiz (float) – The size of a pixel in reciprocal space units (e.g., Å⁻¹).

Returns:

A tuple containing the tilt vectors corresponding to a one-pixel displacement along the x and y axes.

Return type:

tuple[np.ndarray, np.ndarray]

pyextal.roi.split_array_by_lengths(A, B, axis=0)¶

Splits an array into subarrays of specified lengths.

Parameters:

A (np.ndarray) – The array to be split.
B (list[int]) – A list of lengths for each subarray. The sum of lengths
axis. (in B must equal the size of A along the specified)
axis (int, optional) – The axis along which to split the array.
0. (Defaults to)

Returns:

A list of subarrays.

Return type:

list[np.ndarray]

Raises:

ValueError – If the sum of lengths in B does not match the array size.

pyextal.roi.rotation(vec, theta)¶

Rotates a 2D vector by a given angle.

Parameters:

vec (np.ndarray) – The 2D vector to rotate.
theta (float) – The rotation angle in radians.

Returns:

The rotated 2D vector.

Return type:

np.ndarray