Using Inkscape to create PolyAnim animations

PolyAnim version 0.6 added an experimental / unsupported tool that can convert specially made Inkscape SVG files to PolyAnim XML animations. This tutorial shows you how to create PolyAnim animations in Inkscape. Mind you, it's not very pleasant nor flexible, but the basic features work alright. :)

When I get the proper animation editor done, I'm hoping it will make the creation of the animations easier.

The first animation

Download and install Inkscape from http://www.inkscape.org. This guide is tested with Inkscape 0.46, but will most probably work for any version.

Let's start by creating a very simple animation. Start up Inkscape and read on.

Picture 1.

See the marked top-left corner of the Inkscape document, as shown in picture 1? Top-left is the origin for the final animation, so you should design your animation around the top-left corner. Yes, it's not very intuitive, but then again you don't really have to think about it. :)

Let's create our first polygon. Note that the ConvertSVG tool only supports the Path tool (Shift-F6) in Inkscape. When you hover over the tool button, it shows "Draw Bezier curves and straight lines". Straight lines are what we need to use. If you ever accidentally create curves, you need to undo - the converter will not work with curved lines.

Picture 2.

Select the Path-tool (marked in the picture 2), and draw a diamond shape around the origin (the top-left corner) in counter-clockwise order. For simplicity, you should use counter-clockwise for each polygon you draw. The direction itself doesn't matter, but it must be consistent across the animation frames. So, click on the point marked 1., then on 2. and so forth. Close the shape by clicking again on the first point (1. / 5.). Color the polygon as you like (only simple color fill + opacity is supported, no gradients unfortunately).

Picture 3.

In PolyAnim, all polygons must belong to a polygon group. So, we need to wrap our lonely polygon into a group in Inkscape. Yes, a group can consist of a single polygon as well as many. ;) Click on the Group selected objects -button marked in the picture 3. Right-click on the polygon, and select Object Properties from the menu.

Picture 4.

A dialog shown in picture 4 will appear. You need to name the polygon group by setting it's label. Type diamond there and press Set. The actual label/name doesn't matter, but it must be consistent through the animation frames.

At this point you should save your work (Ctrl-S). I've chosen to save the document as diamond.svg. I've saved it to my PolyAnim folder in my Eclipse workspace, so it'll be easily accessible from the test program. But, before we can try that, there's still a couple more things to do.

How the key frames work

Layers in Inkscape will be converted to PolyAnim key frames. The frame transitition duration, which is the time in seconds it takes to move from the previous frame to the current frame, is set by renaming the layer in Inkscape. That was quite a mouthful, so let us consider an example.

Suppose you have three frames of animation: A, B and C. A is the first frame, B is the second and so forth. The frame transition durations are: A = 0 secs, B = 1.5 secs and C = 1.0 secs. PolyAnim will start from frame A, and proceed immediately (as the duration is zero seconds) with a transition to frame B. That transition takes exactly 1.5 seconds. Then, transition to frame C begins, and it takes exactly 1.0 seconds. After that the animation is finished, and it's total length is 0 + 1.5 + 1.0 = 2.5 seconds.

Picture 5.

So, select Layer --> Layers... in Inkscape. The layer view opens up to the right, as shown in picture 5. Click on the text "Layer 1", and rename it to "1.0 secs" without the quotes. That gives the first frame a duration of 1.0 seconds, before PolyAnim starts the transition to the second frame. The format for the layer names is: X.Y secs or X.Y sec or X.Y s or X.Y where X.Y is a floating point number like 1.0 or 0.75. The seconds suffix is optional, and case-insensitive. Note: Inkscape will not allow layers with the same name, so if you need, say, more than one frame with the duration of 1.5 seconds, you need to get a little imaginative and use 1.5 s for one frame, 1.5 for another, etc.

Testing the converter

Now we have a very simple animation, consisting of one static diamond with the total duration of one seconds! Let's convert the diamond.svg to diamond.xml and try it in PolyAnim test program.

Assuming you've saved diamond.svg to your PolyAnim workspace directory, you can use the following command line to do the conversion:

java -cp bin nr.co.mhgames.polyanim.util.ConvertSVG diamond.svg diamond.xml

If all goes well, ConvertSVG outputs

ConvertSVG - unsupported Inkscape SVG to PolyAnim XML converter.
-----------------------------------------------------------------
Parsing 'diamond.svg'.. ok.
Animation diamond.svg: length 1.00s, 1 key frames, nr.co.mhgames.polyanim.Animation@1201a25

Saving the animation to 'diamond.xml'.. ok.

You can then edit nr.co.mhgames.polyanim.test.TestScene.java to display diamond.xml instead of the Dude-animation. Find the line

animation2 = loader.readAnimation("dude.svg.xml");

and replace dude.svg.xml with diamond.xml. When we run either TestJava2D or TestLWJGL we get something like in picture 6.

Picture 6.

Very neat, wouldn't you say? ;)

Adding more frames

All the awesomeness aside, a static animation ain't much of an animation, right? We need more key frames.

Press the Create a new layer -button, marked green in picture 5. Give the new layer a name 1.5 secs. That will make so the transition from frame #1 to #2 will take 1.5 seconds. Now we need to duplicate the layer 1 (frame 1) contents into layer 2 (frame 2).

In the layers view, click on the first layer (named 1.0 secs). Select Edit --> Select All (Ctrl-A). Then Edit --> Copy (Ctrl-C). Now, select the new layer (named 1.5 secs) and Edit --> Paste In Place (Ctrl-Alt-V). After the groups have been copied, it's usually wise to make sure the group names (labels) are stayed the same. Remember, each group must have a consistent name in each frame it appears in. So, right-click on the diamond, select Object properties and make sure the label still reads diamond.

Now, here's a little tip. From the layers view, select the first layer/frame. Drag the opacity slider to something like 50% or below. When you have more frames, I suggest you to hide all the earlier frames except just the previous one. When the previous frame is transparent, it's much easier to animate. Don't worry when hidind/opacifying layers, they won't affect the resulting animation.

Go back to the new layer/frame, by clicking on it. There's two ways of animating in PolyAnim: you can animate the groups as whole (by moving, scaling, rotating) or animate the individual nodes (vertices) of the group polygons. Here we're going to try both.

Select the diamond (make sure you're in layer named 1.5 secs) and drag it up. You should have something like in picture 7 now.

Picture 7.

Now we're going to manipulate the diamond vertices (nodes in Inkscape). Select the Edit paths by nodes -tool (F2). Move the left and right nodes as shown in picture 8.

Picture 8.

While we're at it, why not change the diamond color as well? Having the adjusted diamond selected, assign it a new color. You should save your work now (Ctrl-S), and run the conversion again. If you check the PolyAnim test program, you should see the diamond waiting 1.0 seconds and then moving updwards. It will also smoothly change its color. Impressive, eh? ;)

Picture 9.

That concludes our very simple animation tutorial. :) You can download the SVG created from here: diamond.svg

Feel free to inspect dude.svg, which is the Inkscape file for the example animation (The Dude).

Tips and caveats

While working on more complex animations than the one described above, you might run into some problems. Here a few common caveats that you should keep in mind.

• The polygons render fine with Java2D but not in LWJGL! Why?
• You've used non-convex polygons, which are not supported by OpenGL and thus not by the PolyAnim LWJGL renderer. You need to create more complex shapes in several convex parts. The Inkscape grid mode might help to keep the polygon vertices aligned.
• PolyAnim crashes when rendering the animation
• That is usually when the polygons of your groups do not match between the frames. That is, in order for the animation to work, polygon N in frame X must correspond to the polygon N in frame Y.
• In Inkscape, while you can change the depth order of groups (with PageUp and PageDown keys), you cannot change the order of group polygons.
• If you need to change the order of polygons in a group, you must make sure that the polygon order is the same for every frame the group appears in.
• Inkscapes XML editor might help you inspect the polygon order. Edit --> XML Editor...
• No way to specify looping and the animation name?
• Currently not through Inkscape, you need to edit the converted XML file.
• Shearing doesn't work as it should
• Yep, it's not supported currently. Only scaling, translation and rotation are.
• Also note that Inkscape rotation is only between -180 and +180 degrees, while PolyAnim supports arbitary large rotations. These will be supported in the upcoming animation editor. If you need to make a group spin several times, you either need to make more key frames with smaller rotations, or adjust the rotation by hand in the converted XML file.

Feel free to give comments, ask questions, etc. :)