Understanding animation filters
Table of contents
Animation filters use a combination of the Overlay and ScriptClip standard Avisynth filters in order to achieve animation of position (x and y coordinates) and opacity of the overlayed clip (the clip to be animated) on top of the base clip. Furthermore, they use the Resize filter in order to achieve animation of size (width and height) of the overlayed clip.
From AVSLib version 1.1.0, animation filters are rewritten internally (use of C++ plugins instead Avisynth scripts and also change of algorithm, so that ScriptClip instead of Animate is used at the core) in order to improve memory usage and execution speed. The new version of animation filters is now capable of executing complex animations in a single script; see the 14th example script for more information.
There is a version for animating between two end points (frame numbers) of a clip, LineAnim(), as well as a version for animating between an arbitrary number of consecutive points (frames) of a clip, PolygonAnim(). At each frame number (x,y) position, opacity and size (width,height) can be set independently. The change of them between animation end-points is linear.
For the PolygonAnim() there is also the ability to specify different parameters regarding the way that the animated clip is overlayed in each animation segment (such as overlay mode, mask clip, whether the mask is a greyscale one, etc.).
Thus in principle animation filters can achieve the simulation of any 3D movement of a clip with reference to the base clip's viewport in which at least one axis remains parallel to one axis of the viewport (that is rotations are excluded except for the case of rotation along the x or y axes, where it can be simulated with a series of resize-shift-resize steps and an auxiliary "back" clip) without the need to resort to external plugins.
Animation coordinate system
Animation filters use a coordinate system in which (x,y) coordinates are displaced by half the width and height of the overlayed clip (ie if w,h are the later, xa = x - w/2, ya = y - h/2). The axes retain the direction of the standard clip coordinate system (x increases to the right and y to the bottom of the clip).
The selection may seem a bit uncommon at first site, but it was made for a good reason: to allow easy calculation of the placement of a clip which is animated both in position and size.
Indeed it is a lot easier to define a movement for a clip that constantly changes size in terms of its center; else a detailed knowledge of its size in each frame is needed to modify the coordinates defining its upper left corner. Since the size animation functions produce a clip in which the size animated, overlayed clip is assured to be always centered, it suffices to subtract half the width and height in order to achieve the desired transformation.
To account for this displacement of coordinates inside the animation filters the user must add the same amounts (w/2 for x and h/2 for y) to every end point passed to them.
For example, if the final size animated clip has (w,h) dimensions equal to (400,200) and we want to position animate it across a polygon defined by the points
(0,0), (150,50), (300,250), (300,350), (150,370), (-400,300),
with respect to its top-left corner, we must add 200 to each x and 100 to each y value in order to get the polygon points with respect to its center. The points will then be
(200,100), (350,150), (400,350), (400,450), (350,470), (-200,400).
The significance of masks
All animation filters use masks in order to animate any type of clip on top of any type of clip and allow consequtive stacking of an arbitrary number of animated clips on a base clip without interference with previous animations. If no mask is provided, the functions create an all-white mask with the dimensions of the animated clip.
The masks are animated in parallel with the animated clip. Thus, at each frame the clip affects only the area on top of which is positioned and all the modes (and other arguments) supported by the Overlay standard Avisynth filter can be applied without nasty side effects to other areas of the base clip. This mechanism also makes possible to stack animations on the base clip without cross-interference.
Since the masks are clips and there are argument slots in the animation filters for the user to supply them explicitly, it is possible to provide masks that they transform during the clip's duration.
This makes possible to animate the shape of the clip also (for example to gradually turn it from rectangular to elliptical, or to a star-like or an irregular shape, or simulate rotation by creating a rotated white area inside a full-black mask, etc.). The possibilities are endless.
The only thing that one has to pay attention, if YUV clips are used as masks, is that all masks passed in must be in the full (PC) range (this is a requirement of Overlay, which is propagated by the animation filters, since they use Overlay internally).
Usage tips and examples
First of all, except for the simpler cases, create a scenario. Define what effects you want to achieve and the sequence of events necessary to implement them. Next, identify the components needed for implementing them (filters, AVSLib functions and data structures, etc.). Then follow the guidelines presented below:
- Organise the animation to small blocks (preferably functions) that can easier be conceived, implemented, tested and debugged. You can then later chain the blocks to produce the overall animation.
- Proceed step-by-step, verifying the correct operation of each block before going to the next; it is easier to spot the correct location of errors this way.
- When constructing animation paths always take into account the different coordinate system used by the animation filters and compensate for that. You may find it easier to work on the usual top-left coordinate system and then convert values. If you select this way, you will find ArrayOpValue() extremely useful.
- The standard way to animate multiple clips on top of a base clip is to order the first animation on top of the base clip and then order each subsequent animation on top of the previous result.
For this to work correctly it is essential that masks, if used, are in the full PC range.
Also it is advisable to convert the base clip to a YUV colorspace before applying the animations in order to avoid excess conversions back and forth between RGB and YUV that are made by the Overlay standard Avisynth function; else final result's chroma quality will be affected.
Examples of animation filters' uses are provided by some of the example scripts included with AVSLib documentation.