spiropath

Generalized Spirograph program allowing using arbitrary rotating and stationary shapes specified as SVG paths.

Installing

To install:

cargo install spiropath

Using

This crate installs a spiropath program you can directly invoke from the command line: spiropath -s stationary.svg -r rotating.svg -o output.svg, where stationary.svg contains a single SVG path for the stationary shape and rotating.svg contains a single SVG path for the shape rotating around it. The output SVG file will contain a single polyline tracing the path of a point affixed to the rotating shape as it is moved around the rotating shape.

In addition this crate provides the same functionality (sans the file input/output) as a spiropath::spiropath library function you can use in your own code.

A "classical" Spirograph uses only circles for both the stationary and rotating shapes. Some Spirograph programs (or physical sets) provide more shapes but in general these shapes are restricted to a combination of lines and arcs, and the overall configuration (even in programs) is restricted by physics (e.g. the traced point must be internal to the rotating shape).

In contrast, Spiropath places no restrictions on the stationary and rotating shapes (other than requiring them to be continuous closed paths), or the position of the traced point: the rotating shape is moved around the stationary one ignoring any collisions, and the traced point is moved with it. You can therefore not only specify shapes using any cubic curves (rather than being restricted to lines and arcs), but you can also use non-convex (or even self-intersecting) shapes, and in general specify configurations which are impossible to achieve using a physical spirograph device (e.g. placing the trace point outside the rotating shape).

In general the output SVG is expected to be further processed before the final visualization (e.g. using Inkscape, so Spiropath doesn't provide options to control the path's color, style, width, etc.

Spiropath does provide options to specify the relative sizes of the stationary and the rotating shapes (the number of "teeth" along each of the shapes), the accuracy tolerance (as a fraction of the tooth size), the size of the output (its bounding box), the initial rotation and offsets of the rotating shape, the position of the traced point in the coordinates of the rotated shape, and whether the rotating shape is placed "inside" or "outside" the stationary shape.

The resulting polyline will have a "lot" of points (depending on the tolerance); ideally we'd convert it to a compact representation using SVG path elements such as arcs and curves. However, I couldn't find a Rust library to do this. If you are aware of one, please let me know.

In the meanwhile, you can use external tools, for example using Inkscape to either manually simplify the path as described in the "Simplification" section here or automate this as described here.

License

spiropath is distributed under the GNU AFFERO General Public License (Version 3.0). See the LICENSE for details.