Add filter property

Author: martinRenou

dev-environment.yml

@@ -11,4 +11,4 @@ dependencies:
     - wheel
     - twine
     - jupytext
-    - black=21
+    - black=22.1.0

docs/source/images/filter.png

@@ -140,6 +140,82 @@ Then use it as a ``fill_style`` or ``stroke_style``:
 
 .. image:: images/pattern.png
 
+Filters
+-------
+
+You can apply filters such as blurring and grayscaling to your drawings using the ``filter`` property. This property is similar to the filter CSS property and accepts the same values.
+
+The ``filter`` property is a ``string`` with the following syntax:
+
+.. code:: Python
+
+    canvas.filter = '<filter-function1> [<filter-function2>] [<filter-functionN>]'
+    canvas.filter = 'none'
+
+The following filter functions are supported:
+
+- ``url()``:
+    A CSS url(). Takes an IRI pointing to an SVG filter element, which may be embedded in an external XML file.
+
+- ``blur()``:
+    A CSS <length>. Applies a Gaussian blur to the drawing. It defines the value of the standard deviation to the Gaussian function, i.e., how many pixels on the screen blend into each other; thus, a larger value will create more blur. A value of 0 leaves the input unchanged.
+
+- ``brightness()``:
+    A CSS <percentage>. Applies a linear multiplier to the drawing, making it appear brighter or darker. A value under 100% darkens the image, while a value over 100% brightens it. A value of 0% will create an image that is completely black, while a value of 100% leaves the input unchanged.
+
+- ``contrast()``:
+    A CSS <percentage>. Adjusts the contrast of the drawing. A value of 0% will create a drawing that is completely black. A value of 100% leaves the drawing unchanged.
+
+- ``drop-shadow()``:
+    Applies a drop shadow effect to the drawing. A drop shadow is effectively a blurred, offset version of the drawing's alpha mask drawn in a particular color, composited below the drawing. This function takes up to five arguments:
+
+    - <offset-x>: Specifies the horizontal distance of the shadow.
+    - <offset-y>: Specifies the vertical distance of the shadow.
+    - <blur-radius>: The larger this value, the bigger the blur, so the shadow becomes bigger and lighter. Negative values are not allowed.
+    - <color>: The shadow color.
+
+- ``grayscale()``:
+    A CSS <percentage>. Converts the drawing to grayscale. A value of 100% is completely grayscale. A value of 0% leaves the drawing unchanged.
+
+- ``hue-rotate()``:
+    A CSS <angle>. Applies a hue rotation on the drawing. A value of 0deg leaves the input unchanged.
+
+- ``invert()``:
+    A CSS <percentage>. Inverts the drawing. A value of 100% means complete inversion. A value of 0% leaves the drawing unchanged.
+
+- ``opacity()``:
+    A CSS <percentage>. Applies transparency to the drawing. A value of 0% means completely transparent. A value of 100% leaves the drawing unchanged.
+
+- ``saturate()``:
+    A CSS <percentage>. Saturates the drawing. A value of 0% means completely un-saturated. A value of 100% leaves the drawing unchanged.
+
+- ``sepia()``:
+    A CSS <percentage>. Converts the drawing to sepia. A value of 100% means completely sepia. A value of 0% leaves the drawing unchanged.
+
+- ``none``:
+    No filter is applied. Initial value.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(width=400, height=300)
+
+    canvas.fill_style = 'green'
+    canvas.filter = 'blur(1px) contrast(1.4) drop-shadow(-9px 9px 3px #e81)'
+    canvas.font = '48px serif'
+    canvas.fill_text('Hello world!', 20, 150)
+
+    canvas
+
+.. image:: images/filter.png
+
+.. warning::
+    Applying a filter can be slow, especially if you draw many shapes.
+
+.. danger::
+    This property is **not supported by Safari and Internet Explorer**
+
 RoughCanvas
 -----------
 

docs/source/styles_and_colors.rst

@@ -46,6 +46,20 @@
     "canvas.fill_rects(x, y, size)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "blurred_canvas = Canvas(width=800, height=500)\n",
+    "blurred_canvas.filter = \"blur(1px) drop-shadow(-9px 9px 3px #e81)\"\n",
+    "\n",
+    "blurred_canvas.draw_image(canvas)\n",
+    "\n",
+    "blurred_canvas"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -206,7 +220,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.10.2"
   }
  },
  "nbformat": 4,

examples/particle_system.ipynb

@@ -531,7 +531,7 @@
     "x = np.linspace(-5, 5, 100)\n",
     "y = np.linspace(-5, 5, 100)\n",
     "x_grid, y_grid = np.meshgrid(x, y)\n",
-    "color = np.sin(x_grid + y_grid ** 2) + np.cos(x_grid ** 2 + y_grid ** 2)\n",
+    "color = np.sin(x_grid + y_grid**2) + np.cos(x_grid**2 + y_grid**2)\n",
     "\n",
     "HeatmapPlot(x, y, color, scheme=branca.colormap.linear.RdYlBu_05)"
    ]

examples/plotting.ipynb

@@ -514,6 +514,10 @@ class Canvas(_CanvasBase):
     #: the junction becomes. Default to ``10.``.
     miter_limit = Float(10.0)
 
+    #: (str) Filter effects such as blurring and grayscaling. It is similar to the CSS filter property and accepts the same values.
+    #: This property has no effect on Safari, see https://bugs.webkit.org/show_bug.cgi?id=198416
+    filter = Unicode("none")
+
     _line_dash = List()
 
     #: (float) Specifies where to start a dash array on a line. Default is ``0.``.
@@ -549,6 +553,7 @@ class Canvas(_CanvasBase):
         "shadow_offset_y": 14,
         "shadow_blur": 15,
         "shadow_color": 16,
+        "filter": 17,
     }
 
     def __init__(self, *args, **kwargs):

ipycanvas/canvas.py

@@ -264,6 +264,7 @@ class CanvasModel extends DOMWidgetModel {
     'textBaseline', 'direction', 'globalCompositeOperation',
     'lineWidth', 'lineCap', 'lineJoin', 'miterLimit', 'lineDashOffset',
     'shadowOffsetX', 'shadowOffsetY', 'shadowBlur', 'shadowColor',
+    'filter',
   ];
 
   initialize(attributes: any, options: any) {
@@ -637,7 +638,7 @@ class CanvasModel extends DOMWidgetModel {
     // a scalar
     const numPolygons = args[0];
 
-    // always array 
+    // always array
     const points = getArg(args[1], buffers);
 
     // array or scalar
@@ -666,7 +667,7 @@ class CanvasModel extends DOMWidgetModel {
         this.ctx.beginPath();
         this.ctx.moveTo(points.getItem(start), points.getItem(start+1));
 
-        // draw all points of the polygon (except start) 
+        // draw all points of the polygon (except start)
         for(let idp = start+2; idp < stop; idp += 2){
           this.ctx.lineTo(points.getItem(idp), points.getItem(idp + 1));
         }
@@ -684,7 +685,7 @@ class CanvasModel extends DOMWidgetModel {
     // a scalar
     const numPolygons = args[0];
 
-    // always array 
+    // always array
     const points = getArg(args[1], buffers);
 
     // array or scalar
@@ -701,7 +702,7 @@ class CanvasModel extends DOMWidgetModel {
         this.ctx.beginPath();
         this.ctx.moveTo(points.getItem(start), points.getItem(start+1));
 
-        // draw all points of the polygon (except start) 
+        // draw all points of the polygon (except start)
         for(let idp = start+2; idp < stop; idp += 2){
           this.ctx.lineTo(points.getItem(idp), points.getItem(idp + 1));
         }