Add get_image_data method

Author: martinRenou

docs/source/basic_usage.rst

@@ -48,37 +48,6 @@ The ``Canvas`` and ``MultiCanvas`` classes have a ``clear`` method which allows
 
     canvas.clear()
 
-Save Canvas to a file
----------------------
-
-You can dump the current ``Canvas`` or ``MultiCanvas`` image using the ``to_file`` method. You first need to specify that you want the image data to be synchronized between the front-end and the back-end setting the ``sync_image_data`` attribute to ``True``.
-
-.. code:: Python
-
-    from ipycanvas import Canvas
-
-    canvas = Canvas(size=(200, 200), sync_image_data=True)
-
-    # Perform some drawings...
-
-    canvas.to_file('my_file.png')
-
-Note that this won't work if executed in the same Notebook cell. Because the Canvas won't have drawn anything yet. If you want to put all your code in the same Notebook cell, you need to define a callback function that will be called when the Canvas is ready to be dumped to an image file.
-
-.. code:: Python
-
-    from ipycanvas import Canvas
-
-    canvas = Canvas(size=(200, 200), sync_image_data=True)
-
-    # Perform some drawings...
-
-    def save_to_file(*args, **kwargs):
-        canvas.to_file('my_file.png')
-
-    # Listen to changes on the ``image_data`` trait and call ``save_to_file`` when it changes.
-    canvas.observe(save_to_file, 'image_data')
-
 Optimizing drawings
 -------------------
 

docs/source/index.rst

@@ -28,6 +28,7 @@ You can try ipycanvas, without the need of installing anything on your computer,
     drawing_shapes
     drawing_text
     drawing_images
+    retrieve_images
     canvas_state
     transformations
     events

docs/source/retrieve_images.rst

@@ -0,0 +1,73 @@
+Retrieve Canvas image
+=====================
+
+There are two methods for retrieving the canvas image:
+
+- ``to_file(filename)``: Dumps the image data to a PNG file.
+- ``get_image_data(x=0, y=0, width=None, height=None)``: Get the image data as a NumPy array for a sub-portion of the Canvas.
+
+By default, and in order to keep ipycanvas fast, the image state of the Canvas is not synchronized between the TypeScript front-end and the Python back-end. If you want to retrieve the image data from the Canvas, you first need to explicitly specify that you want the image to be synchronized by setting ``sync_image_data`` to ``True`` before doing any drawing, you can set ``sync_image_data`` back to ``False`` once you're done.
+
+Save Canvas to a file
+---------------------
+
+You can dump the current ``Canvas`` or ``MultiCanvas`` image to a PNG file using the ``to_file`` method.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(size=(200, 200), sync_image_data=True)
+
+    # Perform some drawings...
+
+    canvas.to_file('my_file.png')
+
+Note that this won't work if executed in the same Notebook cell. Because the Canvas won't have drawn anything yet. If you want to put all your code in the same Notebook cell, you need to define a callback function that will be called when the Canvas is ready to be dumped to an image file.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(size=(200, 200), sync_image_data=True)
+
+    # Perform some drawings...
+
+    def save_to_file(*args, **kwargs):
+        canvas.to_file('my_file.png')
+
+    # Listen to changes on the ``image_data`` trait and call ``save_to_file`` when it changes.
+    canvas.observe(save_to_file, 'image_data')
+
+Get image data as a NumPy array
+-------------------------------
+
+You can get the image data of the ``Canvas`` or ``MultiCanvas`` using the ``get_image_data`` method.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(size=(200, 200), sync_image_data=True)
+
+    # Perform some drawings...
+
+    arr1 = canvas.get_image_data()                # Get the entire Canvas as a NumPy array
+    arr2 = canvas.get_image_data(50, 10, 40, 60)  # Get the subpart defined by the rectangle at position (x=50, y=10) and of size (width=40, height=60)
+
+Note that this won't work if executed in the same Notebook cell. Because the Canvas won't have drawn anything yet. If you want to put all your code in the same Notebook cell, you need to define a callback function that will be called when the Canvas has image data.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(size=(200, 200), sync_image_data=True)
+
+    # Perform some drawings...
+
+    def get_array(*args, **kwargs):
+        arr = canvas.get_image_data()
+        # Do something with arr
+
+    # Listen to changes on the ``image_data`` trait and call ``get_array`` when it changes.
+    canvas.observe(get_array, 'image_data')

examples/plotting.ipynb

@@ -304,14 +304,21 @@
     "plot"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### You can retrieve the entire ``Canvas`` or a subpart of it using the ``get_image_data`` method"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Save the plot to an image file!\n",
-    "plot.to_file('my_scatter.png')"
+    "arr = plot.canvas.get_image_data(200, 300, 50, 100)\n",
+    "arr.shape"
    ]
   },
   {
@@ -320,16 +327,29 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from ipywidgets import Image\n",
+    "plot.canvas[1].stroke_style = 'red'\n",
+    "plot.canvas[1].line_width = 2\n",
+    "plot.canvas[1].stroke_rect(200, 300, 50, 100)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipycanvas import Canvas\n",
     "\n",
-    "Image.from_file('my_scatter.png')"
+    "c = Canvas(size=(50, 100))\n",
+    "c.put_image_data(arr, 0, 0)\n",
+    "c"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Because it's a Canvas, you can draw on top of it! "
+    "### Or you can save it to a file using ``to_file``"
    ]
   },
   {
@@ -338,9 +358,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot[1].stroke_style = 'red'\n",
-    "plot[1].line_width = 2\n",
-    "plot[1].stroke_rect(200, 300, 50, 100)"
+    "plot.canvas.to_file('my_scatter.png')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipywidgets import Image\n",
+    "\n",
+    "Image.from_file('my_scatter.png')"
    ]
   },
   {

ipycanvas/canvas.py

@@ -15,10 +15,65 @@
 
 from ._frontend import module_name, module_version
 
-from .utils import binary_image, populate_args, to_camel_case
+from .utils import binary_image, populate_args, to_camel_case, image_bytes_to_array
 
 
-class Canvas(DOMWidget):
+class CanvasBase(DOMWidget):
+    _model_module = Unicode(module_name).tag(sync=True)
+    _model_module_version = Unicode(module_version).tag(sync=True)
+    _view_module = Unicode(module_name).tag(sync=True)
+    _view_module_version = Unicode(module_version).tag(sync=True)
+
+    size = Tuple((700, 500), help='Size of the Canvas, this is not equal to the size of the view').tag(sync=True)
+
+    #: (bool) Specifies if the image should be synchronized from front-end to Python back-end
+    sync_image_data = Bool(False).tag(sync=True)
+
+    #: (bytes) Current image data as bytes (PNG encoded). It is ``None`` by default and will not be
+    #: updated if ``sync_image_data`` is ``False``.
+    image_data = Bytes(default_value=None, allow_none=True, read_only=True).tag(sync=True, **bytes_serialization)
+
+    def to_file(self, filename):
+        """Save the current Canvas image to a PNG file.
+
+        This will raise an exception if there is no image to save (_e.g._ if ``image_data`` is ``None``).
+        """
+        if self.image_data is None:
+            raise RuntimeError('No image data to save, please be sure that ``sync_image_data`` is set to True')
+        if not filename.endswith('.png') and not filename.endswith('.PNG'):
+            raise RuntimeError('Can only save to a PNG file')
+
+        with open(filename, 'wb') as fobj:
+            fobj.write(self.image_data)
+
+    def get_image_data(self, x=0, y=0, width=None, height=None):
+        """Return a NumPy array representing the underlying pixel data for a specified portion of the canvas.
+
+        This will throw an error if there is no ``image_data`` to retrieve, this happens when nothing was drawn yet or
+        when the ``sync_image_data`` attribute is not set to ``True``.
+        The returned value is a NumPy array containing the image data for the rectangle of the canvas specified. The
+        coordinates of the rectangle's top-left corner are (``x``, ``y``), while the coordinates of the bottom corner
+        are (``x + width``, ``y + height``).
+        """
+        if self.image_data is None:
+            raise RuntimeError('No image data, please be sure that ``sync_image_data`` is set to True')
+
+        x = int(x)
+        y = int(y)
+
+        if width is None:
+            width = self.size[0] - x
+        if height is None:
+            height = self.size[1] - y
+
+        width = int(width)
+        height = int(height)
+
+        image_data = image_bytes_to_array(self.image_data)
+        return image_data[y:y + height, x:x + width]
+
+
+class Canvas(CanvasBase):
     """Create a Canvas widget.
 
     Args:
@@ -27,13 +82,7 @@ class Canvas(DOMWidget):
     """
 
     _model_name = Unicode('CanvasModel').tag(sync=True)
-    _model_module = Unicode(module_name).tag(sync=True)
-    _model_module_version = Unicode(module_version).tag(sync=True)
     _view_name = Unicode('CanvasView').tag(sync=True)
-    _view_module = Unicode(module_name).tag(sync=True)
-    _view_module_version = Unicode(module_version).tag(sync=True)
-
-    size = Tuple((700, 500), help='Size of the Canvas, this is not equal to the size of the view').tag(sync=True)
 
     #: (valid HTML color) The color for filling rectangles and paths. Default to ``'black'``.
     fill_style = Color('black')
@@ -108,13 +157,6 @@ class Canvas(DOMWidget):
     #: (float) Specifies where to start a dash array on a line. Default is ``0.``.
     line_dash_offset = Float(0.)
 
-    #: (bool) Specifies if the image should be synchronized from front-end to Python back-end
-    sync_image_data = Bool(False).tag(sync=True)
-
-    #: (bytes) Current image data as bytes (PNG encoded). It is ``None`` by default and will not be
-    #: updated if ``sync_image_data`` is ``False``.
-    image_data = Bytes(default_value=None, allow_none=True, read_only=True).tag(sync=True, **bytes_serialization)
-
     _client_ready_callbacks = Instance(CallbackDispatcher, ())
     _mouse_move_callbacks = Instance(CallbackDispatcher, ())
     _mouse_down_callbacks = Instance(CallbackDispatcher, ())
@@ -347,7 +389,7 @@ 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, dy):
+    def put_image_data(self, image_data, dx=0, dy=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
@@ -440,19 +482,6 @@ def flush(self):
         self._commands_cache = []
         self._buffers_cache = []
 
-    def to_file(self, filename):
-        """Save the current Canvas image to a PNG file.
-
-        This will raise an exception if there is no image to save (_e.g._ if ``image_data`` is ``None``).
-        """
-        if self.image_data is None:
-            raise RuntimeError('No image data to save')
-        if not filename.endswith('.png') and not filename.endswith('.PNG'):
-            raise RuntimeError('Can only save to a PNG file')
-
-        with open(filename, 'wb') as fobj:
-            fobj.write(self.image_data)
-
     # Events
     def on_client_ready(self, callback, remove=False):
         """Register a callback that will be called when a new client is ready to receive draw commands.
@@ -523,7 +552,7 @@ def _handle_frontend_event(self, _, content, buffers):
             self._mouse_out_callbacks(content['x'], content['y'])
 
 
-class MultiCanvas(DOMWidget):
+class MultiCanvas(CanvasBase):
     """Create a MultiCanvas widget with n_canvases Canvas widgets.
 
     Args:
@@ -532,20 +561,7 @@ class MultiCanvas(DOMWidget):
     """
 
     _model_name = Unicode('MultiCanvasModel').tag(sync=True)
-    _model_module = Unicode(module_name).tag(sync=True)
-    _model_module_version = Unicode(module_version).tag(sync=True)
     _view_name = Unicode('MultiCanvasView').tag(sync=True)
-    _view_module = Unicode(module_name).tag(sync=True)
-    _view_module_version = Unicode(module_version).tag(sync=True)
-
-    size = Tuple((700, 500), help='Size of the Canvas, this is not equal to the size of the view').tag(sync=True)
-
-    #: (bool) Specifies if the image should be synchronized from front-end to Python back-end
-    sync_image_data = Bool(False).tag(sync=True)
-
-    #: (bytes) Current image data as bytes (PNG encoded). It is ``None`` by default and will not be
-    #: updated if ``sync_image_data`` is ``False``.
-    image_data = Bytes(default_value=None, allow_none=True, read_only=True).tag(sync=True, **bytes_serialization)
 
     _canvases = List(Instance(Canvas)).tag(sync=True, **widget_serialization)
 
@@ -592,19 +608,6 @@ def flush(self):
         for layer in self._canvases:
             layer.flush()
 
-    def to_file(self, filename):
-        """Save the current MultiCanvas image to a PNG file.
-
-        This will raise an exception if there is no image to save (_e.g._ if ``image_data`` is ``None``).
-        """
-        if self.image_data is None:
-            raise RuntimeError('No image data to save')
-        if not filename.endswith('.png') and not filename.endswith('.PNG'):
-            raise RuntimeError('Can only save to a PNG file')
-
-        with open(filename, 'wb') as fobj:
-            fobj.write(self.image_data)
-
 
 @contextmanager
 def hold_canvas(canvas):

ipycanvas/utils.py

@@ -1,7 +1,20 @@
 """Binary module."""
+from io import BytesIO
+
+from PIL import Image as PILImage
+
 import numpy as np
 
 
+def image_bytes_to_array(im_bytes):
+    """Turn raw image bytes into a NumPy array."""
+    im_file = BytesIO(im_bytes)
+
+    im = PILImage.open(im_file)
+
+    return np.array(im)
+
+
 def binary_image(ar):
     """Turn a NumPy array representing an array of pixels into a binary buffer."""
     if ar is None: