{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Transforming into k-space\n",
    "\n",
    "This notebook demonstrates how to use the `Ewald` module to convert a RHEED image coordinates into the $k_x$–$k_y$ space.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "from pathlib import Path\n",
    "\n",
    "import xrheed"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2",
   "metadata": {},
   "source": [
    "## Prepare the Data\n",
    "\n",
    "While not strictly required, it is recommended to first prepare the RHEED data by properly aligning the image. You should also verify the spot positions by comparing them with the points calculated using the `Ewald` module, as illustrated below.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_dir = Path(\"example_data\")\n",
    "image_path = image_dir / \"Si_111_r3Ag_112_thC.raw\"\n",
    "\n",
    "rheed_image = xrheed.load_data(image_path, plugin=\"dsnp_arpes_raw\")\n",
    "\n",
    "# Rotate the image\n",
    "rheed_image.ri.rotate(-0.5)\n",
    "\n",
    "# Manually pre-adjust the image center\n",
    "center_x = -5.8\n",
    "center_y = 0.2\n",
    "\n",
    "rheed_image.ri.set_center_manual(center_x=center_x, center_y=center_y)\n",
    "\n",
    "# Set the screen scale\n",
    "#rheed_image.ri.screen_scale = 9.05\n",
    "\n",
    "# Setup the screen roi\n",
    "rheed_image.ri.screen_roi_width = 50\n",
    "rheed_image.ri.screen_roi_height = 40\n",
    "\n",
    "rheed_image.ri.set_center_auto(update_incident_angle=True)\n",
    "# Prepare the plot\n",
    "fig, ax = plt.subplots()\n",
    "\n",
    "# Use automatic levels adjustment\n",
    "rheed_image.ri.plot_image(\n",
    "    ax=ax, auto_levels=0.2, show_center_lines=True, show_specular_spot=True\n",
    ")\n",
    "\n",
    "# add horizontal line to check the rotation alignment\n",
    "ax.axhline(-58, color=\"m\", linewidth=1.0)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "## Use a High-Pass Filter\n",
    "\n",
    "Applying a high-pass filter before the transformation is highly recommended, as it enhances the visibility of diffraction features by suppressing background intensity.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.preparation.filters import high_pass_filter\n",
    "\n",
    "# Setup the screen roi\n",
    "rheed_image.ri.screen_roi_width = 60\n",
    "rheed_image.ri.screen_roi_height = 90\n",
    "\n",
    "sigma = 1.5\n",
    "threshold = 0.8\n",
    "\n",
    "hp_rheed_image = high_pass_filter(rheed_image, sigma=sigma, threshold=threshold)\n",
    "hp_rheed_image.ri.plot_image(auto_levels=0.3)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image = hp_rheed_image"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "## Prepare the 2D Lattice\n",
    "\n",
    "In this step, we define two lattices: \n",
    "- Si(111)-(1×1) surface structure,\n",
    "- $(\\sqrt{3} \\times \\sqrt{3})\\text{R}30^\\circ$ reconstruction;\n",
    "\n",
    "which is induced by the presence of 1 monolayer (ML) of Ag deposited at 500 °C.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.kinematics import Lattice\n",
    "\n",
    "si_111_1x1 = Lattice.from_surface_hex(a=3.84, label=\"(1x1)\")\n",
    "si_111_1x1.rotate(0.0)\n",
    "\n",
    "si_111_r3 = Lattice.from_surface_hex(a=3.84 * np.sqrt(3), label=\"r3-Ag\")\n",
    "si_111_r3.rotate(30.0)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "\n",
    "si_111_r3.plot_reciprocal(ax=ax, space_size=2.5, s=10, color=\"b\")\n",
    "si_111_1x1.plot_reciprocal(ax=ax, space_size=2.5, s=20, color=\"r\")\n",
    "\n",
    "ax.legend(loc=\"upper right\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9",
   "metadata": {},
   "source": [
    "## Ewald Object\n",
    "Create an instance of the `Ewald` class using the generated Si(111)-(1×1) lattice and the RHEED image.\n",
    "\n",
    "If the RHEED image is properly aligned and scaled—and the lattice matches the actual crystal structure—there should be a good visual match between the calculated and observed diffraction spots, as shown below.\n",
    "\n",
    "If the match is poor, return to the previous cells and adjust parameters such as `shift_x`, `shift_y`, `screen_scale` and `beta` directly on the image object. Then re-run all cells to recreate the `Ewald` object with the updated settings.\n",
    "\n",
    "For convenience, these parameters can initially be adjusted only within the `Ewald` object. However, for accurate results, the RHEED image itself must ultimately be properly aligned.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.kinematics import Ewald\n",
    "\n",
    "ew_si_111_1x1 = Ewald(si_111_1x1, rheed_image)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "\n",
    "# for testing only, finally apply those on the image before creating Ewald object\n",
    "#ew_si_111_1x1.beta = 2.5\n",
    "#ew_si_111_1x1.shift_x = 0.2\n",
    "#ew_si_111_1x1.shift_y = -0.2\n",
    "#ew_si_111_1x1.screen_scale = 9.05\n",
    "#ew_si_111_1x1.ewald_azimuthal_rotation = 0.02\n",
    "\n",
    "ew_si_111_1x1.plot(\n",
    "    ax=ax,\n",
    "    show_image=True,\n",
    "    auto_levels=0.5,\n",
    "    marker=\"o\",\n",
    "    facecolors=\"none\",\n",
    "    edgecolors=\"magenta\",\n",
    "    s=50,\n",
    ")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11",
   "metadata": {},
   "source": [
    "## Final Transformation\n",
    "\n",
    "The image can be transformed using the `transform_image_to_kxky` function.\n",
    "\n",
    "Please note that the resulting image is no longer a RHEED image, and `ri`-related accessories are no longer available. Nonetheless, all attributes are copied from the original RHEED image for consistency.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.conversion import transform_image_to_kxky\n",
    "\n",
    "trans_image = transform_image_to_kxky(rheed_image, rotate=True, point_symmetry=True)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "\n",
    "trans_image.plot(ax=ax, vmin=5, vmax=25, add_colorbar=False)\n",
    "\n",
    "ax.set_xlim(-5, 5)\n",
    "ax.set_ylim(-3, 0.2)\n",
    "ax.set_aspect(1.0)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "## Final Plot with the Reciprocal Lattice\n",
    "\n",
    "Finally, we can prepare a refined plot that displays both lattices overlaid in reciprocal space.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(6, 6))\n",
    "\n",
    "trans_image.plot(ax=ax, vmin=5, vmax=25, add_colorbar=False, cmap=\"gray\")\n",
    "\n",
    "si_111_r3.plot_reciprocal(ax=ax, facecolors=\"none\", edgecolors=\"magenta\", s=100)\n",
    "si_111_1x1.plot_reciprocal(ax=ax, facecolors=\"none\", edgecolors=\"cyan\", s=150)\n",
    "\n",
    "ax.set_xlim(-3.0, 3.0)\n",
    "ax.set_ylim(-3.0, 3.0)\n",
    "ax.set_aspect(1.0)\n",
    "ax.set_facecolor(\"black\")\n",
    "\n",
    "ax.legend(loc=\"upper right\")\n",
    "plt.show()"
   ]
  }
 ],
 "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.12.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}