EBSDDetector#

class kikuchipy.detectors.EBSDDetector(shape: tuple[int, int] = (1, 1), px_size: float = 1.0, binning: int = 1, tilt: float = 0.0, azimuthal: float = 0.0, twist: float = 0.0, sample_tilt: float = 70.0, pc: ndarray | list | tuple = (0.5, 0.5, 0.5), convention: Literal['bruker', 'tsl', 'edax', 'amatek', 'oxford', 'aztec', 'emsoft', 'emsoft4', 'emsoft5'] | None = 'bruker')[source]#

Bases: object

An EBSD detector defining the detector’s view of the sample.

The detector stores information of the detector shape, pixel size, binning factor, tilt, azimuthal, and twist, the sample tilt, and the projection/pattern center (PC) per beam position. Given one or multiple PCs, the detector’s gnomonic coordinates are calculated.

A detector defines the transformations needed to project patterns generated in the sample to the detector.

Parameters:

shape

Number of detector rows \(N_y\) and columns \(N_x\), in pixels. Default is (1, 1).

px_size

Size of the square unbinned detector pixel \(\delta\), in microns. Default is 1.0.

binning

Detector binning factor \(b\), i.e. how many pixels are binned into one. Default is 1, meaning no binning.

tilt

Detector tilt \(\theta\) about the detector horizontal \(X_d\), in degrees. Default is \(0^{\circ}\).

A positive angle means features on the detector appear to move upward (assuming all other defaults).

azimuthal

Detector tilt \(\omega\) about the detector vertical \(Y_d\), in degrees. Default is \(0^{\circ}\).

A positive angle means features on the detector appear to move toward the right (assuming all other defaults).

twist

Detector tilt \(\gamma\) about the detector normal \(Z_d\), in degrees. Default is \(0^{\circ}\).

A positive angle means features on the detector appear to move counter-clockwise about the projection center (assuming all other defaults).

sample_tilt

Sample tilt \(\sigma\) about the microscope X, \(X_m\), in degrees. Default is \(70^{\circ}\), a typical angle for EBSD acquisition.

pc

X, Y, and Z coordinates of the projection centers (PCs) in the given convention. Default is [0.5, 0.5, 0.5]. The PC describes the location of the beam on the sample surface measured relative to the detector screen. See Notes for the definitions of and conversions between conventions. If multiple PCs are given, they are assumed to be on the form [[x0, y0, z0], [x1, y1, z1], …].

convention

Convention of the given pc. Default is Bruker’s convention. This determines how to convert pc to the internal (Bruker’s) definition. Options are “edax”/”tsl”/”amatek”, “oxford”/”aztec”, “bruker”, “emsoft”, “emsoft4”, and “emsoft5”. “emsoft” and “emsoft5” is the same convention. See Notes for conversions between conventions.

Notes

The pattern on the detector is always viewed from the detector towards the sample. Pattern width and height in pixels are here given as \(N_x\) and \(N_y\), respectively (possibly binned). PCs are stored and used internally in Bruker’s convention.

The Bruker PC coordinates \((x_B^*, y_B^*, z_B^*)\) are defined in fractions of \(N_x\), \(N_y\), and \(N_y\), respectively. \(x_B^*\) and \(y_B^*\) are defined with respect to the upper left corner of the detector. The Bruker PC coordinates are used internally, called \((PC_x, PC_y, PC_z)\) in the rest of the documentation when there is no reference to Bruker specifically.

The EDAX TSL PC coordinates \((x_T^*, y_T^*, z_T^*)\) are defined in fractions of \(N_x\), \(N_y\), and \(\min(N_x, N_y)\) with respect to the lower left corner of the detector, respectively.

Given these definitions, the following is the conversion from a PC in EDAX TSL’s convention to a PC in Bruker’s convention

\[\begin{split}x_B^* &= x_T^*,\\ y_B^* &= 1 - y_T^*,\\ z_B^* &= \frac{\min(N_x, N_y)}{N_y} z_T^*.\end{split}\]

The Oxford Instruments PC coordinates \((x_O^*, y_O^*, z_O^*)\) are defined in fractions of \(N_x\) with respect to the lower left corner of the detector. The conversion from Oxford Instruments to Bruker is therefore given as

\[\begin{split}x_B^* &= x_O^*,\\ y_B^* &= 1 - y_O^* \frac{N_x}{N_y},\\ z_B^* &= \frac{N_x}{N_y} z_O^*.\end{split}\]

The EMsoft PC coordinates \((x_{pc}, y_{pc})\) are defined as the number of pixels (with subpixel accuracy) with respect to the center of the detector. \(x_{pc}\) points towards the right and \(y_{pc}\) points upwards. The final PC coordinate, \(L\), is the detector distance, in microns. Note that prior to EMsoft v5.0, \(x_{pc}\) was defined towards the left. The conversion from EMsoft to Bruker is then, finally, given as

\[\begin{split}x_B^* &= \frac{1}{2} - \frac{x_{pc}}{N_x b},\\ y_B^* &= \frac{1}{2} - \frac{y_{pc}}{N_y b},\\ z_B^* &= \frac{L}{N_y b \delta},\end{split}\]

where \(\delta\) is the unbinned detector pixel size in microns and \(b\) is the binning factor.

The calculation of gnomonic coordinates is based on the supplementary material to [Britton et al., 2016].

Attributes

`EBSDDetector.aspect_ratio`	Return the number of detector columns \(N_x\) divided by the number of detector rows \(N_y\).
`EBSDDetector.azimuthal`	Return or set the detector tilt \(\omega\) about the detector vertical \(Y_d\), in degrees.
`EBSDDetector.binning`	Return or set the integer detector binning factor, \(b\).
`EBSDDetector.bounds`	Return the detector bounds \((0, N_x - 1, 0, N_y - 1)\) in pixel coordinates.
`EBSDDetector.euler`	Return the detector Euler angles in the Bunge convention (ZXZ) in degrees.
`EBSDDetector.gnomonic_bounds`	Return the detector bounds [x0, x1, y0, y1] in gnomonic coordinates.
`EBSDDetector.height`	Return the detector height in microns.
`EBSDDetector.navigation_dimension`	Return the number of navigation dimensions of the projection center array.
`EBSDDetector.navigation_shape`	Return or set the navigation shape of the projection center array.
`EBSDDetector.navigation_size`	Return the number of projection centers.
`EBSDDetector.ncols`	Return the number of detector pixel columns \(N_x\).
`EBSDDetector.nrows`	Return the number of detector pixel rows \(N_y\).
`EBSDDetector.pc`	Return or set all projection center (PC) coordinates.
`EBSDDetector.pc_average`	Return the average projection center.
`EBSDDetector.pc_flattened`	Return a flattened array of projection center coordinates of shape (`navigation_size`, 3).
`EBSDDetector.pcx`	Return or set the projection center (PC) x coordinates.
`EBSDDetector.pcy`	Return or set the projection center (PC) y coordinates.
`EBSDDetector.pcz`	Return or set the projection center (PC) z coordinates.
`EBSDDetector.px_size`	Return the pixel size.
`EBSDDetector.px_size_binned`	Return the binned pixel size in microns.
`EBSDDetector.r_max`	Return the maximum distance from `pc` to the detector edge in gnomonic coordinates.
`EBSDDetector.sample_tilt`	Return or set the sample tilt \(\sigma\) about the microscope X, \(X_m\), in degrees.
`EBSDDetector.sample_to_detector`	Return a rotation that transform vectors given in the sample reference frame in the detector reference frame.
`EBSDDetector.shape`	Return or set the number of detector rows \(N_y\) and columns \(N_x\) in pixels.
`EBSDDetector.size`	Return the number of detector pixels \(N_x N_y\).
`EBSDDetector.specimen_scintillator_distance`	Return the specimen-to-scintillator distance, known in EMsoft as \(L\), given in microns.
`EBSDDetector.tilt`	Return or set the detector tilt \(\theta\) about the detector horizontal \(X_d\), in degrees.
`EBSDDetector.twist`	Return or set the detector twist \(\gamma\) about the detector normal \(Z_d\), in degrees.
`EBSDDetector.unbinned_shape`	Return the unbinned detector shape in pixels.
`EBSDDetector.width`	Return the detector width in microns.
`EBSDDetector.x_max`	Return the right bound in gnomonic coordinates.
`EBSDDetector.x_min`	Return the left bound in gnomonic coordinates.
`EBSDDetector.x_range`	Return the horizontal detector range in gnomonic coordinates.
`EBSDDetector.x_scale`	Return the width of a pixel in gnomonic coordinates.
`EBSDDetector.y_max`	Return the lower bound in gnomonic coordinates.
`EBSDDetector.y_min`	Return the upper bound in gnomonic coordinates.
`EBSDDetector.y_range`	Return the vertical detector range in gnomonic coordinates.
`EBSDDetector.y_scale`	Return the height of a pixel in gnomonic coordinates.

Methods

`EBSDDetector.crop`(extent)	Return a new detector with its `shape` cropped and `pc` values updated accordingly.
`EBSDDetector.deepcopy`()	Return a deep copy using `copy.deepcopy()`.
`EBSDDetector.estimate_xtilt`(...)	Return an estimate of the tilt about the detector \(X_d\) axis.
`EBSDDetector.estimate_xtilt_ztilt`([degrees, ...])	Return estimated tilts about the detector \(X_d\) and \(Z_d\) axes.
`EBSDDetector.extrapolate_pc`(pc_indices, ...)	Return a new detector with projection centers (PCs) in a 2D map extrapolated from an average PC.
`EBSDDetector.fit_pc`(-> ~typing.Self)	Return a new detector with interpolated projection centers (PCs) for all points in a map by fitting a plane to `pc`.
`EBSDDetector.get_indexer`(phase_list[, ...])	Return a PyEBSDIndex EBSD indexer.
`EBSDDetector.load`(fname)	Return an EBSD detector loaded from a text file saved with `save()`.
`EBSDDetector.pc_bruker`()	Return PC in the Bruker convention, given in the class description.
`EBSDDetector.pc_emsoft`([version])	Return the projection center(s) `pc` in the EMsoft convention.
`EBSDDetector.pc_oxford`()	Return PC in the Oxford convention.
`EBSDDetector.pc_tsl`()	Return PC in the EDAX TSL convention.
`EBSDDetector.plot`(-> None)	Plot the detector screen viewed from the detector towards the sample.
`EBSDDetector.plot_pc`(-> None)	Plot all projection centers (PCs).
`EBSDDetector.plot_side_view`(-> None)	Plot the EBSD detector-sample geometry in a 2D side-view.
`EBSDDetector.plot_top_view`(-> None)	Plot the EBSD detector-sample geometry in a 2D top-view.
`EBSDDetector.save`(filename[, convention])	Save the detector in a text file with projection centers (PCs) in the given convention.
`EBSDDetector.to_gnomonic_coords`(coords[, pos])	Return the corresponding gnomonic coordinates for the given detector pixel coordinates.
`EBSDDetector.to_pixel_coords`(coords[, pos])	Return the corresponding detector pixel coordinates for the given gnomonic coordinates.