{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Getting Started\n",
    "This notebook demonstrates how to use xRHEED to load, inspect, and plot an example RHEED image.\n",
    "\n",
    "The image used in this tutorial was recorded from a Si(111)-(7×7) surface. The electron beam was aligned along the $[11\\bar{2}]$ crystallographic direction, and the image was captured at room temperature."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "## Load xRHEED module\n",
    "First, import the `xrheed` library along with other useful Python modules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from pathlib import Path\n",
    "\n",
    "import xrheed"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "## Load a RHEED Image"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "### Using dedicated plugin\n",
    "RHEED images are loaded using dedicated **plugins**.  \n",
    "For more information on writing custom plugins, see the documentation: *Plugins for Data Loading*.  \n",
    "\n",
    "The image coordinates - **sx** (horizontal) and **sy** (vertical) - are expressed in **millimeters**.  \n",
    "This means that the plugin is responsible for converting pixel values to real-world dimensions using the appropriate scaling.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_dir = Path(\"example_data\")\n",
    "image_path = image_dir / \"Si_111_7x7_112_phi_00.raw\"\n",
    "\n",
    "rheed_image = xrheed.load_data(image_path, plugin=\"dsnp_arpes_raw\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "### Manual RHEED Data Loading\n",
    "\n",
    "While writing and using a dedicated plugin is the recommended approach, it is also possible to load RHEED images manually (from **BMP**, **PNG**, **TIFF**).\n",
    "\n",
    "In this mode, you must provide the necessary calibration parameters directly.  \n",
    "\n",
    "Use the `load_data()` function as shown below.  \n",
    "At minimum, the following three parameters are required:\n",
    "\n",
    "- **`screen_sample_distance`** *(float)* — Distance from sample to screen [mm].  \n",
    "- **`screen_scale`** *(float)* — Scaling factor [pixels per mm].  \n",
    "- **`beam_energy`** *(float)* — Beam energy [eV].  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_dir = Path(\"example_data\")\n",
    "image_path = image_dir / \"test_rheed.BMP\"\n",
    "\n",
    "rheed_manual = xrheed.load_data(\n",
    "    image_path,\n",
    "    screen_sample_distance=350.5,\n",
    "    screen_scale=9.5,\n",
    "    beam_energy=18_600,\n",
    "    screen_center_sx_px=749,\n",
    "    screen_center_sy_px=82,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {},
   "source": [
    "## Data format\n",
    "The RHEED data are loaded into an `DataArray` object using `xarray` module.\n",
    "\n",
    "`DataArray` provides powerful built-in methods for data manipulation and analysis. These methods can be used to inspect, slice, and visualize the RHEED image, as demonstrated below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.sel(sx=slice(-50, 50), sy=slice(-60, 10)).plot()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## The `.ri` Accessor\n",
    "\n",
    "Tools dedicated to RHEED images analysis are available through the `.ri` accessor. Please refer to the API documentation to explore all available methods and properties.\n",
    "\n",
    "For example, you can access basic properties of the RHEED image as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(rheed_image.ri.beam_energy)\n",
    "print(rheed_image.ri.screen_scale)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "Return a human-readable summary of the DataArray and key RHEED metadata."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.ri"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14",
   "metadata": {},
   "source": [
    "To view all metadata associated with the image, simply access the `.attrs` property of the `DataArray` object. This will display a dictionary of all attributes stored with the image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.attrs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16",
   "metadata": {},
   "source": [
    "## RHEED Image Preparation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "### Screen ROI\n",
    "\n",
    "Define the region of interest (ROI) for the RHEED image. This ROI is used to set the limits for the `sx` and `sy` axes in the `ri.plot_image()` method.\n",
    "\n",
    "The example below also demonstrates the use of the `auto_levels` argument, which automatically sets the `vmin` and `vmax` values for image contrast adjustment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.ri.screen_roi_width = 60\n",
    "rheed_image.ri.screen_roi_height = 60\n",
    "\n",
    "# Use automatic levels adjustment\n",
    "# auto_levels: percentage of pixels to clip at both low and high ends.\n",
    "rheed_image.ri.plot_image(auto_levels=1.0)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19",
   "metadata": {},
   "source": [
    "### Setting the RHEED Image Center\n",
    "\n",
    "Although the data-loading plugin typically provides screen center information, manual fine-tuning is often required. The image center is defined as follows:\n",
    "\n",
    "- **Horizontal center (`sx = 0`)**: The line connecting the specular spot and the transmitted beam (note: the transmitted beam may not always be visible).\n",
    "- **Vertical center (`sy = 0`)**: Positioned at the shadow boundary.\n",
    "\n",
    "These values depend on the specific RHEED setup and usually require manual adjustment for each image or image series.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "\n",
    "#### Manual Center Adjustment\n",
    "\n",
    "You can manually adjust the image center using the method shown below.\n",
    "\n",
    "> **Note:** Repeated application of the accessor method `ri.set_center_manual` will continuously shift the image by the specified values. To avoid cumulative displacement, we reload the image in the same cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21",
   "metadata": {},
   "outputs": [],
   "source": [
    "image_path = image_dir / \"Si_111_7x7_112_phi_00.raw\"\n",
    "rheed_image = xrheed.load_data(image_path, plugin=\"dsnp_arpes_raw\")\n",
    "\n",
    "rheed_image.ri.set_center_manual(center_x=-0.5, center_y=-0.6)\n",
    "rheed_image.ri.plot_image(show_center_lines=True, auto_levels=1.0)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22",
   "metadata": {},
   "source": [
    "#### Automatic Center Search\n",
    "\n",
    "The center could be set automatically via accessor method `ri.set_center_auto()`.\n",
    "\n",
    "This method supports the `update_incident_angle` argument. When set to `True`, the incident (β) angle is updated based on the positions of transition and specular spots, which are detected during the center search process.\n",
    "\n",
    "> **Note:** Automatic center detection operates on the ROI image. If it fails, consider adjusting the ROI to improve results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "23",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.ri.screen_roi_width = 50\n",
    "rheed_image.ri.screen_roi_height = 60\n",
    "\n",
    "rheed_image.ri.set_center_auto(update_incident_angle=False)\n",
    "\n",
    "rheed_image.ri.plot_image(show_center_lines=True, auto_levels=1.0)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24",
   "metadata": {},
   "source": [
    "#### Semi-Manual Search for Image Center\n",
    "\n",
    "The module `xrheed.preparation.alignment` provides two functions to help locate the horizontal and vertical center of a RHEED image.\n",
    "\n",
    "It is recommended to follow this sequence:\n",
    "\n",
    "- First, determine the horizontal center using `find_horizontal_center(image)`.\n",
    "- Then, pass the calculated value to `find_vertical_center(image, center_x)`.\n",
    "\n",
    "This order is preferred because the vertical center search attempts to locate the mirror and transmission spots near `sx = 0`, which depends on an accurate horizontal center.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.preparation.alignment import find_vertical_center, find_horizontal_center\n",
    "\n",
    "center_x = find_horizontal_center(rheed_image)\n",
    "\n",
    "center_y = find_vertical_center(rheed_image, center_x=center_x)\n",
    "\n",
    "print(f\"Determined values: {center_x:.4f}, {center_y:.4f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26",
   "metadata": {},
   "source": [
    "### Setting the Incident Angle\n",
    "\n",
    "The plugin assigns a default value for the incident (grazing) angle, denoted as **β**. However, for accurate Ewald sphere construction, this value should be manually set or calculated.\n",
    "\n",
    "If both the mirror-reflected and transmitted spots are visible in the RHEED image, their positions can be used to fine-tune the shadow edge location (`sy = 0.0`).\n",
    "\n",
    "To estimate the incident angle, use the `find_incident_angle()` function from the `xrheed.preparation.alignment` module. This function returns the calculated angle.\n",
    "\n",
    "> **Note:** The incident angle may already be updated automatically if `ri.set_center_auto(update_incident_angle=True)` was used.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.preparation.alignment import find_incident_angle\n",
    "\n",
    "real_incident_angle = find_incident_angle(rheed_image)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28",
   "metadata": {},
   "source": [
    "To update the image attribute with the real incident angle β, you can use the `.ri` accessor:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29",
   "metadata": {},
   "outputs": [],
   "source": [
    "rheed_image.ri.incident_angle = real_incident_angle\n",
    "rheed_image.ri"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30",
   "metadata": {},
   "source": [
    "### Image Rotation\n",
    "\n",
    "If the RHEED camera is not perfectly aligned, it may be necessary to rotate the RHEED image to ensure that the shadow edge is perfectly horizontal.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a copy of an image\n",
    "rotated_image = rheed_image.copy()\n",
    "\n",
    "# Rotate the image\n",
    "rotated_image.ri.rotate(-0.4)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "rotated_image.ri.plot_image(ax=ax, show_center_lines=True, auto_levels=1.0)\n",
    "\n",
    "# add horizontal line to check the rotation alignment\n",
    "ax.axhline(-42.0, color=\"b\", linestyle=\"--\")\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use now the rotated image for further analysis\n",
    "rheed_image = rotated_image\n",
    "\n",
    "# Apply automatic center search again after rotation\n",
    "rheed_image.ri.set_center_auto()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33",
   "metadata": {},
   "source": [
    "## High-Pass Filter\n",
    "\n",
    "Apply a high-pass filter to remove the homogeneous background signal from the RHEED image.\n",
    "\n",
    "You can adjust the following parameters:\n",
    "\n",
    "- `sigma` (in mm): controls the width of the Gaussian kernel used for blurring,\n",
    "- `threshold`: scales the blurred image before subtraction.\n",
    "\n",
    "The filtered image is computed as:\n",
    "\n",
    "`filtered_image = real_image - threshold * blurred_image`\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrheed.preparation.filters import high_pass_filter\n",
    "\n",
    "sigma = 3.0\n",
    "threshold = 0.8\n",
    "\n",
    "hp_rheed_image = high_pass_filter(rheed_image, sigma=sigma, threshold=threshold)\n",
    "\n",
    "hp_rheed_image.ri.plot_image(\n",
    "    auto_levels=0.5, show_center_lines=True, show_specular_spot=True\n",
    ")\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
}