Skip to content

Commit

Permalink
Improve wording in reference frame tutorial
Browse files Browse the repository at this point in the history 
Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>
  • Loading branch information
@hakonanes
hakonanes committed Oct 31, 2023
1 parent d2129b9 commit 4f8c230
Showing 1 changed file with 33 additions and 40 deletions.
73 changes: 33 additions & 40 deletions doc/tutorials/reference_frames.ipynb
View file
Expand Up @@ -23,7 +23,7 @@
"source": [
"# Reference frames\n",
"\n",
"In this tutorial we cover the reference frames most important to EBSD, which conventions are used in kikuchipy, and how they relate to conventions in the other softwares by Bruker Nano, EDAX TSL, EMsoft, and Oxford Instruments.\n",
"In this tutorial, we cover the reference frames most important to EBSD, chosen conventions in kikuchipy, and how they relate to conventions in the other softwares by Bruker Nano, EDAX TSL, EMsoft, and Oxford Instruments.\n",
"We also test conversions between the conventions by indexing simulated patterns using Hough indexing (HI) from PyEBSDIndex.\n",
"\n",
"## Detector-sample geometry\n",
Expand All @@ -49,18 +49,18 @@
}
},
"source": [
"In **a**, the electron beam interacts with the sample in the source point, and the shortest distance from this point to the detector is called the projection/pattern center (PC).\n",
"A part of the Kikuchi sphere resulting from the beam-sample interaction is projected onto the flat detector in the gnomonic projection, the EBSD pattern (EBSP).\n",
"In **a**, the electron beam interacts with the sample in the source point.\n",
"The shortest distance from this point to the detector is called the projection or pattern center (PC).\n",
"A part of the Kikuchi sphere, resulting from the beam-sample interaction, is projected onto the flat detector in the gnomonic projection, constituting the EBSD pattern (EBSP).\n",
"A gnomonic coordinate system $CS_g$, ($X_g$, $Y_g$, $Z_g$) with (0, 0, 0) in the PC is defined for the detector plane.\n",
"We also define a detector coordinate system $CS_d$, ($X_d$, $Y_d$, $Z_d$), for the detector plane, with (0, 0, 0) in the upper left corner.\n",
"We also define a detector coordinate system $CS_d$, ($X_d$, $Y_d$, $Z_d$) for the detector plane with (0, 0, 0) in the upper left corner.\n",
"The projection center coordinates ($PC_x$, $PC_y$, $PC_z$) are defined in this detector coordinate system:\n",
"\n",
"- $PC_x$ is measured from the left border of the detector in fractions of detector width.\n",
"- $PC_y$ is measured from the top border of the detector in fractions of detector height.\n",
"- $PC_z$ is the distance from the detector scintillator to the sample divided by pattern height.\n",
"\n",
"Orientations are defined in the Bunge convention with respect to the sample\n",
"coordinate system $CS_s$, ($X_s$, $Y_s$, $Z_s$).\n",
"Orientations are defined in the Bunge convention with respect to the sample coordinate system $CS_s$, ($X_s$, $Y_s$, $Z_s$).\n",
"The detector and sample viewed along the microscope $X$ axis are shown in **b**, with the three coordinate systems and the PC also shown.\n",
"The scanned map is shown in **c**.\n",
"Note the orientation of $CS_s$ and the sample \"Top\": the map is scanned from the bottom of the sample and upwards.\n",
Expand Down Expand Up @@ -96,9 +96,7 @@
"source": [
"## The EBSD detector\n",
"\n",
"All relevant parameters for the detector-sample geometry are stored in an\n",
"[kikuchipy.detectors.EBSDDetector](../reference/generated/kikuchipy.detectors.EBSDDetector.rst)\n",
"instance.\n",
"All relevant parameters for the detector-sample geometry are stored in an [EBSDDetector](../reference/generated/kikuchipy.detectors.EBSDDetector.rst) instance.\n",
"Let's first import necessary libraries and a small Nickel EBSD test data set"
]
},
Expand Down Expand Up @@ -145,8 +143,7 @@
}
},
"source": [
"Then we can define a detector with the same parameters as the one used to\n",
"acquire the small Nickel data set"
"Then we can define a detector with the same parameters as the one used to acquire the small nickel data set"
]
},
{
Expand Down Expand Up @@ -195,9 +192,7 @@
"Passing the PC in the EDAX TSL, Oxford, or EMsoft convention is also supported.\n",
"The definitions of the conventions are given in the [EBSDDetector](../reference/generated/kikuchipy.detectors.EBSDDetector.rst) API reference, together with the conversion from PC coordinates in the EDAX TSL, Oxford, or EMsoft conventions to PC coordinates in the Bruker convention.\n",
"\n",
"The PC coordinates in the EDAX TSL, Oxford, or EMsoft conventions can be retreived via\n",
"[EBSDDetector.pc_tsl()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_tsl.rst),\n",
"[EBSDDetector.pc_oxford()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_oxford.rst), and [EBSDDetector.pc_emsoft()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_emsoft.rst), respectively.\n",
"The PC coordinates in the EDAX TSL, Oxford, or EMsoft conventions can be retreived via [EBSDDetector.pc_tsl()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_tsl.rst), [EBSDDetector.pc_oxford()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_oxford.rst), and [EBSDDetector.pc_emsoft()](../reference/generated/kikuchipy.detectors.EBSDDetector.pc_emsoft.rst), respectively.\n",
"The latter requires the unbinned detector pixel size in microns and the detector binning to be given upon initialization."
]
},
Expand Down Expand Up @@ -246,7 +241,7 @@
"source": [
"This will produce a figure similar to the right panel in the [detector coordinates figure](#detector-coordinates) above, without the arrows and colored labels.\n",
"\n",
"Multiple PCs with a 1D or 2D navigation shape can be passed to the `pc` parameter upon initialization, or can be set directly.\n",
"Multiple PCs with a 1D or 2D navigation shape can be passed to the `pc` parameter upon initialization, or they can be set directly.\n",
"This gives the detector a navigation shape (not to be confused with the detector shape) and a navigation dimension (maximum of two)"
]
},
Expand Down Expand Up @@ -312,8 +307,9 @@
"\n",
"Note\n",
"\n",
"The offset and scale of HyperSpy’s `axes_manager` is fixed for a signal, meaning that we cannot let the PC vary with scan position if we want to calibrate the EBSD detector via the `axes_manager`.\n",
"The need for a varying PC was the main motivation behind the `EBSDDetector` class.\n",
"The offset and scale of HyperSpy’s `axes_manager` is fixed for a signal.\n",
"This restricts us from letting the PC vary with scan position if we want to calibrate the EBSD detector via the `axes_manager`.\n",
"The need for a varying PC was the main motivation for the `EBSDDetector` class.\n",
" \n",
"</div>"
]
Expand Down Expand Up @@ -395,8 +391,8 @@
"## Other software's reference frames\n",
"\n",
"Other software use other reference frames.\n",
"To aid in the conversion of a set of observations, typically orientations, between softwares, the reference frames used in other softwares are also shown here, represented to the best of the\n",
"contributors understanding.\n",
"To aid in the conversion of orientations between softwares, the reference frames used in other softwares are also shown here.\n",
"They represented to the best of the contributors understanding.\n",
"\n",
"<div class=\"alert alert-warning\">\n",
"\n",
Expand Down Expand Up @@ -471,7 +467,7 @@
"## Test PC conventions with PyEBSDIndex\n",
"\n",
"We can test the PC conventions using Hough indexing in PyEBSDIndex.\n",
"We will use ten simulated nickel patterns with a fixed PC and random orientations.\n",
"We will use ten dynamically simulated nickel patterns with a fixed PC and random orientations.\n",
"We check for consistency by passing the PC in all the conventions described above when indexing, and making sure that the indexed orientations are rotated so that they are defined with respect to the same sample reference frame (the one used in kikuchipy, EDAX TSL and EMsoft).\n",
"\n",
"<div class=\"alert alert-info\">\n",
Expand Down Expand Up @@ -534,8 +530,8 @@
"metadata": {},
"outputs": [],
"source": [
"rot = Rotation.random(10)\n",
"ori = Orientation(rot, mp.phase.point_group)"
"Gr = Rotation.random(10)\n",
"G = Orientation(Gr, mp.phase.point_group)"
]
},
{
Expand All @@ -551,7 +547,7 @@
"metadata": {},
"outputs": [],
"source": [
"s2 = mp.get_patterns(rot, det2, energy=20, compute=True)"
"s2 = mp.get_patterns(Gr, det2, energy=20, compute=True)"
]
},
{
Expand Down Expand Up @@ -597,9 +593,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"For the various softwares, define the PCs and the transformations bringing\n",
"the indexed orientations returned from PyEBSDIndex back to the sample reference\n",
"frame used in kikuchipy, EDAX TSL and EMsoft"
"For the various softwares, define the PCs and the transformations bringing the indexed orientations returned from PyEBSDIndex back to the sample reference frame used in kikuchipy, EDAX TSL, and EMsoft"
]
},
{
Expand All @@ -615,11 +609,11 @@
" \"OXFORD\": det2.pc_oxford(),\n",
" \"EMSOFT\": det2.pc_emsoft(),\n",
"}\n",
"post_rot = {\n",
"Gr_sample = {\n",
" \"KIKUCHIPY\": Rotation.identity(),\n",
" \"BRUKER\": Rotation.from_axes_angles((0, 0, 1), -np.pi / 2),\n",
" \"BRUKER\": Rotation.from_axes_angles([0, 0, 1], -np.pi / 2),\n",
" \"EDAX\": Rotation.identity(),\n",
" \"OXFORD\": Rotation.from_axes_angles((0, 0, 1), -np.pi / 2),\n",
" \"OXFORD\": Rotation.from_axes_angles([0, 0, 1], -np.pi / 2),\n",
" \"EMSOFT\": Rotation.identity(),\n",
"}\n",
"\n",
Expand All @@ -638,7 +632,7 @@
"\n",
"1. Initialize a PyEBSDIndex indexer, specifying the vendor and vendor specific PC\n",
"2. Index the ten patterns\n",
"3. Apply vendor specific post rotation to the returned orientations\n",
"3. Apply vendor specific conversion to the returned orientations\n",
"4. Print misorientation angle between indexed orientations and ground truth orientations\n",
"5. Plot the indexed orientations and the ground truth in inverse pole figures (IPFs)"
]
Expand All @@ -649,8 +643,7 @@
"metadata": {},
"outputs": [],
"source": [
"# Keyword arguments common to all vendors\n",
"v_sample = Vector3d([(1, 0, 0), (0, 1, 0), (0, 0, 1)])\n",
"v_sample = Vector3d([(1, 0, 0), (0, 1, 0)])\n",
"for vendor, pc in pcs.items():\n",
" print(vendor)\n",
"\n",
Expand All @@ -668,26 +661,26 @@
" patDim=det2.shape,\n",
" )\n",
" data, *_ = indexer.index_pats(s2.data)\n",
" rot_hi = Rotation(data[-1][\"quat\"]) * post_rot[vendor]\n",
" ori_hi = Orientation(rot_hi, mp.phase.point_group)\n",
" Gr_hi = Rotation(data[0][\"quat\"]) * Gr_sample[vendor]\n",
" G_hi = Orientation(Gr_hi, mp.phase.point_group)\n",
"\n",
" print(\"Mori. angle to ground truth:\\n\", ori_hi.angle_with(ori, degrees=True))\n",
" fig = ori.scatter(\n",
" print(f\"Average misorientation angle to ground truth: {G_hi.angle_with(G, degrees=True).mean():.4f}\")\n",
" fig = G.scatter(\n",
" \"ipf\",\n",
" direction=v_sample,\n",
" c=\"b\",\n",
" c=\"C0\",\n",
" s=200,\n",
" return_figure=True,\n",
" )\n",
" ori_hi.scatter(\"ipf\", figure=fig, c=\"orange\", s=100)\n",
" G_hi.scatter(\"ipf\", figure=fig, c=\"C1\", s=100)\n",
" plt.pause(0.5) # Show IPFs before continuing with next vendor"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"From the IPFs, we see that all indexed orientations for all vendors are very close to the ground truth orientations, with an average misorientation angle below 0.5$^{\\circ}$.\n",
"From the IPFs, we see that all indexed orientations for all vendors are close to the ground truth orientations, with an average misorientation angle below 0.5$^{\\circ}$.\n",
"This confirms that the PC conventions for the various vendors are consistent and that PyEBSDIndex is consistent with kikuchipy."
]
}
Expand All @@ -708,7 +701,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.4"
"version": "3.11.6"
}
},
"nbformat": 4,
Expand Down

0 comments on commit 4f8c230

Please sign in to comment.