generativepy.tween module

The tween module provides simple tweening functions, to help with animation when creating movies.

You would normally create a tween object with the same length as your movie (in frames). You can build a tween object by adding sections that can:

• Maintain a constant value.
• Switch immediately to a new value on a particular frame.
• Change linearly from one value to another over a certain number of frames.
• Change in a non-linear way (easing) based on a supplied function.

After creating a tween object, you can access it like a tuple to get the value of the variable for any particular frame.

There are 2 types of tween object:

• Tween tweens a single value.
• TweenVector tweens a vector value of any dimension. It works on an element by element basis, for example if you tween from (x0, y0, z0) to (x1, y1, z1), the intermediate x values will vary linearly between x0 and x1, similar for y and z. One particular use of this is to tween between two colours (r, g, b, a).

Example

Here is an example that can be found on github as simpletween.py:

from generativepy.tween import Tween

# Create a tween
tween = Tween(3.0).wait(4).to(13.0, 5).wait(2).set(7.0, 4)

# You can use len() to fund the length of the tween in frames
print('Length = ', len(tween))

# You can access the vale#ue for a particular frame using indexing []
# or the get() function.
print('tween[7] = ', tween[5])
print('tween[8] = ', tween.get(7))

# The tween can be accessed as a sequence. Here we use a list
# comprehension to convert the values to strings that print the
# entire sequence
strings = [str(x) for x in tween]
print(', '.join(strings))

Here we create a Tween like this:

• Tween(3.0) creates an empty tween with an current value of 3.0.
• wait(4) adds 4 frames with the current value (3.0).
• to(13.0, 5) adds 5 frames that move from the current value (3.0) to 13.0. The 5 frames include the end points 3.0 and 13.0
• wait(2) adds 2 frames with the current value (13.0).
• set(7.0, 4) sets the current value to 7.0 then adds 4 frames. This gives a step change.

As the example show, the tween acts like a sequence. We can use len and indexing with [].

In the last part of the example we convert the tween to a list of strings, and print it. The result is:

3.0, 3.0, 3.0, 3.0, 3.0, 5.5, 8.0, 10.5, 13.0, 13.0, 13.0, 7.0, 7.0, 7.0, 7.0

This breaks down as:

• Tween(3.0) empty
• wait(4) adds 3.0, 3.0, 3.0, 3.0
• to(13.0, 5) adds 3.0, 5.5, 8.0, 10.5, 13.0
• wait(2) adds 13.0, 13.0
• set(7.0, 4) adds 7.0, 7.0, 7.0, 7.0

Tween

Tween provides a constructor plus the methods:

• wait
• set
• to
• get

Tween constructor

Creates an empty tween.

Tween(value=0)

Tween.wait

Adds extra frames with the current value.

wait(count)

Tween.pad

Adds extra frames with the current value to pad the total length of the tween to a target length.

pad(length)

This method is similar to wait in that it extends the length of the tween by adding extra frames set to the most recent value.

The difference is that the length parameter specifies the required frame count for the tween. That is:

• If the tween currently has a length of 20 frames, and you call pad(100), it will add however many frames are needed to make the length up to 100 (ie it will add 80 frames in this case). This might be zero. If the tween is already longer than length, it will not change (this function will not remove existing frames).
• By contrast, if the tween currently has a length of 20 frames, and you call wait(100), it will add 100 frames.

Tween.set

Sets the current value, then adds extra frames with the current value.

set(value, count=0)

Tween.to

Adds extra frames that interpolate between the current value and a new value.

to(value, count)

Adds count frames. The first frame will be set to the current values, the last frame will be set to to value. The frames in between will be set to intermediate value using linear interpolation.

On exit, the new current value will be value.

Tween.ease

Adds extra frames that interpolate between the current value and a new value, according to an easing function.

ease(value, count, ease_function)

Adds count frames. The frames will interpolate between the current value and the new value according to the ease_function.

The ease_function is a function that takes an input value in the range 0.0 to 1.0, and returns a value that varies from 0.0 to 1.0 by not usually in a linear way. The output value can also stray outside the range 0.0 to 1.0.

On exit, the new current value will be value.

Tween.get

Gets the value at a specific frame.

get(frame)

Gets the value of the frame with index frame, which will be a number value.

TweenVector

TweenVector is similar to Tween but works with vector quantities.

TweenVector is a subclass of Tween. It inherits wait, pad, and get from Tween.

TweenVector constructor

Creates an empty tween.

TweenVector(value=(0, 0))

The value should be a list or tuple of length 2 or greater.

The dimension of the initial value determines the dimension of the tween. Every other value used (in set or to) must have the same dimension (eg if you start with a value of 3 elements, every value must have 3 elements).

TweenVector.set

Sets the current value, then adds extra frames with the current value.

set(value, count=0)

The value sequence must have the same number of elements as the initial value supplied in the constructor.

TweenVector.to

Adds extra frames that interpolate between the current value and a new value.

set(value, count)

Adds count frames. The first frame will be set to the current values, the last frame will be set to to value. The frames in between will be set to intermediate value using linear interpolation of each element of the value.

On exit, the new current value will be value.

TweenVector.ease

Adds extra frames that interpolate between the current value and a new value, according to an easing function.

ease(value, count, ease_function)

Adds count frames. The frames in between will be set to intermediate values according to the ease_function, which is applied to each element of the value.

The ease_function is a function that takes an input value in the range 0.0 to 1.0, and returns a value that varies from 0.0 to 1.0 by not usually in a linear way. The output value can also stray outside the range 0.0 to 1.0.

On exit, the new current value will be value.

See also

• generativepy.drawing module
• generativepy.drawing3d module
• generativepy.color module
• generativepy.geometry module
• generativepy.movie module
• generativepy.graph module
• generativepy.formulas module
• generativepy.bitmap module
• generativepy.nparray module
• generativepy.gif module
• generativepy.utils module