svg-path-commander 0.1.21 → 0.1.22

package/README.md

@@ -40,15 +40,25 @@ npm install svg-path-commander
 ```
 
 # Quick Guide
+
+Flip a path on the X axis:
 ```js
 import SVGPathCommander from 'svg-path-commander';
 
 const path = 'M0 0 L50 100';
 
-// flip a path on X axis
 const flippedPathString = new SVGPathCommander(path).flipX().toString();
+// result => 'M0 100L50 0'
+```
 
-// apply a 2D transformation
+Optimize a path string for best outcome by using the `round: 'auto'` option which will determine the amount of decimals based on the shape's bounding box:
+```js
+const optimizedPathString = new SVGPathCommander(path, {round: 'auto'}).optimize().toString();
+```
+
+Or why not apply a **2D transformation** and even a **3D transformation**:
+```js
+// a transform object
 const transform = {
   translate: 15, // X axis translation
   rotate: 15, // Z axis rotation
@@ -67,16 +77,45 @@ const transform = {
   origin: [15, 15, 15] // full `transform-origin` for a typical 3D transformation
 }
 const transformed3DPathString = new SVGPathCommander(path).transform(transform).toString();
+```
 
-// optimize a path string for best outcome by using the `round: 'auto'` option
-// which will determine the amount of decimals based on the shape's bounding box
-const optimizedPathString = new SVGPathCommander(path, {round: 'auto'}).optimize().toString();
+SVGPathCommander comes with a full range of additional static methods, here's how to normalize a path:
+```js
+const path = 'M0 0 H50';
+
+const normalizedPath = SVGPathCommander.normalizePath(path);
+// result => [['M', 0, 0], ['L', 50, 0]]
+```
+
+Reverse a path:
+```js
+const path = 'M0 0 H50';
 
-// convert a shape to `<path>` and transfer all non-specific attributes
-const circle = document.getElementById('myCircle');
-SVGPathCommander.shapeToPath(circle, true);
+const reversedPath = SVGPathCommander.reversePath(path);
+// result => [['M', 50, 0], ['H', 0]]
+```
+
+Export to string:
+```js
+const myPathString = SVGPathCommander.pathToString([['M', 0, 0], ['L', 50, 0]]);
+// result => 'M0 0 L50 0'
+```
 
-// alternatively you can create <path> from specific attributes
+
+Check a path string validity:
+```js
+SVGPathCommander.isValidPath(path);
+// result => boolean
+```
+
+Convert a shape to `<path>` and transfer all non-specific attributes
+```js
+const myCircle = document.getElementById('myCircle');
+SVGPathCommander.shapeToPath(myCircle, true);
+```
+
+Alternatively you can create `<path>` from specific attributes:
+```js
 const myRectAttr = {
   type: 'rect',
   x: 25,
@@ -90,8 +129,26 @@ const myRectPath = SVGPathCommander.shapeToPath(myRectAttr);
 document.getElementById('mySVG').append(myRectPath);
 ```
 
+Get the path length:
+```js
+const myPathLength = SVGPathCommander.getTotalLength('M0 0L50 0L25 50z');
+// result => 161.80339887498948
+```
+
+Get a point along the path:
+```js
+const myPoint = SVGPathCommander.getPointAtLength('M0 0L50 0L25 50z', 85);
+// result => {x: 34.34752415750147, y: 31.304951684997057}
+```
+
+Get the path bounding box:
+```js
+const myPathBBox = SVGPathCommander.getPathBBox('M0 0L50 0L25 50z');
+// result => {width: 50, height: 50, x: 0, y: 0, x2: 50, y2: 50, cx: 25, cy: 25, cz: 75}
+```
+
 # WIKI
-For developer guidelines, head over to the [wiki pages](https://github.com/thednp/svg-path-commander/wiki).
+For developer guidelines, and a complete list of static methods, head over to the [wiki pages](https://github.com/thednp/svg-path-commander/wiki).
 
 
 # What Is It For?
@@ -110,7 +167,8 @@ For developer guidelines, head over to the [wiki pages](https://github.com/thedn
 * all 3d transformations as well as skews will convert `A` (arc) path commands to `C` (cubic bezier) due to the lack of resources;
 * most tools included with **SVGPathCommander** should work in your Node.js apps, but feel free to report any issue;
 * other path commands like `R` (catmulRomBezier), `O`, `U` (ellipse and shorthand ellipse) are not present in the current draft and are not supported;
-* normalization can mean many things to many people and our library is developed to convert path command values to absolute and shorthand to non-shorthand commands to provide a solid foundation for the main processing tools of our library.
+* normalization can mean many things to many people and our library is developed to convert path command values to absolute and shorthand to longshorthand commands to provide a solid foundation for the main processing tools of our library;
+* when compared to the native methods like `SVGPathElement.getTotalLength()` or `SVGPathElement.getPointAtLength()`, the output of our static methods is within a [0.002 - 0.05] margin delta, but from our experience it's proven to be a more consistent outcome.
 
 
 # Special Thanks
@@ -119,8 +177,10 @@ For developer guidelines, head over to the [wiki pages](https://github.com/thedn
 * Vitaly Puzrin & Alex Kocharin for their [SvgPath](https://github.com/fontello/svgpath)
 * Jürg Lehni & Jonathan Puckey for their [Paper.js](https://github.com/paperjs/paper.js/)
 * Andrew Willems for his [awesome guide](https://stackoverflow.com/users/5218951/andrew-willems)
-* Mike 'Pomax' Kamermans for his awesome [svg-path-reverse](https://github.com/Pomax/svg-path-reverse) and [bezierjs](https://github.com/Pomax/bezierjs)
+* Mike 'Pomax' Kamermans for his awesome [svg-path-reverse](https://github.com/Pomax/svg-path-reverse), [bezierjs](https://github.com/Pomax/bezierjs) and [bezierinfo](https://pomax.github.io/bezierinfo/)
 * Nicolas Debeissat for the inspiration on [svg3d](https://github.com/ndebeiss/svg3d)
+* Mike Bostock for his awesome [closestPoint](https://bl.ocks.org/mbostock/8027637)
+* James Halliday for his excelent [point-at-length](https://github.com/substack/point-at-length)
 
 # License
 **SVGPathCommander** is released under [MIT Licence](https://github.com/thednp/svg-path-commander/blob/master/LICENSE).