{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### **Title**: FreehandDraw Stream\n",
    "\n",
    "**Description**: A linked streams example demonstrating how to use the FreehandDraw stream.\n",
    "\n",
    "**Dependencies**: Bokeh\n",
    "    \n",
    "**Backends**: [Bokeh](./FreehandDraw.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "from holoviews import opts\n",
    "from holoviews import streams\n",
    "hv.extension('bokeh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``FreehandDraw`` stream adds a bokeh tool to the source plot, which allows freehand drawing on the plot canvas and makes the resulting paths available to Python. The tool supports the following actions:\n",
    "\n",
    "**Draw**\n",
    "\n",
    "    Click and drag to draw a line or polygon, release mouse to stop drawing\n",
    "    \n",
    "**Delete line**\n",
    "\n",
    "    Tap a line to select it then press BACKSPACE key while the mouse is within the plot area.\n",
    "    \n",
    "### Properties\n",
    "\n",
    "* **``empty_value``**: Value to add to non-coordinate columns when adding new path\n",
    "* **``num_objects``** (int): Maximum number of paths to draw before deleting the oldest object\n",
    "* **``styles``** (dict): Dictionary of style properties (e.g. line_color, line_width etc.) to apply to each path. If values are lists the values will cycle over the values.\n",
    "    \n",
    "The tool allows drawing lines and polygons by supplying it with a ``Path`` or ``Polygons`` object as a source. It also allows limiting the number of lines or polygons that can be drawn by setting ``num_objects`` to a finite number, causing the first line to be dropped when the limit is reached."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path = hv.Path([])\n",
    "freehand = streams.FreehandDraw(source=path, num_objects=3,\n",
    "                                styles={'line_color': ['red', 'green', 'blue']})\n",
    "\n",
    "path.opts(\n",
    "    opts.Path(active_tools=['freehand_draw'], height=400, line_width=10, width=400))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center><img src=\"https://assets.holoviews.org/gifs/examples/streams/bokeh/freehand_draw.gif\" width=400></center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whenever the data source is edited the data is synced with Python, both in the notebook and when deployed on the bokeh server. The data is made available as a dictionary of columns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "freehand.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively we can use the ``element`` property to get an Element containing the returned data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "freehand.element"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}