svg-path-commander 0.1.11-alpha4 → 0.1.16

package/README.md

@@ -1,6 +1,10 @@
-# SVG Path Commander
+![image](./assets/SVGPathCommander.svg)
 
-A modern set of ES6+ JavaScript tools for manipulating the `d` (description) attribute for *SVGPathElement* items, and is implementing modern JavaScript API to produce reusable path strings with lossless quality.
+A modern set of ES6+ JavaScript tools for manipulating the `d` (description) attribute for *SVGPathElement* items. The library is implementing modern JavaScript API to produce reusable path strings with lossless quality. In addition, you also have a powerful tool to convert other SVG shapes like `<circle>` or `<rect>` to `<path>`.
+
+[![NPM Version](https://img.shields.io/npm/v/svg-path-commander.svg?style=flat-square)](https://www.npmjs.com/package/svg-path-commander)
+[![NPM Downloads](https://img.shields.io/npm/dm/svg-path-commander.svg?style=flat-square)](http://npm-stat.com/charts.html?svg-path-commander)
+[![jsDeliver](https://data.jsdelivr.com/v1/package/npm/svg-path-commander/badge)](https://www.jsdelivr.com/package/npm/svg-path-commander)
 
 While you may find familiar tools inside, this library brings ***new additions***:
 * a tool that can *reverse path draw direction* without altering path commands, even with specific shorthand path commands;
@@ -9,9 +13,10 @@ While you may find familiar tools inside, this library brings ***new additions**
 
 **The key differences with other libraries**:
 * ES6+ sourced with modernized codebase and build tools; all inherited codebase has been modernized as well;
-* you can use this library in both web apps and Node.js, where others are restricted to a single environment;
+* along with the modern codebase, the library also comes with strong TypeScript definitions;
+* you can use this library in both web apps and Node.js, you are not restricted to a single environment;
 * path command transformations are all consistent with the SVG coordinates system, where others compute transform origin only for rotation transformation;
-* as you will see below, our library can create 3D to 2D projections, making your SVGs look like 3D but in the SVG coordinate system.
+* this library can create 3D to 2D projections, making your SVGs look like 3D but in the SVG coordinate system.
 
 **SVGPathCommander** implements the [DOMMatrix API](https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix) for *SVGPathElement* path command transformation and falls back to a modernized [CSSMatrix shim](https://github.com/thednp/DOMMatrix) on older browsers as well as Node.js.
 There are a couple of good reasons for this implementation:
@@ -21,10 +26,6 @@ There are a couple of good reasons for this implementation:
 
 This library is available on [CDN](https://www.jsdelivr.com/package/npm/svg-path-commander) and [npm](https://www.npmjs.com/package/svg-path-commander). 
 
-[![NPM Version](https://img.shields.io/npm/v/svg-path-commander.svg?style=flat-square)](https://www.npmjs.com/package/svg-path-commander)
-[![NPM Downloads](https://img.shields.io/npm/dm/svg-path-commander.svg?style=flat-square)](http://npm-stat.com/charts.html?svg-path-commander)
-[![jsDeliver](https://data.jsdelivr.com/v1/package/npm/svg-path-commander/badge)](https://www.jsdelivr.com/package/npm/svg-path-commander)
-
 
 # Install
 
@@ -44,7 +45,49 @@ import SVGPathCommander from 'svg-path-commander';
 
 const path = 'M0 0 L50 100';
 
-const flippedPath = new SVGPathCommander(path).flipX().toString();
+// flip a path on X axis
+const flippedPathString = new SVGPathCommander(path).flipX().toString();
+
+// apply a 2D transformation
+const transform = {
+  translate: 15, // X axis translation
+  rotate: 15, // Z axis rotation
+  scale: 0.75, // uniform scale on X, Y, Z axis
+  skew: 15, // skew 15deg on the X axis
+  origin: [15, 0] // if not specified, it will calculate a bounding box to determine a proper `transform-origin`
+}
+const transformed2DPathString = new SVGPathCommander(path).transform(transform).toString();
+
+// apply a 3D transformation
+const transform = {
+  translate: [15, 15, 15], // `[15, 15]` would apply a 2D translation, and only `15` for X axis translation
+  rotate: [15, 15, 15], // or only "15" for 2D rotation on Z axis
+  scale: [0.7, 0.75, 0.8], // or only "0.7" for 2D scale on all X, Y, Z axis
+  skew: [15, 15], // or only "15" for the X axis
+  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();
+
+// convert a shape to `<path>` and transfer all non-specific attributes
+const circle = document.getElementById('myCircle');
+SVGPathCommander.shapeToPath(circle, true);
+
+// alternatively you can create <path> from specific attributes
+const myRectAttr = {
+  type: 'rect',
+  x: 25,
+  y: 25,
+  width: 50,
+  height: 50,
+  rx: 5
+};
+
+const myRectPath = SVGPathCommander.shapeToPath(myRectAttr);
+document.getElementById('mySVG').append(myRectPath);
 ```
 
 # WIKI
@@ -55,17 +98,18 @@ For developer guidelines, head over to the [wiki pages](https://github.com/thedn
 
 * converting and optimizing *SVGPathElement* for use in third party application; our [KUTE.js](https://github.com/thednp/kute.js) animation engine is using it to process *SVGPathElement* coordinates for [SVG morphing](https://thednp.github.io/kute.js/svgMorph.html) and [SVG cubic morphing](https://thednp.github.io/kute.js/svgCubicMorph.html);
 * animators that work with SVGs and need tools for performing specific path command processing;
-* font-icon creators can use it in both Node.js and web applications to process and test their creations.
+* front-end developers looking to spice up the content by combining, splitting or transforming paths;
+* font-icon creators can use it in both Node.js and web applications to process, optimize and test their creations.
 
 
 # Technical Considerations
 
-* the `optimize()` instance method will not merge path segments (for instance 2 or more cubic-bezier segments into one or more arc segments); however, it will try to provide shorthand notations where possible, pick the shortest string for each segment; while computing path command values, the script will try to deliver the best possible outcome;
-* all tools processing path segments will always round float values to 3 decimals; EG: 0.5666 => 0.566, 0.50 => 0.5; you can change the default option with `SVGPathCommander.options.decimals = 2` or remove the value rounding all together with `SVGPathCommander.options.round = 0`; you can also control this feature via instance options;
+* the `optimize()` instance method will not merge path segments (for instance two or more cubic-bezier segments into one or more arc segments); however, the script will try to provide shorthand notations where possible, pick the shortest string for each segment, and generally try to deliver the best possible outcome;
+* all tools processing path segments will never round float values, however `pathToString`, `optimizePath` and especially `roundPath` will always round values to the default of 4 decimals; EG: 0.56676 => 0.567, 0.50 => 0.5; you can change the default option with `SVGPathCommander.options.round = 2` or remove the value rounding all together with `SVGPathCommander.options.round = false`; you can also control this feature via instance options;
 * the `getSVGMatrix` utility we developed will always compute the matrix by applying the transform functions in the following order: `translate`, `rotate`, `skew` and `scale`, which is the default composition/recomposition order specified in the W3C draft;
-* all 3d transformations as well as skews will convert `A` (arc) path commands to `C` (cubic bezier) due to the lack of resources on 3D to 2D projection;
-* most tools included with **SVGPathCommander** should work in your Node.js apps, but if you choose to use other complimentary 3rd party libraries, make sure you have the proper tools for them;
-* other path commands like `R` (catmulRomBezier), `O`, `U` (ellipse and shorthand ellipse) are not present in the current draft and they are not supported;
+* 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.