Functions Index :: P :: PolygonAnim

[<< up one level]

Module:

filters :: animate

Definition:

PolygonAnim(clip base, clip ovl, string f_array, val "x_array", val "y_array", val "op_array", val "w_array", val "h_array", val "mask", val "mode", val "greymask", string "output", val "ignore_conditional", val "pc_range")

Description:

Animates a clip between each segment of a sequence of frames while in parallel it overlays it on a base clip using the Overlay() standard Avisynth filter. The clip is animated on each segment along with it's corresponding mask (a full white as default, if none specified), thus allowing the application of any overlay mode supported by Overlay().

The filter accepts all arguments of the Overlay() filter, either as arrays or as single values. In the first case each frame segment has distinct values for the associated parameter; in the later case all frame segments share the same value for the associated parameter.

Thus, the filter provides a general purpose animation interface for multi-point linear (ie polygonal) position, opacity and size animation within a set of frames.

Arguments:

base: The base clip on top of which the animated ovl clip will be overlayed.

ovl: The clip to animate and overlay on top of base clip. If "mask" is not supplied, the function creates a default full opaque (white) mask equal to the dimensions of the ovl clip.

f_array: An array of ints defining the frame numbers of the end-points of each animation segment. f_array must have at least two elements.

The frame numbers must be placed in strict ascending order (ie f_array[i] < f_array[i+1] for every i) and they must all be in the range [0..base.Framecount-1].

"x_array" (Optional, defaults to Round(ovl.Width/2)): Either an array of ints with the same number of elements as f_array if varying ovl x-placement is wanted, or a single value if constant x-placement is wanted.

In the first case the x-placement of ovl is linearly animated in each segment between the specified end-point values.

In every case x_array specifies the starting position of the center [1] of the animated ovl clip on the horizontal (x) axis.

Thus if x_array is not specified the left side of ovl clip will be, taking into account possible scaling, on top of the left side of base clip (same behavior with Overlay).

"y_array" (Optional, defaults to Round(ovl.Height/2)): Either an array of ints with the same number of elements as f_array if varying ovly-placement is wanted, or a single value if constant y-placement is wanted.

In the first case the y-placement of ovl is linearly animated in each segment between the specified end-point values.

In every case y_array specifies the starting position of the center [1] of the animated ovl clip on the vertical (y) axis.

Thus if y_array is not specified the top side of ovl clip will be, taking into account possible scaling, on top of the top side of base clip (same behavior with Overlay).

"op_array" (Optional, defaults to 1.0): Either an array of floats with the same number of elements as f_array if varying ovl opacity is wanted, or a single value if constant opacity is wanted.

In the first case the opacity of ovl is linearly animated in each segment between the specified end-point values.

"w_array" (Optional, defaults to ovl.Width): Either an array of ints with the same number of elements as f_array if varying ovl width is wanted, or a single value if constant width is wanted.

In the first case the width of ovl is linearly animated in each segment between the specified end-point values.

"h_array" (Optional, defaults to ovl.Height): Either an array of ints with the same number of elements as f_array if varying ovl height is wanted, or a single value if constant height is wanted.

In the first case the height of ovl is linearly animated in each segment between the specified end-point values.

"mask" (Optional, defaults to full white mask): Either an array of clips with one less element than f_array if a distinct mask on each animation segment is wanted, or a single value if only one mask for the entire animation is wanted.

When distinct masks are provided, they are applied on a per segment basis, ie the transformation is discontinuous: mask[i] is applied on segment[i], ie on frames [f_array[i]..f_array[i+1]), mask[i+1] on segment[i+1], ie on frames [f_array[i+1]..f_array[i+2]), etc., without any smoothing transition between them.

"mode" (Optional, defaults to "blend"): Either an array of strings with one less element than f_array if a distinct overlay mode on each animation segment is wanted, or a single value if only one overlay mode for the entire animation is wanted.

When distinct modes are provided, they are applied on a per segment basis, ie the transformation is discontinuous: mode[i] is applied on segment[i], ie on frames [f_array[i]..f_array[i+1]), mode[i+1] on segment[i+1], ie on frames [f_array[i+1]..f_array[i+2]), etc., without any smoothing transition between them.

See the Overlay() documentation for the allowed values of this argument.

"greymask" (Optional, defaults to true): Either an array of bools with one less element than f_array if a distinct greymask setting on each animation segment is wanted, or a single value if only one greymask setting for the entire animation is wanted.

When distinct greymask settings are provided, they are applied on a per segment basis, ie the transformation is discontinuous: greymask[i] is applied on segment[i], ie on frames [f_array[i]..f_array[i+1]), greymask[i+1] on segment[i+1], ie on frames [f_array[i+1]..f_array[i+2]), etc., without any smoothing transition between them.

"output" (Optional, defaults to input colorspace): Has the same functionality as the corresponding argument in the Overlay() standard Avisynth function and accepts the same values.

See the Overlay() documentation for the allowed values of this argument.

"ignore_conditional" (Optional, defaults to false): Either an array of bools with one less element than f_array if a distinct ignore_conditional setting on each animation segment is wanted, or a single value if only one ignore_conditional setting for the entire animation is wanted.

When distinct ignore_conditional settings are provided, they are applied on a per segment basis, ie the transformation is discontinuous: ignore_conditional[i] is applied on segment[i], ie on frames [f_array[i]..f_array[i+1]), ignore_conditional[i+1] on segment[i+1], ie on frames [f_array[i+1]..f_array[i+2]), etc., without any smoothing transition between them.

"pc_range": (Optional, defaults to false): Either an array of bools with one less element than f_array if a distinct pc_range setting on each animation segment is wanted, or a single value if only one pc_range setting for the entire animation is wanted.

When distinct pc_range settings are provided, they are applied on a per segment basis, ie the transformation is discontinuous: pc_range[i] is applied on segment[i], ie on frames [f_array[i]..f_array[i+1]), pc_range[i+1] on segment[i+1], ie on frames [f_array[i+1]..f_array[i+2]), etc., without any smoothing transition between them.

Notes and conditions on arguments relations:

1] The last point of each segment is the first point of the next one, thus for n segments (edges) n+1 values are required for end-point settings arrays (such as f_array, x_array, etc.) while n values are required for segment properties arrays (such as mask, mode, etc.).

2] From version 1.1.0 and onwards, the implementation of the filter is based on ScriptClip(), thus allowing smaller memory footprint and consequently more complex animations than the previous versions (which were using the Animate() filter).

3] The filter uses internally the Resize filter in order to execute clip resizing when needed. To control which specific Avisynth resizer will be used by the filter place a call to SetDefaultResizer with appropriate parameters before calling the filter.

Examples:

# zoom-in a clip, sliding it from top-left to center

# and then slide it top-right, to dissapear

bc = AVISource(...) # a 720x480, 600 frames clip

oc = AVISource(...) # a 360x240 clip

f_arr = "0,100,200"

xy_path = ArrayCreate(6,4, 360,240, 720+180,-120)

x_arr = xy_path.ArrayDeplex(0, 2)

y_arr = xy_path.ArrayDeplex(1, 2)

wh_size = "12,8, 360,240, 360,240"

w_arr = wh_size.ArrayDeplex(0, 2)

h_arr = wh_size.ArrayDeplex(1, 2)

op_arr = "0,1,1"

result = PolygonAnim(bc, oc, f_arr, x_arr, y_arr, op_arr, w_arr, h_arr)

...

# move a clip top->bottom->top and in parallel

# stretch it on the left-right direction

bc = AVISource(...) # a 720x480, 600 frames clip

oc = AVISource(...) # a 360x240 clip

f_arr = "0,150,300,450,599"

x_arr = 360 # x is const, no need for array

y_arr = "120,240,360,240,120"

wh_size = "360,240, 720,120, 360,240, 720,120, 360,240"

w_arr = wh_size.ArrayDeplex(0, 2)

h_arr = wh_size.ArrayDeplex(1, 2)

op_arr = 1 # opacity is const, no need for array

# use add mode here

result = PolygonAnim(bc, oc, f_arr, x_arr, y_arr, op_arr, w_arr, h_arr, mode="add")

Further examples can be found at the Example Scripts section of the documentation.

 

[<< top]

 

[1]: Animation filters (currently LineAnim and PolygonAnim) treat parameters specifying overlay clip's (x,y) position as if they correspond to its center and not to its top-left corner as Overlay() does.

While this may seems odd, it does make the calculation of (x,y) paths simpler because in the general case size will also be animated. If this convention was not used then at any path point a correction would had to be made for the changing size of the animated clip at both x and y.

See the tutorial "Understanding animation filters" for details.