SphericalIndexer#

class de_ebsd.index.spherical.SphericalIndexer(master, detector, bandwidth=53, device=None, energy_kev=None)[source]#

Bases: object

Index EBSD patterns against a master pattern by spherical cross-correlation.

Build once (the master spectrum is precomputed here), then call index() on a single pattern or a stack.

Parameters:

master: A de_ebsd.sim.MasterPattern, sampled via master.sample.
detector: EBSDDetector geometry, inverted to back-project each pattern to the sphere.
bandwidth: Band limit L, the accuracy/speed knob: the SOFT grid step is 360 / (2L + 2) degrees. Cost grows ~``O(L^4)`` in both time and memory, since wigner_d() materializes a (N, L+1, 2L+1, 2L+1) tensor.
device: Resolved as explicit argument > master.device > CPU.
energy_kev: Energy bin to sample the master at; None (default) selects the highest.

Attributes:

shtSphericalHarmonicTransform: The shared transform plan; master and patterns both go through it.
a_lm, a2_lmtorch.Tensor: Spectra of the master and of M^2, complex, shape ((L+1)**2,).

Methods

`index`	Index one pattern or a stack, returning orix orientations and quality.
`index_scan`	Index a whole scan and assemble it into an orix `CrystalMap`.
`refine`	Gradient-refine indexed orientations (and optionally the pattern center).

index(patterns, normalize=True, return_surface=False)[source]#

Index one pattern or a stack, returning orix orientations and quality.

Parameters:

patterns: A detector image (H, W) or stack (Np, H, W), numpy or torch.
normalize: Divide out the master’s local FOV norm (default), removing the bias toward orientations that place bright master regions in the field of view. False keeps the raw masked cross-correlation, unbiased only for near-uniform-norm masters.
return_surface: Also return the SO(3) score surface that was arg-maxed, as a third element. It feeds de_ebsd.viz.maps.show_correlation() directly.

Returns:

rotationsorix.quaternion.Rotation: Best-matching sample orientation per pattern, length Np.
qualitytorch.Tensor: Peak score per pattern. Normalized, this is roughly in [-1, 1] and comparable across patterns; unnormalized it has arbitrary scale.
surfacetorch.Tensor: Only when return_surface: shape (Np, N, N, N), N = 2L + 2, on the (alpha, beta, gamma) grid. Detached.

index_scan(patterns, shape=None, step=1.0, phase=None, batch_size=None, normalize=True, refine=False, refine_iters=100, refine_lr=0.02)[source]#

Index a whole scan and assemble it into an orix CrystalMap.

Parameters:

patterns: Either (rows, cols, H, W), from which the scan grid is inferred, or a flat row-major (N, H, W), which requires shape.
shape: (rows, cols) of the scan. Cross-checked against 4-D input.
step: Scan step size, written onto the map’s x/y.
phase: An orix Phase or a de_ebsd Crystal. If None, derived from master.metadata["crystal"].
batch_size: Patterns per mini-batch (default 64). The SO(3) surface is (batch_size, N, N, N), which dominates memory at production bandwidth. Results are identical to a single batch.
refine: Gradient-refine each mini-batch before assembly, making prop["quality"] the refined NCC. Orientation only – a scan shares one detector geometry, and joint pattern-center fitting over a whole scan is not done here.
refine_iters, refine_lr: Adam iterations and rotation learning rate used when refine.

Returns:

orix.crystal_map.CrystalMap: One orientation + prop["quality"] per scan point, single phase.

refine(patterns, rotations=None, pattern_center=None, refine_pattern_center=False, n_iterations=100, learning_rate=0.02, pattern_center_learning_rate=None, keep_best=True, return_history=False)[source]#

Gradient-refine indexed orientations (and optionally the pattern center).

Wraps de_ebsd.index.refine.orientation.refine_orientation() with this indexer’s master, detector, device and SHT quadrature directions, so refinement scores over the same grid the coarse index used. With rotations=None the seeds come from index(), taking raw patterns straight to sharpened orientations.

pattern_center defaults to detector.pattern_center; the remaining arguments pass through. Returns (rotation, score), with pattern_center appended when refine_pattern_center and history when return_history.