Add docs for polygon

Signed-off-by: martinRenou <[email protected]>

Author: martinRenou

docs/source/drawing_shapes.rst

@@ -68,6 +68,62 @@ You can also clear a certain canvas rectangle area:
 
 .. image:: images/rects.png
 
+Drawing polygons
+----------------
+
+You can draw a polygon by providing a list of points, either a Python list, or a NumPy array.
+It's the fastest way to draw a polygon with ipycanvas.
+
+- ``fill_polygon(points)``: Fill a polygon from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
+- ``stroke_polygon(points)``: Draw polygon outline from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(width=200, height=200)
+
+    canvas.fill_style = '#63934e'
+    canvas.stroke_style = '#4e6393'
+    canvas.line_width = 5
+    canvas.fill_polygon([(20, 20), (180, 20), (100, 150)])
+    canvas.stroke_polygon([(20, 20), (180, 20), (100, 150)])
+
+    canvas
+
+.. image:: images/polygon.png
+
+.. code:: Python
+
+    from math import pi
+    import numpy as np
+    from ipycanvas import Canvas
+
+    def polygon(canvas, x, y, radius, n_points):
+        angles = (2 * pi / n_points) * np.arange(n_points)
+
+        v_x = x + np.cos(angles) * radius
+        v_y = y + np.sin(angles) * radius
+
+        points = np.stack((v_x, v_y), axis=1)
+
+        canvas.fill_polygon(points)
+
+    background_color = '#89c64f'
+    polygon_color = '#c6574f'
+
+    canvas = Canvas(width=200, height=200)
+
+    canvas.fill_style = background_color
+    canvas.fill_rect(0, 0, canvas.width, canvas.height)
+
+    canvas.fill_style = polygon_color
+    polygon(canvas, 100, 100, 70, 6)
+
+    canvas
+
+.. image:: images/polygon_numpy.png
+
 Drawing arcs and circles
 ------------------------
 
@@ -168,4 +224,4 @@ instead of running:
 
         canvas.fill_rect(position, position, size)
 
-    canvas
+    canvas

docs/source/images/polygon.png

@@ -0,0 +1,101 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipycanvas import Canvas\n",
+    "\n",
+    "canvas = Canvas(width=200, height=200)\n",
+    "\n",
+    "canvas.fill_style = '#63934e'\n",
+    "canvas.stroke_style = '#4e6393'\n",
+    "canvas.line_width = 5\n",
+    "canvas.fill_polygon([(20, 20), (180, 20), (100, 150)])\n",
+    "canvas.stroke_polygon([(20, 20), (180, 20), (100, 150)])\n",
+    "\n",
+    "canvas"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from math import pi\n",
+    "\n",
+    "import numpy as np\n",
+    "\n",
+    "from ipycanvas import Canvas"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def polygon(canvas, x, y, radius, n_points):\n",
+    "    angles = (2 * pi / n_points) * np.arange(n_points)\n",
+    "\n",
+    "    v_x = x + np.cos(angles) * radius\n",
+    "    v_y = y + np.sin(angles) * radius\n",
+    "\n",
+    "    points = np.stack((v_x, v_y), axis=1)\n",
+    "\n",
+    "    canvas.fill_polygon(points)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "background_color = '#89c64f'\n",
+    "polygon_color = '#c6574f'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "canvas = Canvas(width=500, height=500)\n",
+    "\n",
+    "canvas.fill_style = background_color\n",
+    "canvas.fill_rect(0, 0, canvas.width, canvas.height)\n",
+    "\n",
+    "canvas.fill_style = polygon_color\n",
+    "polygon(canvas, 250, 250, 100, 6)\n",
+    "\n",
+    "canvas"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}