Usage Examples

ES6+ Usage

Import, initialize and call multiple instance methods, or return the values right away.

Example

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

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

// initialize
let mySVGPCInit = new SVGPathCommander(pathString);
/* 
returns => {
  pathValue: 'M0 0l50 0l50 50z',
  segments: [ ['M',0,0], ['l',50,0], ['l',50,50], ['z'] ],
  round: 3
}
*/

// direct access to methods
let mySVGPCInit = new SVGPathCommander(pathString).flipX().toString();
// returns => "M100 50L50 0L0 0z"

Node.js

// for node.js, you also need to bring DOMMatrix shim
const DOMMatrix = require('dommatrix');

// import the constructor
const SVGPathCommander = require('svg-path-commander');

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

// initialize
let mySVGPCInit = new SVGPathCommander(pathString);

// or do whatever you want, perhaps you're a font creator?
let mySVGPCString = new SVGPathCommander(pathString)
                  .flipX()
                  .optimize()
                  .toString();

Examples for Main Methods

// reuse same init object to call different methods
// for instance convert to ABSOLUTE and return the initialization object
mySVGPCInit.toAbsolute()

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

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

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

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

// or return directly what you need
// reverse subpaths and return the optimized pathString
let myReversedPath = new SVGPathCommander(pathString).reverse(1).optimize().toString()

// flip the shape vertically and return the pathString
mySVGPCInit.flipX().toString()

// apply a skew transformation and return the pathString
mySVGPCInit.transform({skew:25}).toString()

Instance Options Example

// disable rounding values
let mySVGPath = new SVGPathCommander('M0 0L0 0', { round: 0 })

// OR set a certain amount of decimals
let mySVGPath = new SVGPathCommander('M0 0L0 0', { decimals: 4 })

// Apply a 45deg rotation on Z axis and use a custom transform origin 
let mySVGPath = new SVGPathCommander( 'M0 0L0 0')
                    .transform({ rotate:[0,0,45], origin: [25,25] }) 

Apply Transform To Path Commands

You can either call the SVGPathCommander methods flipX() or flipY() to perform a quick transformation or set custom functions, in which case you can provide a transformObject Object

2D Transformation Example

// define properties you want to transform
let transformObject = {
  scale: 0.3,
  translate: 20,
  rotate:45,
  skew:20
}

let myPathString = new SVGPathCommander('M0 0L0 0')
                      .transform(transformObject)
                      .toString()

3D Transformation Example

The transformObject can also set the transform-origin required for the transformation, if origin property is not set, by default 50% 50% of the shape's bounding box is used; absolute values relative to a parent SVGElement are expected.

// define properties to apply a transformation for 
// also provide a transform origin with the "origin" Object property
let transformObject = {
  origin: [205,205,205], // transform origin assumes the shape bounding box is 410 wide and 410 tall
  scale: [0.3,0.3,0.3],  // all axes scale
  translate: [20,0,0],   // translateX
  rotate:[0,0,45],       // rotateZ
  skew:[20,0]            // skewX
}

let myPathString = new SVGPathCommander('M0 0L0 0')
                      .transform(transformObject)
                      .toString()

For simplicity reasons and other considerations, we've decided not to include support for axis specific transform functions like rotateX or scaleY, since DOMMatrix and WebKitCSSMatrix APIs both support shorthand functions and would not make sense to just alocate more memory for aliases.

Determine Shape Draw Direction

When reversing path strings, you might want to know their draw direction first:

Example

import getDrawDirection from 'svg-path-commander/src/util/getDrawDirection.js'

// init
let shapeDrawDirection = getDrawDirection(pathString)
// => returns TRUE if shape draw direction is clockwise or FALSE otherwise

Keep in mind that paths with sub-paths may skew your result, you may want to split them and perform this check on each.

Advanced Usage

In most cases, you can import only the tools you need, without importing the entire library.

Example

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))

Most of these tools are already exported to global and are listed below.

Other Tools

When using the distribution files, 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,decimals) - returns a pathArray which is used by all of SVGPathCommander processing tools;
• SVGPathCommander.pathToAbsolute(pathString|pathArray,decimals) - returns a new pathArray having all path commands as absolute coordinates;
• SVGPathCommander.pathToRelative(pathString|pathArray,decimals) - returns a new pathArray having all path commands as relative coordinates;
• SVGPathCommander.pathToCurve(pathString|pathArray,decimals) - returns a new pathArray having all path commands converted to cubicBezier (C) and absolute values;
• SVGPathCommander.pathToString(pathArray) - converts any pathArray to string and returns it;
• SVGPathCommander.clonePath(pathArray) - returns a deep clone of a pathArray, which is the result of any of the above functions;
• SVGPathCommander.roundPath(pathArray,decimals) - returns a new pathArray with all float path command values rounded to 3 decimals by default, or provide a number to be used as the amount of decimals to round values to;
• SVGPathCommander.reversePath(pathString|pathArray,decimals) - returns a new pathArray with all path commands having absolute values and in reverse order, but only for a single M->Z shape, for paths having sub-path(s) you need to use the SVGPathCommander constructor itself;
• SVGPathCommander.optimizePath(pathArray,decimals) - returns a new pathArray with all segments that have the shortest strings from either absolute or relative pathArray segments;
• SVGPathCommander.transformPath(pathArray,transformObject,decimals) - returns a new pathArray with all segments transformed according to the properties defined in the transformObject;
• SVGPathCommander.normalizePath(pathString|pathArray,decimals) - returns a new pathArray with all shorthand path command segments such as S, T are converted to C and Q respectively, V and H to L, all in absolute values; the utility is used by pathToCurve and reversePath;
• SVGPathCommander.getDrawDirection(pathArray) - converts the pathArray to curve and returns TRUE if a shape draw direction is clockwise, it should work for shapes with sub-paths, but it might skew your results, so make sure you split your path and test each subpath separatelly;
• SVGPathCommander.getPathBBox(pathArray) - converts the pathArray to curve and returns the bounding box of a shape in the form of the following object: {x1,y1, x2,y2, width,height, cx,cy}, where cx & cy are the shape's center point; for faster processing, you might want to split the path with subpaths and return the bounding box you know is the largest;
• SVGPathCommander.getPathLength(pathArray) - converts the pathArray to curve and returns the total length of the shape; this is equivalent to SVGPathElement.prototype.getTotalLength() and should work in Node.js;
• SVGPathCommander.getPointAtLength(pathArray) - converts the pathArray to curve and looks into each segment and returns an {x,y} object;
• SVGPathCommander.splitPath(pathString) - returns an Array of sub-path strings.