<p>The SVG Plugin for KUTE.js extends the core engine and enables animation for various SVG specific CSS properties, SVG morphing of path shapes and SVG transforms. We'll dig into this in great detail as well as provide valuable tips on how to
configure your animation for best performance and visual aesthetics. The SVG Plugin is very light, maybe one of the lightest out there, still, you will find it to be very powerful and flexible.</p>
<p>Keep in mind that older browsers like Internet Explorer 8 and below as well as stock browser from Android 4.3 and below <ahref="http://caniuse.com/#search=svg"target="_blank">do not support inline SVG</a> so make sure to fiter out your SVG
tweens.</p>
<h3>SVG Morphing</h3>
<p>One of the most important parts of the plugin is the SVG morphing capability. It only applies to inline <code><path></code> and <code><glyph></code> SVG elements, with closed shapes (their <code>d</code> attribute ends with <code>z</code>).
On initialization or animation start, depending on the chosen KUTE.js method, it will <ahref="http://phrogz.net/SVG/convert_path_to_polygon.xhtml"target="_blank">sample a number of points</a> along the two paths based on a default /
given sample size and will create two arrays with these points, the arrays that we need for interpolation. Further more, with a set of options we can then rearrange / reverse these arrays to optimize and / or maximize the visual effect
of the morph:</p>
<ul>
<li><kbd>morphPrecision: Number</kbd> option allows you to set the sampling size of the morph. The lesser value the better visual but the more power consumption and less performance. The default value is 15 but the
<ahref="http://bl.ocks.org/mbostock/3081153"
target="_blank">D3.js example</a> uses 4.</li>
<li><kbd>morphIndex: Number</kbd> option allows you to rotate the second/end path in a way that the points travel the least possible distance during morph, and as an effect the morph animation feel more "natural". By default, this option is
not set.</li>
<li><kbd>reverseFirstPath: true</kbd> when is <code>true</code> this option allows you to reverse the draw direction of the FIRST shape. By default this option is <code>false</code>.</li>
<li><kbd>reverseSecondPath: true</kbd> when is <code>true</code> this option allows you to reverse the draw direction of the SECOND shape. By default this option is also <code>false</code>.</li>
</ul>
<h4>Basic Example</h4>
<p>In the first morph example we are going to go through some basic steps on how to setup and how to improve the morph animation. Our demo is a morph from a rectangle into a star, so first let's create an SVG element with two paths, first is
going to be visible, filled with color, while second is going to be hidden. The first path is the start shape and the second is the end shape, you guessed it, and we can also add some ID to the paths so we can easily target them with our
<p>As you can see, the animation could need some fine tunning. Let's go ahead and play with the new <ahref="http://codepen.io/thednp/pen/YGayLg">utility</a>, it's gonna make your SVG morph work a breeze.</p>
<p>Well, we're going to set the <code>morphIndex: 127</code> tween option and we will get an improved morph. Sometimes the recommended value isn't what we're looking for, so you just have to experience values
around the recommended one. I also made a <ahref="http://codepen.io/thednp/pen/bpRRZd"target="_blank">pen</a> for you to play with.</p>
<p>When your paths are only <code>lineto</code>, <code>vertical-lineto</code> and <code>horizontal-lineto</code> based shapes (the <code>d</code> attribute consists of <code>L</code>, <code>V</code> and
<code>H</code> path commands), the SVG Plugin will work differently: it will use their points instead of sampling new ones. As a result, we boost the visual and maximize the performance. The
<code>morphPrecision</code> option will not apply since the paths are already polygons, still you will have access to all the other options.</p>
<p>The plugin will try to convert paths to absolute values for polygons, but it might not find most accurate coordinates values for relative <code>v</code> and <code>h</code> path commands. I highly
recommend using my <ahref="http://codepen.io/thednp/full/EgVqLw/">utility converter</a> to prepare your paths in that case.</p>
<p>In the example below the triangle shape will morph into a square, then the square will morph into a star, so 2 tweens chained with a third that will morph back to the original triangle shape. For each
tween the morph will use the number of points from the shape with most points as a sample size for the other shape. Let's have a look at the demo.</p>
<p>The morph for polygon paths is the best morph in terms of performance so it's worth keeping that in mind. Also using paths with only <code>L</code> path command will make sure to prevent value processing
and allow the animation to start as fast as possible.</p>
<p>As you can see, both these paths have subpaths, and KUTE.js will only animate the first of both in this case. To animate them all, we need to break them into multiple paths, so we can handle each path morph properly.</p>
<p>After a close inspection we determined that paths are not ordered the same so it seems we need to tween the paths in a way that their points travel the least possible distance, as follows: <code>#w11</code>
to <code>#w24</code>, <code>#w13</code> to <code>#w21</code>, <code>#w14</code> to <code>#w22</code> and <code>#w12</code> to <code>#w23</code>.</p>
<p>As you can imagine, it's quite hard if not impossible to code something that would do all this work automatically, so after a minute or two tweaking the options, here's what we should see:</p>
<p>Note that this final touch required using <code>reverseSecondPath:true</code> option for all tweens because each shape have a slightly different position from its corresponding shape, so make sure to
check the <ahref="assets/js/svg.js"target="_blank">svg.js</a> for a full code review.</p>
<p>The last morph example is a bit more complex as the paths have subpaths with different positions and other important differences such as having different amounts of subpaths as well as significant
differences of their positions. In this case you have to manually clone one or more paths in a way that the number of starting shapes is equal to the number of ending shapes, as well as making sure
the starting shapes are close to their corresponding end shapes; at this point you should be just like in the previous example.</p>
<p>An important aspect of multi path morph is syncronization: since the <code>.to()</code> method will prepare the paths for interpolation at animation start, and this usually takes a bit of time,
the problem can be easily solved as always using the <code>.fromTo()</code> method. So, let's get into it:</p>
<p>As with the previous example, you should change which path will morph to which path so that their points travel the least possible distance and the morph animation looks visually appealing. In the next
example, we have used a <code>mask</code> where we included the subpaths of both start and end shape, just to get the same visual as the originals.</p>
<p>So you have many options to improve the visual and performance for your complex animation ideas. The SVG Plugin for KUTE.js uses approximatelly the same algorithm as D3.js for determining the coordinates
for tween, it's super light, it's a lighter script, it might be a better solution for your applications.</p>
<li>When morphing subpaths/multipaths instead of cloning shapes to have same number of shapes in both starting and ending shapes, you should also consider a fade and/or scale animation to improve the
overal animation performance, don't forget about mobile devices.</li>
<li>Large displays would need best resolution possible so a small <code>morphPrecision</code> value (1-10) would be required, assuming performant hardware are powering the displays. For small displays
you can get quite comfortable with almost any value, including the default value.</li>
<li>The SVG morph performance is the same for both <code>.to()</code> and <code>.fromTo()</code> methods, but the ones that use the second method will start faster, because the values have been prepared
already and for the first method the processing of the two paths happens on tween start delaying the animation, so keep that in mind when working with syncing multiple tweens, the <code>.to()</code>
based morph will always start later. Of course this assumes the you cache the tween objects first and start the animation later, if not (you start the animation on object creation), both methods will
<p>Next, we're going to animate the stroking of some elements. Starting with KUTE.js version 1.5.2, along with <code><path></code> shapes, <code><circle></code>, <code><ellipse></code>, <code><rect></code>,
<code><line></code>, <code><polyline></code> and <code><polygon></code> shapes are also supported; the script uses the SVG standard <code>.getTotalLength()</code> method for <code><path></code>
shapes, while the others use some helper methods. Here some code examples:</p>
<p>Remember: the <codeclass="bg-indigo">draw</code> property also accepts absolute values, eg. <code>draw: '0 150'</code>; the <code>.to()</code> method takes <code>0% 100%</code> as start value for your
tweens when <code>stroke-dasharray</code> and <code>stroke-dashoffset</code> are not set.</p>
<p>Starting with KUTE.js 1.5.2, the SVG Plugin features a new tween property for cross browser SVG transforms, but was coded as a separate set of methods for SVG only, to keep performance tight and solve
most browser inconsistencies. A very simple roadmap was described <ahref="https://github.com/thednp/kute.js/issues/31"target="_blank">here</a>; in brief we needed to find a way to enable SVG transforms
in a <ahref="https://css-tricks.com/transforms-on-svg-elements/"target="_blank">reliable and cross-browser</a> supported fashion.</p>
<p>With KUTE.js 1.6.0 the SVG transform is a bigger part of the SVG Plugin for two reasons: first is the ability to use the <code>transformOrigin</code> just like for CSS3 transforms and secondly the unique
way to normalize translation to work with the transform origin in a way that the animation is just as consistent as for CSS3 transforms on non-SVG elements. Also the value processing is consistent with
the <ahref="https://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace">working draft</a>.</p>
<p>While you can still use regular <ahref="examples.html">CSS3 transforms</a> for SVGs on browsers like Google Chrome, Opera and others, Firefox struggles big time with the percentage based
<code>transform-origin</code> values and ALL Internet Explorer versions have no implementation for CSS3 transforms on SVG elements.</p>
<p>KUTE.js SVG Plugin comes with a better way to animate transforms on SVGs shapes reliably on all browsers, by the use of the <code>transform</code> presentation attribute and the
<codeclass="bg-indigo">svgTransform</code> tween property with a special notation:</p>
<p>As you can see we have some familiar notation, but an important notice here is that <codeclass="bg-indigo">svgTransform</code> tween property treat all SVG transform functions as if you are using the
<code>50% 50%</code> of the shape box at all times by default, even if the default value is "0px 0px 0px" on SVGs in most browsers.</p>
<p>Perhaps the most important thing to remember is the fact that SVG tranformations always use SVG coordinates system, and the <code>transform</code> attribute accepts no measurement units such as degrees
or pixels. For these reasons the <code>transformOrigin</code> tween option can also accept array values just in case you need coordinates relative to the parent <code><svg></code> element. Also values
like <i>top left</i> values will work.</p>
<p>In the following examples we showcase the animation of CSS3 transform applied to SVG shapes (LEFT) as well as <codeclass="bg-indigo">svgTransform</code> based animations (RIGHT). I highly encourage you
to test all of them in all browsers, and as a word ahead, animations in Webkit browsers will look identical, while others are inconsistent or not responding to DOM changes. Let's break it down to pieces.</p>
<p>Our first chapter of the SVG transform is all about rotations, perhaps the most important part here. As of with KUTE.js 1.6.0 the <codeclass="bg-indigo">svgTransform</code> will only accept single value
for the angle value <code>rotate: 45</code>, the rotation will go around the shape's center point by default, again, contrary to the browsers' default value and you can set a <code>transformOrigin</code>
tween option to override the behavior.</p>
<p>The argument for this implementation is that this is something you would expect from regular HTML elements rotation and probably most needed, not to mention the amount of savings in the codebase department.
<p>The first tween uses the CSS3 transform notation and the animation clearly shows the shape rotating around it's center coordinate, as we've set <code>transformOrigin</code> option to <i>50% 50%</i>, but this
animation doesn't work in IE browsers, while in Firefox is inconsistent with the SVG coordinate system. The second tween uses the <code>rotate: 360</code> notation and the animation shows the shape rotating
around it's own central point and without any option, an animation that DO WORK in all SVG enabled browsers.</p>
<p>When for CSS3 transforms we could have used values such as <i>center bottom</i> as <code>transform-origin</code> (also not supported in all modern browsers for SVGs), the entire processing was basically in/by
the browser, however when it comes to SVGs the plugin here will compute the <code>transformOrigin</code> tween setting value accordingly to use a shape's <code>.getBBox()</code> value to determine for instance
the coordinates for <i>25% 75%</i> position or <i>center top</i>.</p>
<p>In other cases you may want to rotate shapes around the center point of the parent <code><svg></code> or <code><g></code> element, and we use it's <code>.getBBox()</code> to determine the <i>50% 50%</i>
<p>Note that this is the only SVG transform example in which we have adapted the <code>transform-origin</code> for the CSS3 transform rotation so that both animations look consistent in all browsers, and if you are
interested in learning about this fix, similar to the above, just we are adding "px" to the calculated value, but you better make sure to check <ahref="./assets/js/svg.js">svg.js</a> file.</p>
<p>In this example we'll have a look at translations, so when setting <code>translate: [150,0]</code>, the first value is X (horizontal) coordinate to which the shape will translate to and the second value is
Y (vertical) coordinate for translation. When <code>translate: 150</code> notation is used, the script will understand that's the X value and the Y value is 0 just like for the regular HTML elements
transformation. Let's have a look at a quick demo:</p>
<p>The first tween uses the CSS3 <code>translate: 580</code> notation for the end value, while the second tween uses the <code>translate: [0,0]</code> as <codeclass="bg-indigo">svgTransform</code> value.
For the second example the values are unitless and are relative to the <code>viewBox</code> attribute.</p>
<p>For skews for SVGs we have a very simple notation: <code>skewX: 25</code> or <code>skewY: -25</code> as SVGs don't support the <code>skew: [X,Y]</code> function. Here's a quick demo:</p>
<p>The first tween skews the shape on both X and Y axis in a chain via regular CSS3 transforms and the second tween skews the shape on X and Y axis via the <codeclass="bg-indigo">svgTransform</code> tween
property. You will notice translation kicking in to set the transform origin and the example also showcases the fact that chain transformations for SVGs via <code>transform</code> attribute works just
<p>Another transform example for SVGs is the scale. Unlike translations, for scale animation the plugin only accepts single value like <code>scale: 1.5</code>, for both X (horizontal) axis and Y (vertical) axis,
to keep it simple and even if SVGs do support <code>scale(X,Y)</code>. But because the scaling on SVGs depends very much on the shape's position, the script will always try to adjust the translation to
make the animation look as we would expect. A quick demo:</p>
<p>The first tween scales the shape at <code>scale: 1.5</code> via regular CSS3 transforms, and the second tween scales down the shape at <code>scale: 0.5</code> value via <codeclass="bg-indigo">svgTransform</code>.
If you inspect the elements, you will notice for the second shape translation is involved, and this is to keep <code>transform-origin</code> at an expected <i>50% 50%</i> value. A similar case as with the skews.</p>
<p>Our last transform example for SVGs is the mixed transformation. Just like for the other examples the plugin will try to adjust the rotation <code>transform-origin</code> to make it look as you would expect it
from regular HTML elements. Let's combine 3 functions at the same time and see what happens:</p>
<p>Both shapes are scaled at <code>scale: 1.5</code>, translated to <code>translate: 250</code> and skewed at <code>skewX: -15</code>. If you inspect the elements, you will notice the second shape's translation is
different from what we've set in the tween object, and this is to keep <code>transform-origin</code> at an expected <i>50% 50%</i> value. This means that the plugin will also compensate rotation transform origin
when skews are used, so that both CSS3 transform property and SVG transform attribute have an identical animation.</p>
<p>The SVG Plugin does not work with SVG specific chained transform functions right away (do not confuse with tween chain), but if your SVGs only use this feature to set a custom <code>transform-origin</code>,
<p>Well in this case I would recommend using the values of the first translation as <code>transform-origin</code> for your tween built with the <code>.fromTo()</code> method like so:</p>
<pre><codeclass="language-javascript">// a possible workaround for animating a SVG element that uses chained transform functions
<p>Before you hit the <kbd>Start</kbd> button, make sure to check the <code>transform</code> attribute value. The below tween will reset the element's transform attribute to original value when the animation is complete.</p>
<p>This way we make sure to count the real current transform-origin and produce a consistent animation with the SVG coordinate system, just as the above example showcases.</p>
<li>The SVG Plugin coming with KUTE.js version 1.6.0 is successfuly handling all possible combinations of transform functions, and <b>always uses same order of transform functions</b>: <code>translate</code>,
<code>rotate</code>, <code>skewX</code>, <code>skewY</code> and <code>scale</code> to keep animation consistent and with same aspect as for CSS3 transforms on non-SVG elements.</li>
<li>Keep in mind that the SVG transforms will use the center of a shape as transform origin by default, contrary to the SVG draft.</li>
<li>Keep in mind the adjustments required for rotations, remember the <code>.getBBox()</code> method, it's really useful to set custom <code>transform-origin</code>.</li>
<li>By default browsers use <code>overflow: hidden</code> for <code><svg></code> so child elements are partialy/completely hidden while animating. You might want to set <code>overflow: visible</code>
or some browser specific tricks if that is the case.</li>
<li>When using <code>viewBox="0 0 500 500"</code> attribute for <code><svg></code> and no <code>width</code> and/or <code>height</code> attribute(s), means that you expect the SVG to be scalable and most
Internet Explorer versions simply don't work. You might want to <ahref="https://css-tricks.com/scale-svg/"target="_blank">check this tutorial</a>.</li>
<li>Similar to the CSS3 transform animation featured in the core engine, the <codeclass="bg-indigo">svgTransform</code> property DOES stack transform functions for chained tween objects created with the
<code>.to()</code> method, you will have to provide only values for the functions that will change and the plugin will try to keep the unchanged values. However, there's a catch: you need to follow all
the properties and I highly recommend checking the example code for skews in the <ahref="./assets/js/svg.js">svg.js</a> file.</li>
<li>In other cases when you need maximum control and precision or when shapes are already affected by translation, you might want to use the <code>.fromTo()</code> method with all proper values.</li>
<li>Also the <codeclass="bg-indigo">svgTransform</code> tween property does not support 3D transforms, because they are not supported in all SVG enabled browsers.</li>
</ul>
<h3>SVG Plugin Tips</h3>
<ul>
<li>The SVG Plugin can be combined with the <ahref="attr.html">Attributes Plugin</a> to enable even more advanced/complex animations for SVG elements.</li>
<li>Since SVG morph scripting works only with <code>path</code> or <code>glyph</code> elements, you might need a <code>convertToPath</code> feature, so
<ahref="https://github.com/Waest/SVGPathConverter"target="_blank">check this out</a>.</li>
<liclass="hidden-xs"><atarget="_blank"href="https://www.facebook.com/sharer/sharer.php?u=http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Facebook"><spanclass="ion-social-facebook-outline icon"></span></a></li>
<liclass="hidden-xs"><atarget="_blank"href="https://twitter.com/home?status=Spread the word about %23KUTEJS animation engine by @dnp_theme and download here http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Twitter"><spanclass="icon ion-social-twitter-outline"></span></a></li>
<liclass="hidden-xs"><atarget="_blank"href="https://plus.google.com/share?url=http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Google+"><spanclass="icon ion-social-googleplus-outline"></span></a></li>