#+TITLE: Polygonsoup - Python

A collection of plotter-friendly utilities.

• Requirements The dependencies of this package depend on each module. The basic requirements for all modules are [[https://numpy.org/][NumPy]], [[https://www.scipy.org][SciPy]] and [[https://matplotlib.org][Matplotlib]].

** Module specific reqirements

• ~polyhonsoup.svg~ depends on [[https://github.com/mathandy/svgpathtools.git][svgpathtools]]
  • It is suggested to install the latest version with
    • ~pip install git+https://github.com/mathandy/svgpathtools.git~
• ~polygonsoup.clipper~ depends on the [[https://pypi.org/project/pyclipper/][PyClipper]] package.
  • It can be installed with
    • ~conda install -c conda-forge pyclipper~ if using conda
    • or ~pip install pyclipper~ if using pip.
• ~polygonsoup.limb~ depends on the [[https://github.com/neka-nat/kinpy][KinPy]] package, which in turn depends on [[https://vtk.org][VTK]]. The latest version of KinPy can be installed with pip through:
  • ~pip install git+https://github.com/neka-nat/kinpy.git~
  • If using Anaconda, it is suggested to first install VTK with
    • ~conda install -c conda-forge vtk~
• The ~polygonsoup.vtk_utils~ module and the relevant examples depend on VTK.
• The ~polygonsoup.plotters.AxiPlotter~ class depends on the [[https://github.com/fogleman/axi][axi]] Python package. Follow the instructions at the link to install.
• The ~polygonsoup.imaging~ module depends on OpenCV.

• Install To install locally use #+begin_example pip install -e . #+end_example From the ~py~ directory in the repository. This will create a symbolic link to the location of the ~py/polygonsoup~ directory, allowing a user to modify the source code if necessary.

• Usage Plotters basically can just trace 2D lines, so the main objects in this package are a polylines. Points, vectors, and matrices are represented as NumPy arrays. Polylines are represented as a list of points, or optionally as a ~N*D~ ~ndarray~, where ~N~ is the number of points and ~D~ is the number of coordinates (2 or 3 for a 3D polyline). A /compound/ polyline is a list of polylines.

*** ~geom~ The ~geom~ module contains utilities to process polylines (compound or not), as well as basic homogeneous transformation matrices. Points, polylines and compound polylines can be transformed with the same ~geom.affine_transform~ function. Creating a point or a vector can be done with the ~geom.vec~ function, which is simply a shorthand for creating a numpy array with its arguments. For example ~vec(0, 3)~ is equivalent to ~np.array([0, 3])~. These are examples of 2d points, polylines and compound polylines: #+begin_example python from polygonsoup.geom import vec

a 2d point

p = vec(0,0)

A polyline (a closed square)

P = [p, vec(10, 0), vec(10, 10), vec(0, 10), p]

or

P = np.array([p, vec(10, 0), vec(10, 10), vec(0, 10), p])

A compound polyline (the square and one diagonal)

S = [P, [p, vec(10,10)]] #+end_example Polylines can be specified as either lists of points or numpy arrays. While lists can be handy to concatenate points, the preferred format is numpy arrays with points as rows (e.g. a 10x2 array for 10 points) and many functions in this module will return this format.

**** 3D viewing This module also contains a basic line-based 3d graphics pipeline, which is implemented in the ~geom.view_3d~ function. The function transforms 3d polylines into 2d ones, given a view and a projection matrix. The projection can be either a perspective projection (~geom.perspective~) or parallel projection (~geom.parallel~).

*** ~plut~ (or ~plot~) The ~plut~ module enables visualisation and plotting of polylines with the same interface. Visualisation is done through matplotlib, while plotting is done with different interfaces exposed in the ~plotters~ module. Polylines and compound polylines can be plotted with the ~plot.stroke~ function. A barebones visualisation example of a polyline is the following: #+begin_example python import polygonsoup.plot as plut import numpy as np plut.figure('A5') # Create a figure with A5 size plut.stroke(np.random.uniform(-5, 5, (2, 10))) plut.show() #+end_example This displays a random 2D polyline with 10 points. The code between ~figure~ and ~show~ can contain common ~matplotlib~ calls. These will be displayed in the resulting image, but not on the drawing made by the plotter.

The same module provides a ~plut.show_drawing~ function. This takes an ~axi.Drawing~ as an input and allows to plot and visualise outputs generated with the ~axi~ package. As an example of the use of this function refer to [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/axi_lsystem.py][examples/axi_lsystem.py]]. A similar approach can be used to easily convert (and plot) the other nice examples in ~axi~.

*** ~plotters~ This module exposes interfaces that allow plotting with AxiDraw. These can be passed with the ~plotter~ argument to the ~plot.figure~ function, which will also send the polylines following the call to the plotter. The ~AxiPlotter~ class requires an AxiDraw to be connected to the computer, and uses the [[https://github.com/fogleman/axi][axi]] package for communicating with the plotter. The ~AxiDrawClient~ connects to a running instance of the [[https://github.com/colormotor/polygonsoup/tree/main/py/server][axidraw_server]] script. The ~NoPlotter~ class is the default, which is used to display graphics only. This can be useful when testing the output of a script. As an example, plotting the minimal example above when connected to an AxiDraw can be done with: #+begin_example python import polygonsoup.plot as plot import polygonsoup.plotters as plotters import numpy as np plot.figure('A5', plotter=plotters.AxiPlotter()) # Create a figure with A5 size, send to AxiPlotter plot.stroke(np.random.uniform(-5, 5, (2, 10))) plot.show() #+end_example

*** ~clipper~ This module provides utilities to clip or to perform boolean operations with polylines. It simply wraps the [[http://www.angusj.com/delphi/clipper.php][Clipper]] library and requires the [[https://pypi.org/project/pyclipper/][PyClipper]] package to be installed. See [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/boolean_ops.py][examples/boolean_ops.py]] for a usage example.

*** ~bezier~ This module contains utilities to generate Bezier curves.

*** ~svg~ This module provides utilities to load SVG files. To load a file as a compound polyline: #+begin_example python import polygonsoup.svg as svg S = svg.load_svg('filename.svg') #+end_example See [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/svg_example.py][examples/svg_example.py]] for a usage example.

*** ~hatch~ This module implements hatching, which can be used to "fill" a shape with lines. The input to the method is assumed to be closed, and filling of compound shapes follows the [[https://en.wikipedia.org/wiki/Even–odd_rule]["Even-odd"]] rule. See [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/cubes_hatch.py][examples/cubes_hatch.py]] for a usage example.

*** ~vtk_utils~ This module exposes some of the functionalities of the Visualization Toolkit (VTK), a powerful library for 3d geometry processing. See [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/vtk_contour_lines.py][examples/vtk_contour_lines.py]] and [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/vtk_silhouette.py][examples/vtk_silhouette.py]] for usage examples.

*** ~limb~ The limb module provides utilities to perform forward and inverse kinematics on a kinematic chain. The chain can be loaded from a URDF or SDF file with the ~limb.Limb~ class. The module wraps relies on the [[https://github.com/neka-nat/kinpy][KinPy]] package for loading, forward kinematics and Jacobian computation, while the ~Limb~ class provides two functions to compute inverse kinematics (~ik~ and ~ik_soft~). See [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/forward_kinematics.py][examples/forward_kinematics.py]] and [[https://github.com/colormotor/polygonsoup/blob/main/py/examples/inverse_kinematics.py][examples/inverse_kinematics.py]] for usage examples.