{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f7ed2d3c",
   "metadata": {},
   "source": [
    "# Element_To_Draw & WolfMapViewer — Drawing architecture\n",
    "\n",
    "This tutorial explains the object hierarchy used for rendering in the WOLF GUI.\n",
    "\n",
    "- `Element_To_Draw` — base class for all drawable objects\n",
    "- `WolfMapViewer` — the main OpenGL viewer (wxPython `wx.Frame`)\n",
    "\n",
    "> **Note** — `WolfMapViewer` requires wxPython and an OpenGL context.\n",
    "> This notebook focuses on the *architecture* and what can be done headless.\n",
    "> For full GUI usage, see the [GUI video tutorials](videos_gui_all.rst)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb448eef",
   "metadata": {},
   "source": [
    "## Inheritance tree\n",
    "\n",
    "All objects that can be displayed in `WolfMapViewer` inherit from `Element_To_Draw`:\n",
    "\n",
    "```\n",
    "Element_To_Draw\n",
    "├── WolfArray / WolfArrayModel     (raster grids)\n",
    "├── WolfArrayMB                    (multi-block arrays)\n",
    "├── Zones                          (vector data)\n",
    "│   ├── PictureCollection          (georeferenced photos)\n",
    "│   └── ImagesTiles                (tiled raster images)\n",
    "├── Wolfresults_2D                 (2D simulation results)\n",
    "├── Triangulation                  (triangulated meshes)\n",
    "├── cloud_vertices                 (point clouds)\n",
    "├── SyntheticDike                  (dike geometry)\n",
    "├── crosssections                  (cross-sections)\n",
    "└── ... (bridges, weirs, particle systems, ...)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a788169d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from wolfhece.drawing_obj import Element_To_Draw"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa79d712",
   "metadata": {},
   "source": [
    "## Element_To_Draw — base interface\n",
    "\n",
    "Every drawable object exposes these core attributes and methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "c0af5426",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Identifier : my_layer\n",
      "Plotted?   : True\n",
      "Bounds     : x=[0.0, 0.0], y=[0.0, 0.0]\n",
      "MapViewer  : None\n"
     ]
    }
   ],
   "source": [
    "elem = Element_To_Draw(idx='my_layer', plotted=True)\n",
    "\n",
    "print(f\"Identifier : {elem.idx}\")\n",
    "print(f\"Plotted?   : {elem.plotted}\")\n",
    "print(f\"Bounds     : x=[{elem.xmin}, {elem.xmax}], y=[{elem.ymin}, {elem.ymax}]\")\n",
    "print(f\"MapViewer  : {elem.mapviewer}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "38642f12",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "After uncheck: plotted=False\n"
     ]
    }
   ],
   "source": [
    "# Toggle visibility\n",
    "elem.check_plot()   # plotted = True\n",
    "elem.uncheck_plot() # plotted = False\n",
    "print(f\"After uncheck: plotted={elem.plotted}\")\n",
    "\n",
    "# Attach to a viewer (normally done automatically)\n",
    "# elem.set_mapviewer(viewer)\n",
    "\n",
    "# Compute spatial extent (overridden by subclasses)\n",
    "elem.find_minmax(update=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5084d2f3",
   "metadata": {},
   "source": [
    "## Key methods to override in subclasses\n",
    "\n",
    "When creating a new drawable class:\n",
    "\n",
    "| Method | Purpose |\n",
    "|--------|---------|\n",
    "| `plot(sx, sy, xmin, ymin, xmax, ymax)` | Render in OpenGL context |\n",
    "| `find_minmax(update)` | Compute spatial bounding box |\n",
    "| `show_properties()` | Display properties dialog |\n",
    "| `check_plot()` / `uncheck_plot()` | Visibility toggle hooks |\n",
    "\n",
    "```python\n",
    "class MyCustomLayer(Element_To_Draw):\n",
    "    def __init__(self, data, **kwargs):\n",
    "        super().__init__(**kwargs)\n",
    "        self.data = data\n",
    "\n",
    "    def find_minmax(self, update=False):\n",
    "        self.xmin = self.data[:, 0].min()\n",
    "        self.xmax = self.data[:, 0].max()\n",
    "        self.ymin = self.data[:, 1].min()\n",
    "        self.ymax = self.data[:, 1].max()\n",
    "\n",
    "    def plot(self, sx=None, sy=None, **kwargs):\n",
    "        if not self.plotted:\n",
    "            return\n",
    "        # OpenGL rendering code here...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e52c7bc8",
   "metadata": {},
   "source": [
    "## WolfMapViewer — the GUI viewer\n",
    "\n",
    "`WolfMapViewer` is a `wx.Frame` that manages a list of `Element_To_Draw` objects and renders them\n",
    "in an OpenGL canvas. It handles:\n",
    "\n",
    "- **Layer management**: add/remove arrays, vectors, results, etc. via the tree panel\n",
    "- **Pan & zoom**: mouse-driven navigation\n",
    "- **Querying**: tooltip shows values under cursor\n",
    "- **Actions**: profile extraction, zone statistics, polygon analysis\n",
    "\n",
    "### Opening the viewer from Python\n",
    "\n",
    "```python\n",
    "import wx\n",
    "from wolfhece.PyDraw import WolfMapViewer\n",
    "\n",
    "app = wx.App()\n",
    "viewer = WolfMapViewer(title='My Viewer', w=1024, h=768)\n",
    "\n",
    "# Add a WolfArray\n",
    "from wolfhece.wolf_array import WolfArray\n",
    "wa = WolfArray(fname='path/to/data.bin')\n",
    "viewer.add_object('dem', newobj=wa)\n",
    "\n",
    "viewer.Show()\n",
    "app.MainLoop()\n",
    "```\n",
    "\n",
    "### Main object lists in WolfMapViewer\n",
    "\n",
    "| Attribute | Type stored |\n",
    "|-----------|-------------|\n",
    "| `myarrays` | `WolfArray`, `WolfArrayMB` |\n",
    "| `myvectors` | `Zones` |\n",
    "| `myclouds` | `cloud_vertices`, `cloud_of_clouds` |\n",
    "| `mytri` | `Triangulation` |\n",
    "| `myres2D` | `Wolfresults_2D` |\n",
    "| `mypicturecollections` | `PictureCollection` |\n",
    "| `myimagestiles` | `ImagesTiles` |"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd2d1ab8",
   "metadata": {},
   "source": [
    "## Model / GUI pattern\n",
    "\n",
    "Many wolfhece classes follow a Model/GUI split:\n",
    "\n",
    "| Model class (headless) | GUI class (wx) | Purpose |\n",
    "|----------------------|---------------|----------|\n",
    "| `WolfArrayModel` | `WolfArray` | Raster grids |\n",
    "| `wolfpaletteModel` | `wolfpalette` | Color palettes |\n",
    "| `header_wolf` | — | Spatial metadata |\n",
    "\n",
    "Use Model classes for scripts, tests, and notebooks; GUI classes when running\n",
    "inside `WolfMapViewer`. See the [architecture tutorial](architecture_model_gui.ipynb)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python311",
   "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.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}