Add azimuthal angle to EBSDDetector, used when generating EBSD patterns from masterpattern

[hakonanes]

Signed-off-by: Håkon Wiik Ånes hwaanes@gmail.com

Description of the change

• Add azimuthal angle, which is the sample tilt angle about the RD axis (see figure in the "Reference frames" docs generated from this PR), to the EBSDDetector. This can be used when generating EBSD patterns from masterpatterns with EBSDMasterPattern.get_patterns().
• Update documentation with explanatory figure in "Reference frames"
• Simplify calculation of direction cosines internally in get_patterns(), to use only PC values as fractions of detector shape (unlike the EMsoft absolute values used previously). See example below.

Close #351.

Progress of the PR

• Docstrings for all functions
• Unit tests with pytest for all lines
• Clean code style by running black via pre-commit

Minimal example of the bug fix or new feature

Passing the binning and px_size yields the same patterns because these values aren't used in get_patterns(), but yields different EMsoft PCs

>>> import kikuchipy as kp
>>> from orix.quaternion import Rotation
>>> import matplotlib.pyplot as plt
>>> detector1 = kp.detectors.EBSDDetector(
...     shape=(60, 60),
...     pc=[0.421, 0.7794, 0.5049],
...     sample_tilt=70,
...     convention="tsl",
... )
>>> print(detector1.pc_emsoft())
[[ 4.74  16.764 30.294]]
>>> detector2 = kp.detectors.EBSDDetector(
...     shape=(60, 60),
...     pc=[0.421, 0.7794, 0.5049],
...     sample_tilt=70,
...     binning=8,
...     px_size=70,
...     convention="tsl",
... )
>>> print(detector2.pc_emsoft())
[[   37.92    134.112 16964.64 ]]
>>> mp = kp.data.nickel_ebsd_master_pattern_small(projection="lambert")
>>> r = Rotation.identity()
>>> s = mp.get_patterns(r, detector1, energy=20, compute=True)
>>> s2 = mp.get_patterns(r, detector2, energy=20, compute=True)
>>> np.allclose(s.data, s2.data)
True
>>> fig, ax = plt.subplots(ncols=2)
>>> ax[0].imshow(s.data.squeeze())
>>> ax[1].imshow(s2.data.squeeze())

Effect of the azimuthal angle on projected patterns

>>> import kikuchipy as kp
>>> from orix.quaternion import Rotation
>>> import matplotlib.pyplot as plt
>>> mp = kp.data.nickel_ebsd_master_pattern_small(projection="lambert")
>>> detector1 = kp.detectors.EBSDDetector(
...     shape=(480, 640),
...     pc=(0.531, 0.542, 0.625),
...     convention="tsl",
...     sample_tilt=70,
... )
>>> detector2 = detector1.deepcopy()
>>> detector2.azimuthal = 10  # Sample tilt about RD
>>> detector3 = detector1.deepcopy()
>>> detector3.azimuthal = -10
>>> r = Rotation.identity()
>>> s1 = mp.get_patterns(r, detector1, energy=20, compute=True)
>>> s2 = mp.get_patterns(r, detector2, energy=20, compute=True)
>>> s3 = mp.get_patterns(r, detector3, energy=20, compute=True)
>>> fig, ax = plt.subplots(ncols=3)
>>> ax[0].imshow(s1.data.squeeze())
>>> ax[1].imshow(s2.data.squeeze())
>>> ax[2].imshow(s3.data.squeeze())

For reviewers

• The PR title is short, concise, and will make sense 1 year later.
• New functions are imported in corresponding __init__.py.
• New features, API changes, and deprecations are mentioned in the
  unreleased section in doc/changelog.rst.

[hakonanes]

@friedkitteh, could you quickly look at the examples and tell me if you think this looks reasonable? That's why I asked for a review, not to have a look at all code changes etc.

[friedkitteh]

@friedkitteh, could you quickly look at the examples and tell me if you think this looks reasonable? That's why I asked for a review, not to have a look at all code changes etc.

I haven't looked too much into patterns with azimuthal angle != 0, however, the patterns presented look reasonable. I believe in my refinement branch azimuthal angle is assumed to be 0 and removed from some calculations. If we were to support it, we need to make sure it appears on the correct spots again.

[hakonanes]

I haven't looked too much into patterns with azimuthal angle != 0, however, the patterns presented look reasonable.

Yeah, my intuition tells me the patterns look qualitatively correct based on the updated figure in the documentation. This shows that parts of the viewed pattern moves towards the left when increasing the azimuthal angle (sample is rotated about the RD axis, which points downwards). (Always worth mentioning that we view the pattern from behind the detector towards the sample.)

I believe in my refinement branch azimuthal angle is assumed to be 0 and removed from some calculations. If we were to support it, we need to make sure it appears on the correct spots again.

I think this is fine. If we want to support it at a later point, we can.