Implement draw_image

Author: martinRenou

docs/source/drawing_images.rst

@@ -4,12 +4,47 @@ Drawing images
 From an Image widget
 --------------------
 
-Coming soon!
+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``.
+
+.. code:: Python
+
+    from ipywidgets import Image
+
+    from ipycanvas import Canvas
+
+    sprite1 = Image.from_file('sprites/smoke_texture0.png')
+    sprite2 = Image.from_file('sprites/smoke_texture1.png')
+
+    canvas = Canvas(size=(300, 300))
+
+    canvas.fill_style = '#a9cafc'
+    canvas.fill_rect(0, 0, 300, 300)
+
+    canvas.draw_image(sprite1, 50, 50)
+    canvas.draw_image(sprite2, 100, 100)
+
+    canvas
+
+.. image:: images/draw_image1.png
 
 From another Canvas
 -------------------
 
-Coming soon!
+You can draw from another ``Canvas`` widget. This is the fastest way of drawing an image on the canvas.
+
+.. code:: Python
+
+    canvas2 = Canvas(size=(600, 300))
+
+    # Here ``canvas`` is the canvas from the previous example
+    canvas2.draw_image(canvas, 0, 0)
+    canvas2.draw_image(canvas, 300, 0)
+
+    canvas2
+
+.. image:: images/draw_image2.png
 
 From a NumPy array
 ------------------
@@ -41,3 +76,68 @@ You can directly draw a NumPy array of pixels on the ``Canvas``, it must be a 3-
     canvas
 
 .. image:: images/numpy.png
+
+Optimizing drawings
+-------------------
+
+Drawing from another ``Canvas`` is by far the fastest of the three solutions presented here. So if you want to draw the same image a thousand times, it is recommended to first draw this image on a temporary canvas, then draw from the temporary canvas a thousand times.
+
+.. code:: Python
+
+    from random import choice, randint, uniform
+    from math import pi
+
+    from ipywidgets import Image, HBox
+
+    from ipycanvas import Canvas, hold_canvas
+
+    # Create temporary Canvases
+    canvas_sprite1 = Canvas(size=(100, 100))
+    canvas_sprite1.draw_image(Image.from_file('sprites/smoke_texture0.png'), 0, 0)
+
+    canvas_sprite2 = Canvas(size=(100, 100))
+    canvas_sprite2.draw_image(Image.from_file('sprites/smoke_texture1.png'), 0, 0)
+
+    canvas_sprite3 = Canvas(size=(100, 100))
+    canvas_sprite3.draw_image(Image.from_file('sprites/smoke_texture2.png'), 0, 0)
+
+    sprites = [canvas_sprite1, canvas_sprite2, canvas_sprite3]
+
+    # Display them horizontally
+    HBox(sprites)
+
+.. image:: images/sprites.png
+
+.. code:: Python
+
+    canvas = Canvas(size=(800, 600))
+
+    with hold_canvas(canvas):
+        for _ in range(2_000):
+            canvas.save()
+
+            # Choose a random sprite texture
+            sprite = sprites[choice(range(3))]
+
+            # Choose a random sprite position
+            pos_x = randint(0, canvas.size[0])
+            pos_y = randint(0, canvas.size[1])
+
+            # Choose a random rotation angle (but first set the rotation center with `translate`)
+            canvas.translate(pos_x, pos_y)
+            canvas.rotate(uniform(0., pi))
+
+            # Choose a random sprite size
+            canvas.scale(uniform(0.2, 1.))
+
+            # Restore the canvas center
+            canvas.translate(- pos_x, - pos_y)
+
+            # Draw the sprite
+            canvas.draw_image(sprite, pos_x, pos_y)
+
+            canvas.restore()
+
+    canvas
+
+.. image:: images/thousands_sprites.png

docs/source/images/draw_image1.png

@@ -22,11 +22,20 @@
     "from random import choice, randint, uniform\n",
     "from math import pi\n",
     "\n",
-    "from PIL import Image\n",
+    "from PIL import Image as PILImage\n",
     "\n",
     "import numpy as np\n",
     "\n",
-    "from ipycanvas import MultiCanvas, hold_canvas"
+    "from ipywidgets import Image\n",
+    "\n",
+    "from ipycanvas import Canvas, hold_canvas"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Drawing a sprite from an ``Image`` widget"
    ]
   },
   {
@@ -35,9 +44,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def load_image(path):\n",
-    "    \"\"\"Load an image into a NumPy array.\"\"\"\n",
-    "    return np.array(Image.open(path))"
+    "sprite1 = Image.from_file('sprites/smoke_texture0.png')\n",
+    "sprite2 = Image.from_file('sprites/smoke_texture1.png')\n",
+    "\n",
+    "canvas1 = Canvas(size=(300, 300))\n",
+    "canvas1.fill_style = '#a9cafc'\n",
+    "canvas1.fill_rect(0, 0, 300, 300)\n",
+    "canvas1.draw_image(sprite1, 50, 50)\n",
+    "\n",
+    "canvas1"
    ]
   },
   {
@@ -46,8 +61,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Loading sprites as NumPy arrays\n",
-    "sprites_data = [load_image('sprites/smoke_texture{}.png'.format(i)) for i in range(3)]"
+    "canvas1.draw_image(sprite2, 100, 100)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Drawing from another ``Canvas``"
    ]
   },
   {
@@ -56,7 +77,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sprites_data[0].shape"
+    "canvas2 = Canvas(size=(600, 300))\n",
+    "canvas2.draw_image(canvas1, 0, 0)\n",
+    "\n",
+    "canvas2"
    ]
   },
   {
@@ -65,11 +89,23 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = MultiCanvas(n_canvases=2, size=(800, 600))\n",
-    "m[0].fill_style = '#a9cafc'\n",
-    "m[0].fill_rect(0, 0, m.size[0], m.size[1])\n",
-    "\n",
-    "m"
+    "canvas2.draw_image(canvas1, 300, 0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Drawing from a NumPy array"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sprite3 = np.array(PILImage.open('sprites/smoke_texture2.png'))"
    ]
   },
   {
@@ -78,34 +114,88 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "with hold_canvas(m[1]):\n",
-    "    for _ in range(200):\n",
-    "        m[1].save()\n",
+    "canvas2.put_image_data(sprite3, 250, 150)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Drawing thousands of sprites, the more optimized solution is to first \"cache\" your images in other ``Canvas`` instances"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The fastest solution is drawing from another canvas\n",
+    "canvas_sprite1 = Canvas(size=(100, 100))\n",
+    "canvas_sprite1.draw_image(sprite1, 0, 0)\n",
+    "canvas_sprite1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas_sprite2 = Canvas(size=(100, 100))\n",
+    "canvas_sprite2.draw_image(sprite2, 0, 0)\n",
+    "canvas_sprite2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas_sprite3 = Canvas(size=(100, 100))\n",
+    "canvas_sprite3.draw_image(Image.from_file('sprites/smoke_texture2.png'), 0, 0)\n",
+    "canvas_sprite3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas3 = Canvas(size=(800, 600))\n",
+    "\n",
+    "sprites = [canvas_sprite1, canvas_sprite2, canvas_sprite3]\n",
+    "\n",
+    "with hold_canvas(canvas3):\n",
+    "    for _ in range(2_000):\n",
+    "        canvas3.save()\n",
     "\n",
     "        # Choose a random sprite texture\n",
-    "        sprite = sprites_data[choice(range(3))]\n",
-    "        \n",
+    "        sprite = sprites[choice(range(3))]\n",
+    "\n",
     "        # Choose a random sprite position\n",
-    "        pos_x = randint(0, m.size[0] - sprite.shape[1])\n",
-    "        pos_y = randint(0, m.size[1] - sprite.shape[0])\n",
+    "        pos_x = randint(0, canvas3.size[0] - 50)\n",
+    "        pos_y = randint(0, canvas3.size[1] - 50)\n",
     "\n",
     "        # Choose a random rotation angle (but first set the rotation center with `translate`)\n",
-    "        t_x = pos_x + 0.5 * sprite.shape[1]\n",
-    "        t_y = pos_y + 0.5 * sprite.shape[0]\n",
-    "        m[1].translate(t_x, t_y)\n",
-    "        m[1].rotate(uniform(0., pi))\n",
+    "        canvas3.translate(pos_x, pos_y)\n",
+    "        canvas3.rotate(uniform(0., pi))\n",
     "\n",
     "        # Choose a random sprite size\n",
     "        scale = uniform(0.2, 1.)\n",
-    "        m[1].scale(scale)\n",
+    "        canvas3.scale(scale)\n",
     "\n",
     "        # Restore the canvas center\n",
-    "        m[1].translate(- t_x, - t_y)\n",
+    "        canvas3.translate(- pos_x, - pos_y)\n",
     "\n",
     "        # Draw the sprite\n",
-    "        m[1].put_image_data(sprite, pos_x, pos_y)\n",
+    "        canvas3.draw_image(sprite, pos_x, pos_y)\n",
+    "\n",
+    "        canvas3.restore()\n",
     "\n",
-    "        m[1].restore()"
+    "canvas3"
    ]
   }
  ],
@@ -125,7 +215,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.4"
   }
  },
  "nbformat": 4,

docs/source/images/draw_image2.png

@@ -10,7 +10,7 @@
 
 from traitlets import Enum, Float, Instance, List, Tuple, Unicode, observe
 
-from ipywidgets import CallbackDispatcher, Color, DOMWidget, widget_serialization
+from ipywidgets import CallbackDispatcher, Color, DOMWidget, Image, widget_serialization
 
 from ._frontend import module_name, module_version
 
@@ -307,6 +307,18 @@ 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):
+        """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')
+
+        if width is not None and height is None:
+            height = width
+
+        serialized_image = widget_serialization['to_json'](image, None)
+
+        self._send_canvas_command('drawImage', (serialized_image, x, y, width, height))
+
     def put_image_data(self, image_data, dx, dy):
         """Draw an image on the Canvas.