{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "df229fb9-0a56-47b4-a8d2-72cab8782624",
   "metadata": {},
   "source": [
    "#### **Title**: Scalebar\n",
    "\n",
    "**Dependencies**: Bokeh\n",
    "\n",
    "**Backends**: [Bokeh](./Scalebar.ipynb)\n",
    "\n",
    "The `scalebar` feature overlays a scale bar on the element to help gauge the size of features on a plot. This is particularly useful for maps, images like CT or MRI scans, and other scenarios where traditional axes might be insufficient."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1cee420f-3ad1-4b0c-ae66-b26d726d7a0a",
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "import numpy as np\n",
    "\n",
    "hv.extension(\"bokeh\")\n",
    "\n",
    "pollen = hv.RGB.load_image(\"../assets/pollen.png\", bounds=(-10, -5, 10, 15)).opts(scalebar=True)\n",
    "pollen"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d58cb23b-206b-4368-aed7-b083a7766320",
   "metadata": {},
   "source": [
    "Zoom in and out to see the scale bar dynamically adjust."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04f983fc-69cf-4b79-bdd2-6e437366167d",
   "metadata": {},
   "source": [
    "### Custom Units"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "298933cc-8122-4252-b510-fca24f07326b",
   "metadata": {},
   "source": [
    "By default, the `scalebar` uses meters. To customize the units, use the `scalebar_unit` parameter, which accepts a tuple of two strings: the first for the actual measurement and the second for the base unit that remains invariant regardless of scale. In the example below, the y-axis unit is micro-volts (`µV`), and the base unit is Volts (`V`).\n",
    "\n",
    "You can also apply a unit to the y-label independently of the scale bar specification using `hv.Dimension`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1140d0c9-5538-477c-b461-82f09648bd1c",
   "metadata": {},
   "outputs": [],
   "source": [
    "dim = hv.Dimension('Voltage', unit='µV')\n",
    "hv.Curve(np.random.rand(1000), ['time'], [dim]).opts(\n",
    "    width=400,\n",
    "    scalebar=True,\n",
    "    scalebar_range='y',\n",
    "    scalebar_unit=('µV', 'V'),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39af797f-4ea2-449b-96c7-eb7d0da8394e",
   "metadata": {},
   "source": [
    "### Customization\n",
    "\n",
    "In the plot above, you can see that we applied the scalebar to the y-axis by specifying the `scalebar_range` argument. Below are further customization options for the scalebar:\n",
    "\n",
    "- The `scalebar_location` parameter defines the positioning anchor for the scalebar, with options like \"bottom_right\", \"top_left\", \"center\", etc.\n",
    "- The `scalebar_label` parameter allows customization of the label template, using variables such as `@{value}` and `@{unit}`.\n",
    "- The `scalebar_opts` parameter enables specific styling options for the scalebar, as detailed in the [Bokeh's documentation](https://docs.bokeh.org/en/latest/docs/reference/models/annotations.html#bokeh.models.ScaleBar).\n",
    "\n",
    "All these parameters are only utilized if `scalebar` is set to `True` in `.opts()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ab063b3-d1cb-40b4-9fa7-a5860932c16d",
   "metadata": {},
   "outputs": [],
   "source": [
    "dim = hv.Dimension('Voltage', unit='µV')\n",
    "hv.Curve(np.random.rand(1000), ['time'], [dim]).opts(\n",
    "    color='lightgrey',\n",
    "    width=400,\n",
    "    scalebar=True,\n",
    "    scalebar_range='y',\n",
    "    scalebar_unit=('µV', 'V'),\n",
    "    scalebar_location = 'top_right',\n",
    "    scalebar_label = '@{value} [@{unit}]',\n",
    "    scalebar_opts={\n",
    "        'background_fill_alpha': 0,\n",
    "        'border_line_color': None,\n",
    "        'label_text_font_size': '20px',\n",
    "        'label_text_color': 'maroon',\n",
    "        'label_text_alpha': .5,\n",
    "        'label_location': 'left',\n",
    "        'length_sizing': 'exact',\n",
    "        'bar_length': 0.5,\n",
    "        'bar_line_color': 'maroon',\n",
    "        'bar_line_alpha': .5,        \n",
    "        'bar_line_width': 5,\n",
    "        'margin': 0,\n",
    "        'padding': 5,\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "871c7b55-353e-4ec6-8b79-bf1299cd2a45",
   "metadata": {},
   "source": [
    "### Toolbar \n",
    "\n",
    "The scalebar tool is added to the toolbar with a measurement ruler icon. Toggling this icon will either hide or show the scalebars. To remove scalebar icon from the toolbar, set `scalebar_tool = False`.\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}