"svgpathtools is a collection of tools for manipulating and analyzing SVG Path objects and Bézier curves.\n",
"\n",
"## Features\n",
"\n",
"svgpathtools contains functions designed to **easily read, write and display SVG files** as well as *a large selection of geometrically\\-oriented tools* to **transform and analyze path elements**.\n",
"\n",
"Additionally, the submodule *bezier.py* contains tools for for working with general **nth order Bezier curves stored as n-tuples**.\n",
"- convert Bézier path segments to **numpy.poly1d** (polynomial) objects\n",
"- convert polynomials (in standard form) to their Bézier form\n",
"- compute **tangent vectors** and (right-hand rule) **normal vectors**\n",
"- compute **curvature**\n",
"- break discontinuous paths into their **continuous subpaths**.\n",
"- efficiently compute **intersections** between paths and/or segments\n",
"- find a **bounding box** for a path or segment\n",
"- **reverse** segment/path orientation\n",
"- **crop** and **split** paths and segments\n",
"- **smooth** paths (i.e. smooth away kinks to make paths differentiable)\n",
"- **transition maps** from path domain to segment domain and back (T2t and t2T)\n",
"- compute **area** enclosed by a closed path\n",
"- compute **arc length**\n",
"- compute **inverse arc length**\n",
"- convert RGB color tuples to hexadecimal color strings and back\n",
"\n",
"## Prerequisites\n",
"- **numpy**\n",
"- **svgwrite**\n",
"\n",
"## Setup\n",
"\n",
"If not already installed, you can **install the prerequisites** using pip.\n",
"\n",
"```bash\n",
"$ pip install numpy\n",
"```\n",
"\n",
"```bash\n",
"$ pip install svgwrite\n",
"```\n",
"\n",
"Then **install svgpathtools**:\n",
"```bash\n",
"$ pip install svgpathtools\n",
"``` \n",
" \n",
"### Alternative Setup \n",
"You can download the source from Github and install by using the command (from inside the folder containing setup.py):\n",
"\n",
"```bash\n",
"$ python setup.py install\n",
"```\n",
"\n",
"## Credit where credit's due\n",
"Much of the core of this module was taken from [the svg.path (v2.0) module](https://github.com/regebro/svg.path). Interested svg.path users should see the compatibility notes at bottom of this readme.\n",
"\n",
"## Basic Usage\n",
"\n",
"### Classes\n",
"The svgpathtools module is primarily structured around four path segment classes: ``Line``, ``QuadraticBezier``, ``CubicBezier``, and ``Arc``. There is also a fifth class, ``Path``, whose objects are sequences of (connected or disconnected<sup id=\"a1\">[1](#f1)</sup>) path segment objects.\n",
"\n",
"* ``Line(start, end)``\n",
"\n",
"* ``Arc(start, radius, rotation, large_arc, sweep, end)`` Note: See docstring for a detailed explanation of these parameters\n",
"See the relevant docstrings in *path.py* or the [official SVG specifications](<http://www.w3.org/TR/SVG/paths.html>) for more information on what each parameter means.\n",
"\n",
"<u id=\"f1\">1</u> Warning: Some of the functionality in this library has not been tested on discontinuous Path objects. A simple workaround is provided, however, by the ``Path.continuous_subpaths()`` method. [↩](#a1)"
"# Let's take a quick look at the path and its smoothed relative\n",
"# The following commands will open two browser windows to display path and spaths\n",
"from svgpathtools import disvg\n",
"from time import sleep\n",
"disvg(path) \n",
"sleep(1) # needed when not giving the SVGs unique names (or not using timestamp)\n",
"disvg(spath)\n",
"print(\"Notice that path contains {} segments and spath contains {} segments.\"\n",
" \"\".format(len(path), len(spath)))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Reading SVGSs\n",
"\n",
"The **svg2paths()** function converts an svgfile to a list of Path objects and a separate list of dictionaries containing the attributes of each said path. \n",
"Note: Line, Polyline, Polygon, and Path SVG elements can all be converted to Path objects using this function."
"# Let's print out the first path object and the color it was in the SVG\n",
"# We'll see it is composed of two CubicBezier objects and, in the SVG file it \n",
"# came from, it was red\n",
"redpath = paths[0]\n",
"redpath_attribs = attributes[0]\n",
"print(redpath)\n",
"print(redpath_attribs['stroke'])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Writing SVGSs (and some geometric functions and methods)\n",
"\n",
"The **wsvg()** function creates an SVG file from a list of path. This function can do many things (see docstring in *paths2svg.py* for more information) and is meant to be quick and easy to use.\n",
"Note: Use the convenience function **disvg()** (or set 'openinbrowser=True') to automatically attempt to open the created svg file in your default SVG viewer."
"There will be many more examples of writing and displaying path data below.\n",
"\n",
"### The .point() method and transitioning between path and path segment parameterizations\n",
"SVG Path elements and their segments have official parameterizations.\n",
"These parameterizations can be accessed using the ``Path.point()``, ``Line.point()``, ``QuadraticBezier.point()``, ``CubicBezier.point()``, and ``Arc.point()`` methods.\n",
"All these parameterizations are defined over the domain 0 <= t <= 1.\n",
"\n",
"**Note:** In this document and in inline documentation and doctrings, I use a capital ``T`` when referring to the parameterization of a Path object and a lower case ``t`` when referring speaking about path segment objects (i.e. Line, QaudraticBezier, CubicBezier, and Arc objects). \n",
"Given a ``T`` value, the ``Path.T2t()`` method can be used to find the corresponding segment index, ``k``, and segment parameter, ``t``, such that ``path.point(T)=path[k].point(t)``. \n",
"There is also a ``Path.t2T()`` method to solve the inverse problem."
"### Bezier curves as NumPy polynomial objects\n",
"Another great way to work with the parameterizations for `Line`, `QuadraticBezier`, and `CubicBezier` objects is to convert them to ``numpy.poly1d`` objects. This is done easily using the ``Line.poly()``, ``QuadraticBezier.poly()`` and ``CubicBezier.poly()`` methods. \n",
"There's also a ``polynomial2bezier()`` function in the pathtools.py submodule to convert polynomials back to Bezier curves. \n",
"\n",
"**Note:** cubic Bezier curves are parameterized as $$\\mathcal{B}(t) = P_0(1-t)^3 + 3P_1(1-t)^2t + 3P_2(1-t)t^2 + P_3t^3$$\n",
"where $P_0$, $P_1$, $P_2$, and $P_3$ are the control points ``start``, ``control1``, ``control2``, and ``end``, respectively, that svgpathtools uses to define a CubicBezier object. The ``CubicBezier.poly()`` method expands this polynomial to its standard form \n",
"The ability to convert between Bezier objects to NumPy polynomial objects is very useful. For starters, we can take turn a list of Bézier segments into a NumPy array \n",
"### Numpy Array operations on Bézier path segments\n",
"[Example available here](https://github.com/mathandy/svgpathtools/blob/master/examples/compute-many-points-quickly-using-numpy-arrays.py)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To further illustrate the power of being able to convert our Bezier curve objects to numpy.poly1d objects and back, lets compute the unit tangent vector of the above CubicBezier object, b, at t=0.5 in four different ways.\n",
"Here we'll create an SVG that shows off the parametric and geometric midpoints of the paths from ``test.svg``. We'll need to compute use the ``Path.length()``, ``Line.length()``, ``QuadraticBezier.length()``, ``CubicBezier.length()``, and ``Arc.length()`` methods, as well as the related inverse arc length methods ``.ilength()`` function to do this."
"## Compatibility Notes for users of svg.path (v2.0)\n",
"\n",
"- renamed Arc.arc attribute as Arc.large_arc\n",
"\n",
"- Path.d() : For behavior similar<sup id=\"a2\">[2](#f2)</sup> to svg.path (v2.0), set both useSandT and use_closed_attrib to be True.\n",
"\n",
"<u id=\"f2\">2</u> The behavior would be identical, but the string formatting used in this method has been changed to use default format (instead of the General format, {:G}), for inceased precision. [↩](#a2)\n",
