Merge pull request #153 from martinRenou/polygon_docs

Update docs

Author: martinRenou

README.md

@@ -19,6 +19,10 @@ You can try it online by clicking on this badge:
 
 You can read the documentation following this link: https://ipycanvas.readthedocs.io
 
+## Questions?
+
+If you have any question, or if you want to share what you do with ipycanvas, [start a new discussion on Github](https://github.com/martinRenou/ipycanvas/discussions/new)!
+
 ## Installation
 
 You can install using `pip`:

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
 ------------------------
 
@@ -105,9 +161,10 @@ There are methods that draw arcs/circles on the canvas:
 Drawing lines
 -------------
 
-There is one command for drawing a straight line from one point to another:
+There are two commands for drawing a straight line from one point to another:
 
 - ``stroke_line(x1, y1, x2, y2)``: Draw a line from ``(x1, y1)`` to ``(x2, y2)``.
+- ``stroke_lines(points)``: Draw a path of consecutive lines from a list of points ``[(x1, y1), (x2, y2), ..., (xn, yn)]``.
 
 .. code:: Python
 
@@ -128,6 +185,26 @@ There is one command for drawing a straight line from one point to another:
 
 .. image:: images/lines.png
 
+.. code:: Python
+
+    import numpy as np
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(width=200, height=200)
+
+    n = 50
+    x = np.linspace(0, 200, n)
+    y = np.random.randint(200, size=n)
+
+    points = np.stack((x, y), axis=1)
+
+    canvas.stroke_lines(points)
+
+    canvas
+
+.. image:: images/stroke_lines.png
+
 
 Vectorized methods
 ------------------
@@ -168,4 +245,4 @@ instead of running:
 
         canvas.fill_rect(position, position, size)
 
-    canvas
+    canvas

docs/source/images/polygon.png

@@ -14,6 +14,11 @@ You can try ipycanvas, without the need of installing anything on your computer,
 .. image:: https://img.shields.io/badge/start-drawing!-F5A252.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFkAAABZCAMAAABi1XidAAAB8lBMVEX///9XmsrmZYH1olJXmsr1olJXmsrmZYH1olJXmsr1olJXmsrmZYH1olL1olJXmsr1olJXmsrmZYH1olL1olJXmsrmZYH1olJXmsr1olL1olJXmsrmZYH1olL1olJXmsrmZYH1olL1olL0nFf1olJXmsrmZYH1olJXmsq8dZb1olJXmsrmZYH1olJXmspXmspXmsr1olL1olJXmsrmZYH1olJXmsr1olL1olJXmsrmZYH1olL1olLeaIVXmsrmZYH1olL1olL1olJXmsrmZYH1olLna31Xmsr1olJXmsr1olJXmsrmZYH1olLqoVr1olJXmsr1olJXmsrmZYH1olL1olKkfaPobXvviGabgadXmsqThKuofKHmZ4Dobnr1olJXmsr1olJXmspXmsr1olJXmsrfZ4TuhWn1olL1olJXmsqBi7X1olJXmspZmslbmMhbmsdemsVfl8ZgmsNim8Jpk8F0m7R4m7F5nLB6jbh7jbiDirOEibOGnKaMhq+PnaCVg6qWg6qegKaff6WhnpKofKGtnomxeZy3noG6dZi+n3vCcpPDcpPGn3bLb4/Mb47UbIrVa4rYoGjdaIbeaIXhoWHmZYHobXvpcHjqdHXreHLroVrsfG/uhGnuh2bwj2Hxk17yl1vzmljzm1j0nlX1olL3AJXWAAAAbXRSTlMAEBAQHx8gICAuLjAwMDw9PUBAQEpQUFBXV1hgYGBkcHBwcXl8gICAgoiIkJCQlJicnJ2goKCmqK+wsLC4usDAwMjP0NDQ1NbW3Nzg4ODi5+3v8PDw8/T09PX29vb39/f5+fr7+/z8/Pz9/v7+zczCxgAABC5JREFUeAHN1ul3k0UUBvCb1CTVpmpaitAGSLSpSuKCLWpbTKNJFGlcSMAFF63iUmRccNG6gLbuxkXU66JAUef/9LSpmXnyLr3T5AO/rzl5zj137p136BISy44fKJXuGN/d19PUfYeO67Znqtf2KH33Id1psXoFdW30sPZ1sMvs2D060AHqws4FHeJojLZqnw53cmfvg+XR8mC0OEjuxrXEkX5ydeVJLVIlV0e10PXk5k7dYeHu7Cj1j+49uKg7uLU61tGLw1lq27ugQYlclHC4bgv7VQ+TAyj5Zc/UjsPvs1sd5cWryWObtvWT2EPa4rtnWW3JkpjggEpbOsPr7F7EyNewtpBIslA7p43HCsnwooXTEc3UmPmCNn5lrqTJxy6nRmcavGZVt/3Da2pD5NHvsOHJCrdc1G2r3DITpU7yic7w/7Rxnjc0kt5GC4djiv2Sz3Fb2iEZg41/ddsFDoyuYrIkmFehz0HR2thPgQqMyQYb2OtB0WxsZ3BeG3+wpRb1vzl2UYBog8FfGhttFKjtAclnZYrRo9ryG9uG/FZQU4AEg8ZE9LjGMzTmqKXPLnlWVnIlQQTvxJf8ip7VgjZjyVPrjw1te5otM7RmP7xm+sK2Gv9I8Gi++BRbEkR9EBw8zRUcKxwp73xkaLiqQb+kGduJTNHG72zcW9LoJgqQxpP3/Tj//c3yB0tqzaml05/+orHLksVO+95kX7/7qgJvnjlrfr2Ggsyx0eoy9uPzN5SPd86aXggOsEKW2Prz7du3VID3/tzs/sSRs2w7ovVHKtjrX2pd7ZMlTxAYfBAL9jiDwfLkq55Tm7ifhMlTGPyCAs7RFRhn47JnlcB9RM5T97ASuZXIcVNuUDIndpDbdsfrqsOppeXl5Y+XVKdjFCTh+zGaVuj0d9zy05PPK3QzBamxdwtTCrzyg/2Rvf2EstUjordGwa/kx9mSJLr8mLLtCW8HHGJc2R5hS219IiF6PnTusOqcMl57gm0Z8kanKMAQg0qSyuZfn7zItsbGyO9QlnxY0eCuD1XL2ys/MsrQhltE7Ug0uFOzufJFE2PxBo/YAx8XPPdDwWN0MrDRYIZF0mSMKCNHgaIVFoBbNoLJ7tEQDKxGF0kcLQimojCZopv0OkNOyWCCg9XMVAi7ARJzQdM2QUh0gmBozjc3Skg6dSBRqDGYSUOu66Zg+I2fNZs/M3/f/Grl/XnyF1Gw3VKCez0PN5IUfFLqvgUN4C0qNqYs5YhPL+aVZYDE4IpUk57oSFnJm4FyCqqOE0jhY2SMyLFoo56zyo6becOS5UVDdj7Vih0zp+tcMhwRpBeLyqtIjlJKAIZSbI8SGSF3k0pA3mR5tHuwPFoa7N7reoq2bqCsAk1HqCu5uvI1n6JuRXI+S1Mco54YmYTwcn6Aeic+kssXi8XpXC4V3t7/ADuTNKaQJdScAAAAAElFTkSuQmCC
    :target: https://mybinder.org/v2/gh/martinRenou/ipycanvas/stable?filepath=examples
 
+Questions?
+----------
+
+If you have any question, or if you want to share what you do with ipycanvas, come `start a new discussion on Github <https://github.com/martinRenou/ipycanvas/discussions/new>`_!
+
 Index
 -----
 

docs/source/images/polygon_numpy.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
+}