Merge pull request #47 from martinRenou/image_sync

Image synchronization

Author: martinRenou

docs/source/basic_usage.rst

@@ -33,10 +33,10 @@ that does not need to update much while other objects moves a lot on the screen.
     - observe some of its attributes and call functions when they change
     - link some of its attributes to other widget attributes
 
-Clear canvas
+Clear Canvas
 ------------
 
-The ``Canvas`` class has a ``clear`` method which allows to clear the entire canvas.
+The ``Canvas`` and ``MultiCanvas`` classes have a ``clear`` method which allows to clear the entire canvas.
 
 .. code:: Python
 
@@ -48,6 +48,37 @@ The ``Canvas`` class has a ``clear`` method which allows to clear the entire can
 
     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
 -------------------
 

examples/plotting.ipynb

@@ -32,7 +32,7 @@
    "source": [
     "def init_2d_plot(x, y, color=None, scheme=branca.colormap.linear.RdBu_11, canvas=None, canvas_size=(800, 600), padding=0.1):\n",
     "    if canvas is None:\n",
-    "        canvas = MultiCanvas(3, size=canvas_size)\n",
+    "        canvas = MultiCanvas(3, size=canvas_size, sync_image_data=True)\n",
     "    else:\n",
     "        canvas.size = canvas_size\n",
     "\n",
@@ -282,6 +282,27 @@
     "plot"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Save the plot to an image file!\n",
+    "plot.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')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

ipycanvas/canvas.py

@@ -8,9 +8,10 @@
 
 import numpy as np
 
-from traitlets import Enum, Float, Instance, List, Tuple, Unicode
+from traitlets import Bool, Bytes, Enum, Float, Instance, List, Tuple, Unicode
 
 from ipywidgets import CallbackDispatcher, Color, DOMWidget, Image, widget_serialization
+from ipywidgets.widgets.trait_types import bytes_serialization
 
 from ._frontend import module_name, module_version
 
@@ -107,6 +108,13 @@ 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, ())
     _click_callbacks = Instance(CallbackDispatcher, ())
@@ -430,6 +438,19 @@ 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.
@@ -503,7 +524,14 @@ class MultiCanvas(DOMWidget):
     _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')
+    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)
 
@@ -550,6 +578,19 @@ 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):

src/utils.ts

@@ -71,3 +71,35 @@ function getArg(metadata: any, buffers: any) : Arg {
 
   throw 'Could not process argument ' + metadata;
 }
+
+export
+async function toBlob(canvas: HTMLCanvasElement) : Promise<Blob> {
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob == null) {
+        return reject('Unable to create blob');
+      }
+
+      resolve(blob);
+    });
+  });
+}
+
+export
+async function toBytes(canvas: HTMLCanvasElement) : Promise<Uint8ClampedArray> {
+  const blob = await toBlob(canvas);
+
+  return new Promise<Uint8ClampedArray>((resolve, reject) => {
+    const reader = new FileReader();
+
+    reader.onloadend = () => {
+        if (typeof reader.result == 'string' || reader.result == null) {
+          return reject('Unable to read blob');
+        }
+
+        const bytes = new Uint8ClampedArray(reader.result);
+        resolve(bytes);
+    };
+    reader.readAsArrayBuffer(blob);
+  });
+}

src/widget.ts

@@ -10,7 +10,7 @@ import {
 } from './version';
 
 import {
-  getArg
+  getArg, toBytes
 } from './utils';
 
 
@@ -34,11 +34,16 @@ class CanvasModel extends DOMWidgetModel {
       _view_module: CanvasModel.view_module,
       _view_module_version: CanvasModel.view_module_version,
       size: [700, 500],
+      sync_image_data: false,
+      image_data: null,
     };
   }
 
   static serializers: ISerializers = {
     ...DOMWidgetModel.serializers,
+    image_data: { serialize: (bytes: Uint8ClampedArray) => {
+      return new DataView(bytes.buffer.slice(0));
+    }}
   }
 
   initialize(attributes: any, options: any) {
@@ -61,6 +66,9 @@ class CanvasModel extends DOMWidgetModel {
     this.forEachView((view: CanvasView) => {
       view.updateCanvas();
     });
+
+    this.trigger('new-frame');
+    this.syncImageData();
   }
 
   private async processCommand(command: any, buffers: any) {
@@ -271,6 +279,17 @@ class CanvasModel extends DOMWidgetModel {
     this.canvas.setAttribute('height', size[1]);
   }
 
+  private async syncImageData() {
+    if (!this.get('sync_image_data')) {
+      return;
+    }
+
+    const bytes = await toBytes(this.canvas);
+
+    this.set('image_data', bytes);
+    this.save_changes();
+  }
+
   static model_name = 'CanvasModel';
   static model_module = MODULE_NAME;
   static model_module_version = MODULE_VERSION;
@@ -350,13 +369,56 @@ class MultiCanvasModel extends DOMWidgetModel {
       _view_name: MultiCanvasModel.view_name,
       _view_module: MultiCanvasModel.view_module,
       _view_module_version: MultiCanvasModel.view_module_version,
+      size: [700, 500],
       _canvases: [],
+      sync_image_data: false,
+      image_data: null,
     };
   }
 
   static serializers: ISerializers = {
     ...DOMWidgetModel.serializers,
     _canvases: { deserialize: (unpack_models as any) },
+    image_data: { serialize: (bytes: Uint8ClampedArray) => {
+      return new DataView(bytes.buffer.slice(0));
+    }}
+  }
+
+  initialize(attributes: any, options: any) {
+    super.initialize(attributes, options);
+
+    this.on('change:_canvases', this.updateListeners.bind(this));
+    this.updateListeners();
+  }
+
+  private updateListeners() {
+    // TODO: Remove old listeners
+    for (const canvasModel of this.get('_canvases')) {
+      canvasModel.on('new-frame', this.syncImageData, this);
+    }
+  }
+
+  private async syncImageData() {
+    if (!this.get('sync_image_data')) {
+      return;
+    }
+
+    const [ width, height ] = this.get('size');
+
+    // Draw on a temporary off-screen canvas.
+    const offscreenCanvas = document.createElement('canvas');
+    offscreenCanvas.width = width;
+    offscreenCanvas.height = height;
+    const ctx = getContext(offscreenCanvas);
+
+    for (const canvasModel of this.get('_canvases')) {
+      ctx.drawImage(canvasModel.canvas, 0, 0)
+    }
+
+    const bytes = await toBytes(offscreenCanvas);
+
+    this.set('image_data', bytes);
+    this.save_changes();
   }
 
   static model_name = 'MultiCanvasModel';