Merge pull request #52 from martinRenou/example_plot_class

Add Handdrawing Notebook example

Author: martinRenou

docs/source/drawing_images.rst

@@ -6,7 +6,7 @@ From an Image widget
 
 You can draw from an `Image <https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html#Image>`_ widget directly, this is the less optimized solution but it works perfectly fine if you don't draw more than a hundred images at a time.
 
-- ``draw_image(image, x, y, width=None, height=None)``: Draw an ``image`` on the Canvas at the coordinates (``x``, ``y``) and scale it to (``width``, ``height``). The ``image`` must be an ``Image`` widget or another ``Canvas``.
+- ``draw_image(image, x=0, y=0, width=None, height=None)``: Draw an ``image`` on the Canvas at the coordinates (``x``, ``y``) and scale it to (``width``, ``height``). The ``image`` must be an ``Image`` widget or another ``Canvas``. If ``width``/``height`` is ``None``, the natural image ``width``/``height`` is used.
 
 .. code:: Python
 
@@ -51,7 +51,7 @@ From a NumPy array
 
 You can directly draw a NumPy array of pixels on the ``Canvas``, it must be a 3-D array of integers and the last dimension must be 3 or 4 (rgb or rgba), with values going from ``0`` to ``225``.
 
-- ``put_image_data(image_data, dx, dy)``: Draw an image on the Canvas. ``image_data`` should be  a NumPy array containing the image to draw and ``dx`` and ``dy`` the pixel position where to draw (top left pixel of the image).
+- ``put_image_data(image_data, x=0, y=0)``: Draw an image on the Canvas. ``image_data`` should be  a NumPy array containing the image to draw and ``x`` and ``y`` the pixel position where to draw (top left pixel of the image).
 
 .. code:: python
 

docs/source/events.rst

@@ -1,10 +1,12 @@
 Interactions
 ============
 
-Using built-in events
+Built-in mouse events
 ---------------------
 
-The following built-in mouse events are supported: ``mouse_down``, ``mouse_move``, ``mouse_up`` and ``mouse_out``.
+The following built-in mouse events are supported: ``mouse_down``, ``mouse_move``, ``mouse_up`` and ``mouse_out``. You can define Python callback functions that will be called whenever those mouse events occur, using the ``on_mouse_down``, ``on_mouse_move``, ``on_mouse_up`` and ``on_mouse_out`` methods.
+
+Those methods take a callback function as single argument, this callback function must take two positional arguments that are the ``x`` and ``y`` pixel coordinates where the mouse was during the event.
 
 .. code:: Python
 
@@ -23,8 +25,8 @@ The following built-in mouse events are supported: ``mouse_down``, ``mouse_move`
 .. note::
     Please open an issue or a Pull Request if you want more events to be supported by ipycanvas
 
-Using ipyevents
----------------
+ipyevents
+---------
 
 If built-in events are not enough for your use case, you can use `ipyevents <https://github.com/mwcraig/ipyevents>`_ which provides mouse and keyboard events.
 

examples/hand_drawing.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipywidgets import Image\n",
+    "\n",
+    "from ipywidgets import ColorPicker, IntSlider, link, AppLayout, HBox\n",
+    "\n",
+    "from ipycanvas import MultiCanvas, hold_canvas"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "width = 500\n",
+    "height = 500"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = MultiCanvas(3, size=(width, height))\n",
+    "\n",
+    "image = Image.from_file('sprites/logo.png')\n",
+    "\n",
+    "background_layer = canvas[0]\n",
+    "drawing_layer = canvas[1]\n",
+    "interaction_layer = canvas[2]\n",
+    "\n",
+    "drawing = False\n",
+    "start = None\n",
+    "\n",
+    "def draw_line(canvas, start, end):\n",
+    "    canvas.begin_path()\n",
+    "    canvas.move_to(start[0], start[1])\n",
+    "    canvas.line_to(end[0], end[1])\n",
+    "    canvas.stroke()\n",
+    "    canvas.close_path()\n",
+    "\n",
+    "def on_mouse_down(x, y):\n",
+    "    global drawing\n",
+    "    global start\n",
+    "\n",
+    "    if not drawing:\n",
+    "        start = (x, y)\n",
+    "    else:\n",
+    "        with hold_canvas(canvas):\n",
+    "            draw_line(drawing_layer, start, (x, y))\n",
+    "\n",
+    "            interaction_layer.clear()\n",
+    "\n",
+    "        start = None\n",
+    "    \n",
+    "    drawing = not drawing\n",
+    "\n",
+    "def on_mouse_move(x, y):\n",
+    "    if not drawing:\n",
+    "        return\n",
+    "\n",
+    "    with hold_canvas(canvas):\n",
+    "        interaction_layer.clear()\n",
+    "\n",
+    "        draw_line(interaction_layer, start, (x, y))\n",
+    "\n",
+    "interaction_layer.on_mouse_down(on_mouse_down)\n",
+    "interaction_layer.on_mouse_move(on_mouse_move)\n",
+    "\n",
+    "background_layer.draw_image(image, 0, 0, width, height)\n",
+    "\n",
+    "drawing_layer.stroke_style = '#749cb8'\n",
+    "drawing_layer.line_width = 3\n",
+    "interaction_layer.stroke_style = '#749cb8'\n",
+    "interaction_layer.line_width = 3\n",
+    "\n",
+    "picker = ColorPicker(description='Color:', value='#749cb8')\n",
+    "slider = IntSlider(description='Line width:', value=3, min=1, max=20)\n",
+    "\n",
+    "link((picker, 'value'), (drawing_layer, 'stroke_style'))\n",
+    "link((picker, 'value'), (interaction_layer, 'stroke_style'))\n",
+    "link((slider, 'value'), (drawing_layer, 'line_width'))\n",
+    "link((slider, 'value'), (interaction_layer, 'line_width'))\n",
+    "\n",
+    "AppLayout(center=canvas, footer=HBox((picker, slider)))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/sprites.ipynb

@@ -4,13 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Displaying sprites on the Canvas\n",
-    "\n",
-    "Note that this notebook needs `pillow` for loading the sprite image:\n",
-    "\n",
-    "```\n",
-    "$ pip install pillow\n",
-    "```"
+    "# Displaying sprites on the Canvas"
    ]
   },
   {

examples/sprites/logo.png

@@ -377,7 +377,7 @@ def set_line_dash(self, segments):
         self._send_canvas_command('setLineDash', (self._line_dash, ))
 
     # Image methods
-    def draw_image(self, image, x, y, width=None, height=None):
+    def draw_image(self, image, x=0, y=0, width=None, height=None):
         """Draw an ``image`` on the Canvas at the coordinates (``x``, ``y``) and scale it to (``width``, ``height``)."""
         if (not isinstance(image, (Canvas, Image))):
             raise TypeError('The image argument should be an Image widget or a Canvas widget')
@@ -389,15 +389,15 @@ def draw_image(self, image, x, y, width=None, height=None):
 
         self._send_canvas_command('drawImage', (serialized_image, x, y, width, height))
 
-    def put_image_data(self, image_data, dx=0, dy=0):
+    def put_image_data(self, image_data, x=0, y=0):
         """Draw an image on the Canvas.
 
-        ``image_data`` should be  a NumPy array containing the image to draw and ``dx`` and ``dy`` the pixel position where to
+        ``image_data`` should be  a NumPy array containing the image to draw and ``x`` and ``y`` the pixel position where to
         draw. Unlike the CanvasRenderingContext2D.putImageData method, this method **is** affected by the canvas transformation
         matrix, and supports transparency.
         """
         image_metadata, image_buffer = binary_image(image_data)
-        self._send_canvas_command('putImageData', (image_metadata, dx, dy), (image_buffer, ))
+        self._send_canvas_command('putImageData', (image_metadata, x, y), (image_buffer, ))
 
     def create_image_data(self, width, height):
         """Create a NumPy array of shape (width, height, 4) representing a table of pixel colors."""