SVGPathCommander

A modern set of ES6/ES7 JavaScript tools for manipulating SVGPathElement description attribute. This library was developed to try and solve over-optimized arcTo segment strings and provide a solid solution to parse, convert and reverse SVGPathElement draw direction.

This library is made possible thanks to Raphael.js, SvgPath, Paper.js and is used by KUTE.js for SVG path morphing.

Install

npm install svg-path-commander

CDN

Find SVGPathCommander on jsDelivr.

Usage

On a regular basis, you can import, initialize and access methods, or return the values right away.

// import the constructor
import SVGPathCommander from 'svg-path-commander'

let pathString = 'M0 0l50 0l50 50z';

// initializing
let mySVGPathCommanderInit = new SVGPathCommander(pathString);
/* returns => {
  segments: [ ['M',0,0], ['l',50,0], ['l',50,50], ['z'] ]
}
*/

// reuse same init object to call different methods
// for instance convert to ABSOLUTE and return the string path
mySVGPathCommanderInit.toAbsolute().toString()

// or convert to RELATIVE and return the string path
mySVGPathCommanderInit.toRelative().toString()

// reverse and return the string path
mySVGPathCommanderInit.reverse().toString()

// ONLY reverse subpaths and return the string path
// if the shape has no sub-path, this call will produce no effect
mySVGPathCommanderInit.reverse(1).toString()

// converts to both absolute and relative then return the shorter segment string
mySVGPathCommanderInit.optimize().toString()

// or return directly what you need
let mySVGAbsolutePath = new SVGPathCommander(pathString).reverse(1).optimize().toString()

Advanced Usage

In some cases, you can also import only the tool you need, without importing the entire library.

import pathToAbsolute from 'svg-path-commander/src/convert/pathToAbsolute.js'
import pathToString from 'svg-path-commander/src/convert/pathToString.js'

let mySVGAbsolutePath = pathToString(pathToAbsolute(pathString))

Tools

When using the library as a package, type in "SVGPathCommander." in your browser console and have a look, there are a wide range of tools to play with. Here are some notable utilities:

• SVGPathCommander.parsePathString(pathString) - returns a pathArray and is used by/for most of SVGPathCommander conversion tools
• SVGPathCommander.pathToAbsolute(pathString|pathArray) - returns a new pathArray having all path commands as absolute coordinates
• SVGPathCommander.pathToRelative(pathString|pathArray) - returns a new pathArray having all path commands as relative coordinates
• SVGPathCommander.pathToCurve(pathString|pathArray) - returns a new pathArray having all path commands converted to cubicBezierTo (C) path commands
• SVGPathCommander.clonePath(pathArray) - returns a deep clone of a pathArray, which is the result of any of the above functions
• SVGPathCommander.roundPath(pathArray) - returns a new pathArray with all path command values rounded to 3 decimals by default
• SVGPathCommander.reversePath(pathString|pathArray) - returns a new pathArray with all path commands having absolute values and in reverse order, but only for a single M->Z shape, for SVGPathElement items with sub-path, you need to use pathToAbsolute -> pathToString -> splitPath -> reversePath for each subpath
• SVGPathCommander.optimizePath(pathArray) - returns a new pathArray with all segments that have the shortest strings from either absolute or relative pathArray segments
• SVGPathCommander.getDrawDirection(pathCurve) - returns TRUE if a shape draw direction is clockwise, it should not be used for shapes with sub-paths, but each sub-path individually
• SVGPathCommander.splitPath(pathString) - returns an Array of sub-path strings

Some Technical Considerations

• the optimize() method will only return the shortest segment string of the pathArray, it will not simplify/merge the path commands; to do that you can use SVGO and its convertPathData plugin;
• all tools processing path segments will always round float values to 3 decimals, remember: only float numbers; EG: 0.5666 => 0.566, 0.50 => 0.5, 5 => 5; you can change the default option with SVGPathCommander.options.decimals = 2 or remove the value rounding all together with SVGPathCommander.options.round = 0.

Special Thanks

• Dmitry Baranovskiy for his Raphael.js
• Vitaly Puzrin & Alex Kocharin for their SvgPath
• Jürg Lehni & Jonathan Puckey for their Paper.js
• Andrew Willems for his awesome guide
• Mike 'Pomax' Kamermans for his awesome svg-path-reverse and bezierjs

License

SVGPathCommander is released under MIT Licence.