Add put_image_data and binary buffers support

Author: martinRenou

ipycanvas/binary.py

@@ -0,0 +1,32 @@
+"""Binary module."""
+
+try:
+    from io import BytesIO as StringIO  # python3
+except:
+    from StringIO import StringIO  # python2
+
+import numpy as np
+
+
+def array_to_binary(ar):
+    """Turn a NumPy array into a binary buffer."""
+    if ar is None:
+        return None
+    if ar.dtype != np.uint8:
+        ar = ar.astype(np.uint8)
+    if ar.ndim == 1:
+        ar = ar[np.newaxis, :]
+    if ar.ndim == 2:
+        # extend grayscale to RGBA
+        add_alpha = np.full((ar.shape[0], ar.shape[1], 4), 255, dtype=np.uint8)
+        add_alpha[:, :, :3] = np.repeat(ar[:, :, np.newaxis], repeats=3, axis=2)
+        ar = add_alpha
+    if ar.ndim != 3:
+        raise ValueError("Please supply an RGBA array with shape (width, height, 4).")
+    if ar.shape[2] != 4 and ar.shape[2] == 3:
+        add_alpha = np.full((ar.shape[0], ar.shape[1], 4), 255, dtype=np.uint8)
+        add_alpha[:, :, :3] = ar
+        ar = add_alpha
+    if not ar.flags["C_CONTIGUOUS"]:  # make sure it's contiguous
+        ar = np.ascontiguousarray(ar, dtype=np.uint8)
+    return ar.shape, memoryview(ar)

ipycanvas/canvas.py

@@ -12,6 +12,8 @@
 
 from ._frontend import module_name, module_version
 
+from .binary import array_to_binary
+
 
 def to_camel_case(snake_str):
     """Turn a snake_case string into a camelCase one."""
@@ -42,6 +44,7 @@ def __init__(self, *args, **kwargs):
         """Create a Canvas widget."""
         self.caching = kwargs.get('caching', False)
         self._commands_cache = []
+        self._buffers_cache = []
 
         super(Canvas, self).__init__(*args, **kwargs)
         self.layout.width = str(self.size[0]) + 'px'
@@ -50,19 +53,19 @@ def __init__(self, *args, **kwargs):
     # Rectangles methods
     def fill_rect(self, x, y, width, height):
         """Draw a filled rectangle."""
-        self._send_canvas_command('fillRect', x, y, width, height)
+        self._send_canvas_command('fillRect', (x, y, width, height))
 
     def stroke_rect(self, x, y, width, height):
         """Draw a rectangular outline."""
-        self._send_canvas_command('strokeRect', x, y, width, height)
+        self._send_canvas_command('strokeRect', (x, y, width, height))
 
     def clear_rect(self, x, y, width, height):
         """Clear the specified rectangular area, making it fully transparent."""
-        self._send_canvas_command('clearRect', x, y, width, height)
+        self._send_canvas_command('clearRect', (x, y, width, height))
 
     def rect(self, x, y, width, height):
         """Draw a rectangle whose top-left corner is specified by (x, y) with the specified width and height."""
-        self._send_canvas_command('rect', x, y, width, height)
+        self._send_canvas_command('rect', (x, y, width, height))
 
     # Paths methods
     def begin_path(self):
@@ -87,27 +90,27 @@ def fill(self):
 
     def move_to(self, x, y):
         """Move the "pen" to the given (x, y) coordinates."""
-        self._send_canvas_command('moveTo', x, y)
+        self._send_canvas_command('moveTo', (x, y))
 
     def line_to(self, x, y):
         """Add a straight line to the current path by connecting the path's last point to the specified (x, y) coordinates.
 
         Like other methods that modify the current path, this method does not directly render anything. To
         draw the path onto the canvas, you can use the fill() or stroke() methods.
         """
-        self._send_canvas_command('lineTo', x, y)
+        self._send_canvas_command('lineTo', (x, y))
 
     def arc(self, x, y, radius, start_angle, end_angle, anticlockwise=False):
         """Create a circular arc centered at (x, y) with a radius of radius.
 
         The path starts at startAngle and ends at endAngle, and travels in the direction given by
         anticlockwise (defaulting to clockwise).
         """
-        self._send_canvas_command('arc', x, y, radius, start_angle, end_angle, anticlockwise)
+        self._send_canvas_command('arc', (x, y, radius, start_angle, end_angle, anticlockwise))
 
     def arc_to(self, x1, y1, x2, y2, radius):
         """Add a circular arc to the current path, using the given control points and radius."""
-        self._send_canvas_command('arcTo', x1, y1, x2, y2, radius)
+        self._send_canvas_command('arcTo', (x1, y1, x2, y2, radius))
 
     def quadratic_curve_to(self, cp1x, cp1y, x, y):
         """Add a quadratic Bezier curve to the current path.
@@ -116,7 +119,7 @@ def quadratic_curve_to(self, cp1x, cp1y, x, y):
         The starting point is the latest point in the current path, which can be changed using move_to()
         before creating the quadratic Bezier curve.
         """
-        self._send_canvas_command('quadraticCurveTo', cp1x, cp1y, x, y)
+        self._send_canvas_command('quadraticCurveTo', (cp1x, cp1y, x, y))
 
     def bezier_curve_to(self, cp1x, cp1y, cp2x, cp2y, x, y):
         """Add a cubic Bezier curve to the current path.
@@ -125,16 +128,27 @@ def bezier_curve_to(self, cp1x, cp1y, cp2x, cp2y, x, y):
         The starting point is the latest point in the current path, which can be changed using move_to()
         before creating the Bezier curve.
         """
-        self._send_canvas_command('bezierCurveTo', cp1x, cp1y, cp2x, cp2y, x, y)
+        self._send_canvas_command('bezierCurveTo', (cp1x, cp1y, cp2x, cp2y, x, y))
 
     # Text methods
     def fill_text(self, text, x, y, max_width=None):
         """Fill a given text at the given (x,y) position. Optionally with a maximum width to draw."""
-        self._send_canvas_command('fillText', text, x, y, max_width)
+        self._send_canvas_command('fillText', (text, x, y, max_width))
 
     def stroke_text(self, text, x, y, max_width=None):
         """Stroke a given text at the given (x,y) position. Optionally with a maximum width to draw."""
-        self._send_canvas_command('strokeText', text, x, y, max_width)
+        self._send_canvas_command('strokeText', (text, x, y, max_width))
+
+    # Image methods
+    def put_image_data(self, image_data, dx, dy):
+        """Draw an image on the Canvas.
+
+        `image_data` being a NumPy array defining the image to draw
+        and `x` and `y` the pixel position where to draw.
+        This method is not affected by the canvas transformation matrix.
+        """
+        shape, image_buffer = array_to_binary(image_data)
+        self._send_canvas_command('putImageData', ({'shape': shape}, dx, dy), (image_buffer, ))
 
     def clear(self):
         """Clear the entire canvas."""
@@ -145,10 +159,11 @@ def flush(self):
         if not self.caching:
             return
 
-        self.send(self._commands_cache)
+        self.send(self._commands_cache, self._buffers_cache)
 
         self.caching = False
         self._commands_cache = []
+        self._buffers_cache = []
 
     @observe('fill_style', 'stroke_style', 'global_alpha', 'font', 'textAlign', 'textBaseline', 'direction')
     def _on_set_attr(self, change):
@@ -159,14 +174,20 @@ def _on_set_attr(self, change):
         }
         self._send_command(command)
 
-    def _send_canvas_command(self, name, *args):
-        self._send_command({'name': name, 'args': [arg for arg in args if arg is not None]})
+    def _send_canvas_command(self, name, args=[], buffers=[]):
+        command = {
+            'name': name,
+            'n_buffers': len(buffers),
+            'args': [arg for arg in args if arg is not None]
+        }
+        self._send_command(command, buffers)
 
-    def _send_command(self, command):
+    def _send_command(self, command, buffers=[]):
         if self.caching:
             self._commands_cache.append(command)
+            self._buffers_cache += buffers
         else:
-            self.send(command)
+            self.send(command, buffers)
 
 
 class MultiCanvas(DOMWidget):

setup.py

@@ -87,6 +87,7 @@
     include_package_data = True,
     install_requires = [
         'ipywidgets>=7.5.0',
+        'numpy'
     ],
     extras_require = {
         'examples': [

src/widget.ts

@@ -40,37 +40,67 @@ class CanvasModel extends DOMWidgetModel {
     this.on('msg:custom', this.onCommand.bind(this));
   }
 
-  private onCommand(command: any) {
-    this.processCommand(command);
+  private onCommand(command: any, buffers: any) {
+    this.processCommand(command, buffers);
 
     this.forEachView((view: CanvasView) => {
       view.updateCanvas();
     });
   }
 
-  private processCommand(command: any) {
+  private processCommand(command: any, buffers: any) {
     if (command instanceof Array) {
+      let remainingBuffers = buffers;
+
       for (const subcommand of command) {
-        this.processCommand(subcommand);
+        let subbuffers = [];
+        if (subcommand.n_buffers) {
+          subbuffers = remainingBuffers.slice(0, subcommand.n_buffers);
+          remainingBuffers = remainingBuffers.slice(subcommand.n_buffers)
+        }
+        this.processCommand(subcommand, subbuffers);
       }
       return;
     }
 
-    if (command.name == 'set') {
-      this.ctx[command.attr] = command.value;
-      return;
+    switch (command.name) {
+      case 'putImageData':
+        this.putImageData(command.args, buffers);
+        break;
+      case 'set':
+        this.setAttr(command.attr, command.value);
+        break;
+      case 'clear':
+        this.clearCanvas();
+        break;
+      default:
+        this.executeCommand(command.name, command.args);
+        break;
     }
+  }
 
-    if (command.name == 'clear') {
-      this.forEachView((view: CanvasView) => {
-        view.clear();
-      });
-      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+  private putImageData(args: any[], buffers: any) {
+    const [bufferMetadata, dx, dy] = args;
 
-      return;
-    }
+    const data = new Uint8ClampedArray(buffers[0].buffer);
+    const imageData = new ImageData(data, bufferMetadata.shape[1], bufferMetadata.shape[0]);
+
+    this.ctx.putImageData(imageData, dx, dy);
+  }
+
+  private setAttr(attr: string, value: any) {
+    this.ctx[attr] = value;
+  }
+
+  private clearCanvas() {
+    this.forEachView((view: CanvasView) => {
+      view.clear();
+    });
+    this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+  }
 
-    this.ctx[command.name](...command.args);
+  private executeCommand(name: string, args: any[]) {
+    this.ctx[name](...args);
   }
 
   private forEachView(callback: (view: CanvasView) => void) {