{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "t1-header",
   "metadata": {},
   "source": [
    "# Tutorial 1: How to Open a Simple 2D Panel\n",
    "\n",
    "This tutorial shows how to create and display a simple 2D visualization panel in scivianna. You'll learn the complete workflow from importing the library to displaying interactive visualizations of MED mesh/field files."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-imports",
   "metadata": {},
   "source": [
    "## Step 1: Import Scivianna\n",
    "\n",
    "First, import the scivianna module along with supporting classes. These are the core components you'll use throughout all tutorials:\n",
    "\n",
    "- `ComputeSlave`: The computation engine that manages data processing and interface communication\n",
    "- `MEDInterface`: The interface for reading MED (MEDCoupling) mesh and field files\n",
    "- `Panel2D`: The 2D visualization panel widget for displaying geometry and fields\n",
    "- `GEOMETRY` / `MESH`: Constants used to identify file types and display modes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t1-import-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "import scivianna\n",
    "from pathlib import Path\n",
    "from scivianna.slave import ComputeSlave\n",
    "from scivianna.interface.med_interface import MEDInterface\n",
    "from scivianna.panel.panel_2d import Panel2D\n",
    "from scivianna.constants import MESH, GEOMETRY\n",
    "import scivianna.input_file\n",
    "\n",
    "print(f\"Scivianna version: {scivianna.__version__ if hasattr(scivianna, '__version__') else 'dev'}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-convenience-panel",
   "metadata": {},
   "source": [
    "## Step 2: Create a Panel Using Convenience Functions\n",
    "\n",
    "The fastest way to get started is using scivianna's convenience functions. These helper functions encapsulate the common pattern of creating a `ComputeSlave`, loading a file, and wrapping it in a `Panel2D`.\n",
    "\n",
    "`get_med_panel()` is the simplest approach. It takes a MED file path and returns a ready-to-use `Panel2D` instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t1-get-med-panel-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scivianna.notebook_tools import get_med_panel\n",
    "\n",
    "# Path to a built-in example MED file\n",
    "med_file_path = Path(scivianna.input_file.__file__).parent / \"power.med\"\n",
    "\n",
    "# Create the panel with a single function call\n",
    "panel = get_med_panel(geo=str(med_file_path), title=\"MED Visualizer\")\n",
    "\n",
    "# Display the panel - note: while it can work on standard jupyter notebook, it does not through VS-Code due to a bokeh vscode incompatibility\n",
    "# panel"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-custom-panel",
   "metadata": {},
   "source": [
    "## Step 3: Create a Panel Manually (Advanced)\n",
    "\n",
    "For more control over the visualization, you can build the panel step by step. This approach gives you access to all customization options:\n",
    "\n",
    "- `display_polygons`: `True` for polygon-based rendering (cell-by-cell colors), `False` for grid rendering (interpolated field on a mesh grid)\n",
    "- `displayed_field`: Which field to display by default (e.g., `MESH` for geometry outline, or a field name like temperature)\n",
    "- `colormap`: The color mapping scheme (e.g., `\"BuRd\"` for blue-red, `\"Viridis\"`, etc.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t1-manual-panel-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a ComputeSlave with the MED interface\n",
    "slave = ComputeSlave(MEDInterface)\n",
    "\n",
    "# Load the geometry file (MED format)\n",
    "slave.read_file(med_file_path, GEOMETRY)\n",
    "\n",
    "# Create the Panel2D with explicit configuration\n",
    "panel_manual = Panel2D(\n",
    "    slave=slave,\n",
    "    name=\"Manual 2D Panel\",\n",
    "    display_polygons=True,      # Display as polygons (False for grid mode)\n",
    "    displayed_field=MESH,        # Display geometry outline by default\n",
    "    colormap=\"BuRd\",             # Colormap: BuRd, Viridis, Plasma, etc.\n",
    ")\n",
    "\n",
    "# panel_manual"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-interactions",
   "metadata": {},
   "source": [
    "## Step 4: Panel Interactions\n",
    "\n",
    "The 2D panel supports several interactive features:\n",
    "\n",
    "- **Zoom/Pan**: Use the toolbar on the right side of the plot\n",
    "- **Colormap**: Select from available colormaps in the sidebar\n",
    "- **Field Selection**: Choose which field to display (geometry, temperature, pressure, etc.)\n",
    "- **Axes Adjustment**: Change the viewing angle (u, v, w axes) in the sidebar\n",
    "\n",
    "You can also configure update events to react to user interactions. Update events determine when the panel recomputes the visualization:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "t1-update-events-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scivianna.enums import UpdateEvent\n",
    "\n",
    "# Set panel to recompute when user clicks on the plot\n",
    "panel.update_event = UpdateEvent.CLIC\n",
    "\n",
    "# Or multiple events\n",
    "# panel.update_event = [UpdateEvent.CLIC, UpdateEvent.MOUSE_POSITION_CHANGE]\n",
    "\n",
    "# Available update events:\n",
    "# - UpdateEvent.CLIC: Recompute on mouse click (useful for cell inspection)\n",
    "# - UpdateEvent.MOUSE_POSITION_CHANGE: Recompute on every mouse move\n",
    "# - UpdateEvent.MOUSE_CELL_CHANGE: Recompute only when entering a new cell\n",
    "# - UpdateEvent.RANGE_CHANGE: Recompute when zoom/pan bounds change\n",
    "# - UpdateEvent.RECOMPUTE: Manual recompute only (default, no auto-update)\n",
    "# - UpdateEvent.PERIODIC: Periodic updates for real-time simulation coupling"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-programmatic-control",
   "metadata": {},
   "source": [
    "## Step 5: Programmatic Control\n",
    "\n",
    "You can control the panel programmatically for automation or custom workflows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t1-programmatic-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change the displayed field\n",
    "panel.set_field(\"TEMPERATURE\")\n",
    "\n",
    "# Change the colormap\n",
    "panel.set_colormap(\"Viridis\")\n",
    "\n",
    "# Set custom axes coordinates\n",
    "panel.set_coordinates(\n",
    "    u=(1.0, 0.0, 0.0),    # Horizontal axis direction vector\n",
    "    v=(0.0, 1.0, 0.0),    # Vertical axis direction vector\n",
    "    u_min=0.0, u_max=1.0, # Horizontal range bounds\n",
    "    v_min=0.0, v_max=1.0, # Vertical range bounds\n",
    "    w=0.5                 # Normal axis position (for 3D slicing)\n",
    ")\n",
    "\n",
    "# Get available fields for the loaded geometry\n",
    "available_fields = slave.get_labels()\n",
    "print(f\"Available fields: {available_fields}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-show-serve",
   "metadata": {},
   "source": [
    "## Step 6: Displaying the Panel Outside a Notebook\n",
    "\n",
    "When running from a regular Python script (not a Jupyter notebook), you can display the panel using these two approaches:\n",
    "\n",
    "- **`_show_panel()`**: Opens the panel in a local browser window (blocking call)\n",
    "- **`_serve_panel()`**: Starts a web server accessible from any machine on the network\n",
    "\n",
    "These functions are available in `scivianna.notebook_tools`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "t1-show-serve-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scivianna.notebook_tools import _show_panel, _serve_panel\n",
    "\n",
    "# To display in a local browser (uncomment to run):\n",
    "# _show_panel(panel, title=\"MED Visualizer\")\n",
    "\n",
    "# To serve on the network (uncomment to run):\n",
    "# _serve_panel(panel, title=\"MED Visualizer\")\n",
    "# This starts a web server and opens the panel in your browser at the machine's IP address"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "t1-summary",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this tutorial, you learned:\n",
    "1. How to import scivianna and its core components (`ComputeSlave`, `MEDInterface`, `Panel2D`)\n",
    "2. How to create a 2D panel quickly using convenience functions (`get_med_panel`)\n",
    "3. How to create a panel manually with full control over display mode, field, and colormap\n",
    "4. How to configure update events for interactive recomputation (click, mouse position, cell change, range change)\n",
    "5. How to programmatically control the panel (change fields, colormaps, axes coordinates)\n",
    "6. How to display the panel outside a notebook using `_show_panel()` or `_serve_panel()`\n",
    "\n",
    "## Next Steps\n",
    "\n",
    "- [Tutorial 2: Multiview Panels](./2_multiview_panels.ipynb) - Display multiple panels side by side\n",
    "- [Tutorial 3: 2D-1D Panel Interactions](./3_panel_2d_1d_interactions.ipynb) - Link 2D geometry views with 1D line plots"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv_t4",
   "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}