DictionaryIndexer#

class de_ebsd.index.dictionary.DictionaryIndexer(master, detector, point_group=None, resolution=3.0, device=None, dtype=None, energy_kev=None, match_binning=1)[source]#

Bases: object

Index EBSD patterns against a fundamental-zone dictionary by matmul.

The dictionary – the master projected at every fundamental-zone orientation, normalized – is built once in __init__(); index() then scores a whole stack with one matmul. The grid is coarse by design, so the intended workflow is this fast coarse pass followed by refine().

Parameters:

master: A de_ebsd.sim.MasterPattern, projected onto the detector at every dictionary orientation.
detector: EBSDDetector geometry; indexed patterns must match its (nrows, ncols).
point_group: orix Symmetry whose fundamental zone is sampled. Falls back to master.metadata["crystal"]; one or the other is required.
resolution: Target average disorientation (degrees) of the sampling. Default 3.0, which refines to the same sub-degree accuracy as 2.0 at a ~3x cheaper build, while 4.0 starts dropping patterns into a wrong basin that refinement cannot escape. Go finer only for strongly pseudo-symmetric phases.
device: Explicit argument > master.device > CPU.
dtype: None (default) auto-selects fp16 on tensor-core GPUs (compute capability >= 7.0) and fp32 elsewhere – on Pascal (native fp16 at 1/64 the fp32 rate) and on CPU (no fp16 matmul) fp16 is a pessimization.
energy_kev: Energy bin the master is projected at; None (default) is the highest.
match_binning: Bin factor for the coarse match only (default 1). Kikuchi bands are low-frequency, so a binned pattern resolves the coarse cell just as well while the match shrinks by match_binning**2. Must divide both detector dimensions. Refinement still runs at full resolution, so this trades nothing away.

Attributes:

dictionary_rotationsorix.quaternion.Rotation: The fundamental-zone orientations, length n_dict.
dictionarytorch.Tensor: Normalized, stored transposed and contiguous as (n_px, n_dict) so the match runs at full matmul throughput (a transposed view runs at ~half).
n_dictint: Number of orientations in the dictionary.

Methods

`index`	Index one pattern or a stack against the fundamental-zone dictionary.
`index_scan`	Index a whole scan and assemble it into an orix `CrystalMap`.
`refine`	Gradient-refine the coarse dictionary orientations to sub-grid accuracy.

index(patterns, return_scores=False)[source]#

Index one pattern or a stack against the fundamental-zone dictionary.

Patterns are always given at full detector resolution; binning to the match resolution happens internally.

Parameters:

patterns: A detector image (H, W) or stack (Np, H, W), numpy or torch.
return_scores: Also return the full (Np, n_dict) float32 score matrix.

Returns:

rotationsorix.quaternion.Rotation: Best-matching fundamental-zone orientation per pattern.
qualitytorch.Tensor: Peak NCC per pattern, roughly in [-1, 1]; higher is better.
scorestorch.Tensor: Only when return_scores: the (Np, n_dict) matrix whose per-row argmax gives rotations.

index_scan(patterns, shape=None, step=1.0, phase=None, batch_size=None, refine=False, refine_iters=12)[source]#

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

Mirrors index_scan().

Parameters:

patterns: Either (rows, cols, H, W), from which the 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 256). Results are identical to a single batch.
refine: Gradient-refine each mini-batch before assembly, making prop["quality"] the refined NCC. The coarse grid makes this the intended finish.
refine_iters: Levenberg-Marquardt steps when refine (default 12).

Returns:

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

refine(patterns, rotations=None, **kw)[source]#

Gradient-refine the coarse dictionary orientations to sub-grid accuracy.

Wraps de_ebsd.index.refine.orientation.refine_orientation(), seeding from this indexer’s master and detector (from index() when rotations is None).

Defaults to method="lm": the second-order refiner reaches the same sub-degree accuracy in ~10 steps rather than Adam’s ~60. LM is orientation-only, so refine_pattern_center=True falls back to Adam. **kw is forwarded; device defaults to this indexer’s.