doc/reference_frames.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `kikuchipy` documentation https://kikuchipy.org.\n",
    "Links to the documentation won't work from the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Reference frames\n",
    "\n",
    "## Sample-detector geometry\n",
    "\n",
    "The figures below show the\n",
    "[sample reference frame](#fig:detector-sample-geometry) and the\n",
    "[detector reference frame](#fig:detector-coordinates) used in kikuchipy, all of\n",
    "which are right handed. In short, the sample reference frame is the one used by\n",
    "EDAX TSL, RD-TD-ND, while the pattern center is defined as in the Bruker\n",
    "software."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img id=\"fig:detector-sample-geometry\" src=\"_static/image/reference_frames/detector_sample_geometry.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In **(a)**, a schematic of the microscope chamber shows the orientation of the\n",
    "crystal reference frame, RD-TD-ND, attached to the sample. The\n",
    "$x_{euler}-y_{euler}-z_{euler}$ crystal reference frame used by Bruker\n",
    "Nano EDAX TSL is shown for reference. An EBSD pattern on the detector screen is\n",
    "viewed from behind the screen towards the sample. **(b)** shows how the EBSD map\n",
    "appears within the data collection software, with the crystal reference frame\n",
    "and the scanning reference frame, $x_{scan}-y_{scan}-z_{scan}$, attached.\n",
    "**(c)** shows the relationship between the crystal reference frame and the\n",
    "detector reference frame, $x_{detector}-y_{detector}-z_{detector}$, with\n",
    "the projection center highlighted. The detector tilt $\\theta$ and sample tilt\n",
    "$\\sigma$, in this case $10^{\\circ}$ and $70^{\\circ}$, respectively, are also\n",
    "shown."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img id=\"fig:detector-coordinates\" src=\"_static/image/reference_frames/detector_gnomonic_coordinates.jpg\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above figure shows the EBSD pattern in the\n",
    "[sample reference frame figure](#fig:detector-sample-geometry) **(a)** as viewed\n",
    "from behind the screen towards the sample (left), with the detector reference\n",
    "frame the same as in **(c)** with its origin (0, 0) in the upper left pixel. The\n",
    "detector pixels' gnomonic coordinates can be described with a calibrated\n",
    "projection center (PC) (right), with the gnomonic reference frame origin (0, 0)\n",
    "in ($PC_x, PC_y$). The circles indicate the angular distance from the PC in\n",
    "steps of $10^{\\circ}$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The EBSD detector\n",
    "\n",
    "All relevant parameters for the sample-detector geometry are stored in an\n",
    "[kikuchipy.detectors.EBSDDetector](reference.rst#kikuchipy.detectors.ebsd_detector.EBSDDetector)\n",
    "instance. Let's first import necessary libraries and a small Nickel EBSD test\n",
    "data set"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# exchange inline for qt5 for interactive plotting from the pyqt package\n",
    "%matplotlib inline\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "plt.rcParams[\"font.size\"] = 15\n",
    "import numpy as np\n",
    "import kikuchipy as kp\n",
    "\n",
    "\n",
    "s = kp.data.nickel_ebsd_small()  # Use kp.load(\"data.h5\") to load your own data\n",
    "s"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we can define a detector with the same parameters as the one used to\n",
    "acquire the small Nickel data set"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector = kp.detectors.EBSDDetector(\n",
    "    shape=s.axes_manager.signal_shape[::-1],\n",
    "    pc=[0.421, 0.779, 0.505],\n",
    "    convention=\"tsl\",\n",
    "    px_size=70,  # microns\n",
    "    binning=8,\n",
    "    tilt=0,\n",
    "    sample_tilt=70\n",
    ")\n",
    "detector"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.pc_tsl()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The projection/pattern center (PC) is stored internally in the Bruker\n",
    "convention:\n",
    "- PCx is measured from the left border of the detector in fractions of detector\n",
    "  width.\n",
    "- PCy is measured from the top border of the detector in fractions of detector\n",
    "  height.\n",
    "- PCz is the distance from the detector scintillator to the sample divided by\n",
    "  pattern height.\n",
    "\n",
    "Above, the PC was passed in the EDAX TSL convention. Passing the PC in the\n",
    "Bruker, Oxford, or EMsoft v4 or v5 convention is also supported. Likewise, the\n",
    "PC can be returned in all conventions via\n",
    "[EBSDDetector.pc_emsoft()](reference.rst#kikuchipy.detectors.ebsd_detector.EBSDDetector.pc_emsoft)\n",
    "and similar. Conversions between conventions are implemented as described in\n",
    "<cite data-cite=\"jackson2019dictionary\">Jackson et al. (2019)</cite>. The\n",
    "unbinned pixel size $\\delta$, binning factor $b$ and number of pixel rows $s_y$\n",
    "and columns $s_x$ are needed to convert a PC between the EMsoft and Bruker\n",
    "conventions:\n",
    "\n",
    "- EDAX TSL or Oxford to Bruker\n",
    "\n",
    "$$\n",
    "[PC_x, PC_y, PC_z] = [x^*, 1 - y^*, z^*].\n",
    "$$\n",
    "\n",
    "- EMsoft to Bruker, with $v = -1$ for EMsoft v5 and $+1$ for v4\n",
    "\n",
    "$$\n",
    "[PC_x, PC_y, PC_z] = \\left[\n",
    "\\frac{1}{2} + v\\frac{x_{pc}}{s_x b},\n",
    "\\frac{1}{2} - \\frac{y_{pc}}{s_y b},\n",
    "\\frac{L}{s_y \\delta b}\n",
    "\\right].\n",
    "$$\n",
    "\n",
    "The detector can be plotted to show whether the average PC is placed as\n",
    "expected using\n",
    "[EBSDDetector.plot()](reference.rst#kikuchipy.detectors.ebsd_detector.EBSDDetector.plot)\n",
    "(see its docstring for a complete explanation of its parameters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx-thumbnail": {
     "tooltip": "Definitions of the sample and projection/pattern center reference frames"
    },
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "detector.plot(pattern=s.inav[0, 0].data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will produce a figure similar to the left panel in the\n",
    "[detector coordinates figure](#fig:detector-coordinates) above, without the\n",
    "arrows and colored labels.\n",
    "\n",
    "Multiple PCs with a 1D or 2D navigation shape can be passed to the `pc`\n",
    "parameter upon initialization, or can be set directly. This gives the detector\n",
    "a navigation shape (not to be confused with the detector shape) and a navigation\n",
    "dimension (maximum of two)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.pc = np.ones([3, 4, 3]) * [0.421, 0.779, 0.505]\n",
    "detector.navigation_shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.navigation_dimension"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.pc = detector.pc[0, 0]\n",
    "detector.navigation_shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "The offset and scale of HyperSpy’s `axes_manager` is fixed for a signal,\n",
    "meaning that we cannot let the PC vary with scan position if we want to\n",
    "calibrate the EBSD detector via the `axes_manager`. The need for a varying\n",
    "PC was the main motivation behind the `EBSDDetector` class.\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The right panel in the [detector coordinates figure](#fig:detector-coordinates)\n",
    "above shows the detector plotted in the gnomonic projection using\n",
    "[EBSDDetector.plot()](reference.rst#kikuchipy.detectors.ebsd_detector.EBSDDetector.plot).\n",
    "We assign 2D gnomonic coordinates ($x_g, y_g$) in a gnomonic projection plane\n",
    "parallel to the detector screen to a 3D point ($x_d, y_d, z_d$) in the detector\n",
    "frame as\n",
    "\n",
    "$$\n",
    "x_g = \\frac{x_d}{z_d}, \\qquad y_g = \\frac{y_d}{z_d}.\n",
    "$$\n",
    "\n",
    "The detector bounds and pixel scale in this projection, per navigation point,\n",
    "are stored with the detector"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.bounds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.gnomonic_bounds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.x_range"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "detector.r_max  # Largest radial distance to PC"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}