bonnyfone / vectalign

Tool for create complex morphing animations using VectorDrawables (allows morphing between any pair of SVG images)

VectAlign

VectAlign (a.k.a. VectorDrawableAlign) is a developer's tool which automagically aligns two VectorDrawable "pathData" strings (or SVG images) in order to allow morphing animations between them using an AnimatedVectorDrawable. VectAlign can be used from command line or through a simple GUI (which includes morphing preview and export functionalities).

Here are some examples of what you can do with the help of VectAlign (take a look at the sample project for a live demo):

The problem

As stated in the official docs two paths must be compatible so that they can be morphed, which means that the paths must be composed by the same list of SVG commands (in terms of length and type of commands).

Example of compatible paths:

M 10,10 L 40,10 L 40,40 L 10,40 Z
M 25,10 L 40,25 L 25,40 L 10,25 Z

Example of incompatible paths:

M 10,10 L 40,10 L 40,40 L 10,40 Z
M 30,30 L 10,10 C 14,25 20,30 10,49 L 3,3 L 0,8 Z

Creating an AnimatedVectorDrawable containing morphing animations which use incompatible paths leads to runtime exceptions like the following:

android.view.InflateException: Binary XML file line #3 Can't morph from M 10,10 L 40,10 L 40,40 L 10,40 Z  to  M 30,30 L 10,10 C 14,25 20,30 10,49 L 3,3 L 0,8 Z
        at android.animation.AnimatorInflater.setupAnimatorForPath(AnimatorInflater.java:337)
        at android.animation.AnimatorInflater.parseAnimatorFromTypeArray(AnimatorInflater.java:283)
...

When the morphing involves only simple shapes is averagely simple to fix the paths by manually injecting or duplicating commands here and there; but when the complexity of the shapes grows, this task becomes quite tedious to do by hand (sometimes almost impossible). VectAlign automagically aligns any pair of SVG paths (regardless of their complexity), creating a new pair of morphable paths without altering the original images.

Download

You can download the latest version of the pre-compiled jar from here.

Changelog

• v0.2

• added different morphing strategies (BASE, LINEAR, SUB_BASE, SUB_LINEAR)

• added GUI (view, load and edit SVG/pathData, morphing preview)

• added export function (automatically creates all the Android XML resources required)

• v0.1

• first public release of VectAlign (command line only)

Usage

Run VectAlign from command line by passing the two paths that you want to use in your morphing animation; you can pass these sequences by typing them directly or by referring a file (a simple txt file or even a standard SVG image); simply pass no params if you want to start the GUI:

Examples of execution

Run VectAlign in GUI mode:

java -jar  vectalign.jar 

java -jar  vectalign.jar --gui

Run VectAlign in command line mode:

java -jar  vectalign.jar   --start "M 10,20..."   --end "M 30,30..."

java -jar  vectalign.jar   --start image1.svg   --end image2.svg

The result represents the aligned (and compatible) version of the input paths/images: these new paths can be finally morphed using an AnimatedVectorDrawable without incurring in the "Can't morph from X to Y" exceptions:

Example of output

--------------------
  ALIGNMENT RESULT  
-------------------- 
# new START sequence:  
M 48.0,54.0 L 31.0,42.0 L 15.0,54.0 L 21.0,35.0 L 6.0,23.0 L 25.0,23.0 L 25.0,23.0 L 25.0,23.0 L 25.0,23.0 L 32.0,4.0 L 40.0,23.0 L 58.0,23.0 L 42.0,35.0 L 48.0,54.0 

# new END sequence:  
M 48.0,54.0 L 48.0,54.0 L 48.0,54.0 L 48.0,54.0 L 31.0,54.0 L 15.0,54.0 L 10.0,35.0 L 6.0,23.0 L 25.0,10.0 L 32.0,4.0 L 40.0,10.0 L 58.0,23.0 L 54.0,35.0 L 48.0,54.0 

Available options

usage: java -jar vectalign.jar  [-g] [-s <"string"|txt_file|svg_file>] [-e <"string"|txt_file|svg_file>] [-m <BASE|LINEAR|SUB_BASE|SUB_LINEAR>] [-v] [-h]

Align two VectorDrawable paths in order to allow morphing animations
between them.

 -g,--gui                                      Start VectAlign GUI
 -s,--start <"string"|txt_file|svg_file>       Starting VectorDrawable
                                               path ("string", txt file or
                                               SVG file)
 -e,--end <"string"|txt_file|svg_file>         Ending VectorDrawable path
                                               ("string", txt file or SVG
                                               file)
 -m,--mode <BASE|LINEAR|SUB_BASE|SUB_LINEAR>   Aligning technique (default
                                               is BASE)
 -v,--version                                  Print the version of the
                                               application
 -h,--help

How it works

VectAlign is based on an adaptation of the Needleman-Wunsch algorithm, which is used in bioinformatics to align protein or nucleotide sequences.

Notes and known issues

• This is an experimental tool which faces a complex task. Result's quality may vary depending on the inputs; thus, wow effect of the resulting animation is not guaranteed.
• Aligning complex shapes may create visual artifacts on one or both images; in this case, try to simplify the original SVG path (e.g. using InkScape) and then run VectAlign again (see also the Tips section).
• When referring a SVG file, all the path groups which compose the image will be merged in one single path.
• If your SVG path is too much complex the system renderer will throw a silent exception: "OpenGLRenderer﹕ Path too large to be rendered into a texture"; in this case you need to simplify your image further.

Tips

• When morphing complex aligned paths, for best result avoid using the fillColor attribute in your VectorDrawable and use the strokeColor only. This because filled surfaces are more likely to be affected by artifacts than the stroke-only ones and usually provide less gorgeous morphing effects.
• As general rule, similar images (in terms of SVG complexity) morph better than very different ones.
• If you don't like the result of a morphing, try to alter the original images by simplifying the SVG path (e.g. using InkScape) and then run VectAlign again.
• Since AnimatedVectorDrawable is API 21+ you can use the vector-compat library to extend support down to API 14+.

References

• DevBytes: Android Vector Graphics
• AnimatedVectorDrawable
• VectorDrawable
• VectorDrawableCompat on support library v7 (partial)
• SVG Paths Specification

License

Copyright 2015, Stefano Bonetta.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

vectalign's Issues

Request: put an executable ...

so that all could run it without the need to compile it first.

java.lang.ArrayIndexOutOfBoundsException

java -jar vectalign-0.2-jar-with-dependencies.jar --start "M 16 17 A 1,1,0,1,0,15,16 A 1,1,0,0,0,16,17 Z M 16 18 A 2,2,0,1,1,18,16 A 1.9994,1.9994,0,0,1,16,18 Z M 16.95 15.948 L 16.4 15.948 L 16.4 15.125 L 15.577 15.125 L 15.577 15.948 L 15.028 15.948 L 15.988 16.91 Z" --end "M16,26C21.52,26 26,21.52 26,16C26,10.48 21.52,6 16,6C10.48,6 6,10.48 6,16C6,21.52 10.48,26 16,26ZM16,28C9.37,28 4,22.63 4,16C4,9.37 9.37,4 16,4C22.63,4 28,9.37 28,16C28,22.63 22.63,28 16,28ZM21.7,15.69L18.4,15.69L18.4,10.75L13.46,10.75L13.46,15.69L10.17,15.69L15.93,21.46L21.7,15.69Z" --mode BASE

Sequences sizes: 16 / 21
Aligning mode: BASE
0. align iteration...
Alignment found!
M A A # # # # L M A A # # # # L M # L L L L L L L
M # # C C C C L M # # C C C C L M L L L L L L L L
Sequence aligned! (25 elements)
###################### EXCEPTION #####################
java.lang.ArrayIndexOutOfBoundsException: 7
at com.bonnyfone.vectalign.techniques.BaseFillMode.fillInjectedNodes(BaseFillMode.java:93)
at com.bonnyfone.vectalign.VectAlign.align(VectAlign.java:120)
at com.bonnyfone.vectalign.Main.main(Main.java:104)
######################################################

Creates a small graphics issue

Hi @bonnyfone

Thank you for this library.

The Icons

The start icon (SVG): https://storage.googleapis.com/material-icons/external-assets/v1/icons/svg/ic_menu_white_24px.svg

The end icon (SVG): https://storage.googleapis.com/material-icons/external-assets/v1/icons/svg/ic_close_white_24px.svg

The Path generated by Vect Align

Start path (drawer_path):
M 3.0,18.0 l 18.0,0.0 l 0.0,-2.0 l -18.0,0.0 l 0.0,2.0 L 3.0,18.0 m 0.0,-5.0 l 18.0,0.0 l 0.0,-2.0 l -18.0,0.0 l 0.0,2.0 L 3.0,13.0 M 3.0,6.0 L 3.0,6.0 L 3.0,6.0 L 3.0,6.0 L 3.0,6.0 L 3.0,6.0 L 3.0,8.0 L 21.0,8.0 L 21.0,6.0 L 3.0,6.0 L 3.0,6.0

End path (close_path):
M 19.0,6.41 l 0.0,0.0 l 0.0,0.0 l 0.0,0.0 l 0.0,0.0 L 17.59,5.0 m 0.0,0.0 l0.0,0.0 l 0.0,0.0 l 0.0,0.0 l 0.0,0.0 L 12.0,10.59 M 12.0,10.59 L 6.41,5.0 L 5.0,6.41 L 10.59,12.0 L 5.0,17.59 L 6.41,19.0 L 12.0,13.41 L 17.59,19.0 L 19.0,17.59 L 13.41,12.0 L 19.0,6.41

Screenshot of the issue

XML Files in the Project:

Vector FIle (ic_drawer.xml):

<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24"
    android:viewportHeight="24">

    <path
        android:name="v"
        android:fillColor="#FFFFFF"
        android:pathData="@string/drawer_path" />

</vector>

Animated Vector File (ic_drawer_to_close.xml):

<?xml version="1.0" encoding="utf-8"?>
<animated-vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/ic_drawer">

    <target
        android:name="v"
        android:animation="@anim/drawer_to_close" />

</animated-vector>

The Anim File (drawer_to_close.xml):

<?xml version="1.0" encoding="utf-8"?>
<objectAnimator xmlns:android="http://schemas.android.com/apk/res/android"
    android:duration="650"
    android:propertyName="pathData"
    android:valueFrom="@string/drawer_path"
    android:valueTo="@string/close_path"
    android:valueType="pathType" />

I hope you help me with this issue.

>> Paths are already morphable!!! Leaving sequences untouched <<

---

ALIGNMENT RESULT

new START path:

new END path:

These sequences are morphable and can be used as 'pathData' attributes inside of VectorDrawable files.

why?

.jar download source is deprecated

Hello!

I tried to download the precompiled .jar but bintray is not hosting it anymore. Can you please set up another source for it?
Cheers,
Best wishes,
Wiktor

New on github

Hey bonny, im new on github and i wanna use this repository but dont know how, is there a tutorial or something I can watch to know exactly how to open and use the jar in command line? thanks

java.lang.ArrayIndexOutOfBoundsException in checkPenPosValidity

I am developing dynamic symbolic execution tool for Java programs. Now I am using it as fully automatic tool for defect detection on some open source programs from GitHub. It has found some java.lang.ArrayIndexOutOfBoundsExceptions in VectAlign:

java.lang.ArrayIndexOutOfBoundsException: -1
	at com.bonnyfone.vectalign.techniques.BaseFillMode.checkPenPosValidity(BaseFillMode.java:110)
	at com.bonnyfone.vectalign.techniques.BaseFillMode.fillInjectedNodes(BaseFillMode.java:101)
	at com.bonnyfone.vectalign.VectAlign.align(VectAlign.java:120)
	at com.bonnyfone.vectalign.Main.main(Main.java:104)
	at jia.test.big.VectalignTest.main(VectalignTest.java:23)

Constructed input was manually minimized to -s L -e M.

Arguments to and from (returned from method doRawAlign) of fillInjectedNodes method are empty ArrayLists. So I think either doRawAlign should not return empty lists or checkPenPosValidity should have additional check on its arguments.

Input is incorrect, so, please let me know is this a bug or undefined behavior caused by incorrect input. In other words, do you think analyzer has reported a real bug or a false positive.

Suggestion: Add morphed "rotation" setting

So, when playing with vectalign I noticed that it fails a lot of the time when trying to morph between assets where the "centerline", that is, the visual rotation axis where two assets should meet at an intermediary representation, isn't aligned.
Take a play and a pause icon for example:
The play icon is "visually", with respect to its symmetry, rotated 90 degrees clockwise relative to the pause icon. Rotating the play icon -90 degrees before morphing generates a much smoother transition.
Solution would be to add a rotation to one/other of the assets in the transition.