refine_projection_center#
- EBSD.refine_projection_center(xmap: CrystalMap, detector: EBSDDetector, master_pattern: EBSDMasterPattern, energy: int | float, navigation_mask: np.ndarray | None = None, signal_mask: np.ndarray | None = None, method: str | None = 'minimize', method_kwargs: dict | None = None, trust_region: tuple | list | np.ndarray | None = None, initial_step: float | None = None, rtol: float = 0.0001, maxeval: int | None = None, compute: bool = True, rechunk: bool = True, chunk_kwargs: dict | None = None) tuple[np.ndarray, EBSDDetector, np.ndarray] | da.Array [source]#
Refine projection centers by searching the parameter space using fixed orientations.
Refinement attempts to maximize the similarity between patterns in this signal and simulated patterns projected from a master pattern. The similarity metric used is the normalized cross-correlation (NCC). The sample-detector geometry, represented by the three projection center (PC) parameters (PCx, PCy, PCz) in the Bruker convention, is updated during refinement, while the orientations, defined relative to the EDAX TSL sample reference frame RD-TD-ND, are fixed.
A subset of the optimization methods in SciPy and NLopt are available:
- Local optimization:
minimize()
(includes Nelder-Mead, Powell etc.).Nelder-Mead via nlopt.LN_NELDERMEAD
- Global optimization:
- Parameters:
- xmap
Crystal map with points to use in refinement. Only the points in the data (see
CrystalMap
) are used. If anavigation_mask
is given, points equal to points in the data and points equal toFalse
in this mask are used.- detector
Detector describing the detector-sample geometry with either one PC to be used for all map points or one for each point. Which PCs are refined depend on
xmap
andnavigation_mask
.- master_pattern
Master pattern in the square Lambert projection of the same phase as the one in the crystal map.
- energy
Accelerating voltage of the electron beam in kV specifying which master pattern energy to use during projection of simulated patterns.
- navigation_mask
A boolean mask of points in the crystal map to use in refinement (equal to
False
, i.e. points to mask out areTrue
). The mask must be of equal shape to the signal’s navigation shape. If not given, all points in the crystal map data are used.- signal_mask
A boolean mask of detector pixels to use in refinement (equal to
False
, i.e. pixels to mask out areTrue
). The mask must be of equal shape to the signal’s signal shape. If not given, all pixels are used.- method
Name of the
scipy.optimize
or NLopt optimization method, among"minimize"
,"differential_evolution"
,"dual_annealing"
,"basinhopping"
,"shgo"
and"ln_neldermead"
(from NLopt). Default is"minimize"
, which by default performs local optimization with the Nelder-Mead method, unless another"minimize"
method is passed tomethod_kwargs
.- method_kwargs
Keyword arguments passed to the
scipy.optimize
method
. For example, to perform refinement with the modified Powell algorithm from SciPy, passmethod="minimize"
andmethod_kwargs=dict(method="Powell")
. Not used ifmethod="LN_NELDERMEAD"
.- trust_region
List of three +/- deviations in the range [0, 1] used to determine the bounds constraints on the PC parameters per navigation point, e.g.
[0.05, 0.05, 0.05]
. Not passed to SciPymethod
if it does not support bounds. The definition range of the PC parameters are assumed to be [-2, 2].- initial_step
A single initial step size for all PC parameters in the range [0, 1]. Only used if
method="LN_NELDERMEAD"
.- rtol
Stop optimization of a pattern when the difference in NCC score between two iterations is below this value (relative tolerance). Default is
1e-4
. Only used ifmethod="LN_NELDERMEAD"
.- maxeval
Stop optimization of a pattern when the number of function evaluations exceeds this value, e.g.
100
. Only used ifmethod="LN_NELDERMEAD"
.- compute
Whether to refine now (
True
) or later (False
). Default isTrue
. Seecompute()
for more details.- rechunk
If
True
(default), rechunk the dask array with patterns used in refinement (not the signal data inplace) if it is returned fromget_dask_array()
in a single chunk. This ensures small data sets are rechunked so as to utilize multiple CPUs.- chunk_kwargs
Keyword arguments passed to
get_chunking()
ifrechunk=True
and the dask array with patterns used in refinement is returned fromget_dask_array()
in a single chunk.
- Returns:
out
New similarity metrics, a new EBSD detector instance with the refined PCs and the number of function evaluations if
compute=True
. Ifcompute=False
, a dask array of navigation size + (5,) is returned, to be computed later. Seecompute_refine_projection_center_results()
. Each navigation point has the optimized score, the three PC parameters in the Bruker convention and the number of function evaluations in element 0, 1, 2, 3 and 4, respectively.
Notes
If the crystal map to refine contains points marked as not indexed, the returned detector might not have a 2D navigation shape.
NLopt is for now an optional dependency, see Dependencies for details. Be aware that NLopt does not fail gracefully. If continued use of NLopt proves stable enough, its implementation of the Nelder-Mead algorithm might become the default.