Add scalebar support (#6002)

Co-authored-by: Demetris Roumis <[email protected]>

doc/conf.py

@@ -95,7 +95,8 @@
             'elements',
             'containers',
             'streams',
-            'apps'
+            'apps',
+            'features',
         ]
     }
 

examples/reference/features/bokeh/Scalebar.ipynb

@@ -0,0 +1,144 @@
+{
+ "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
+}