generativepy.tween module


Martin McBride, 2020-08-08
Tags tweening
Categories generativepy generative art

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.

After creating a tween object, you can access it 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)
Parameter Type Description
value number Initial current value.

Tween.wait

Adds extra frames with the current value.

wait(count)
Parameter Type Description
count int Number of frames to add.

Tween.set

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

set(value, count=0)
Parameter Type Description
value number New value.
count int Number of frames to add. Can be zero.

Tween.to

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

set(value, count=0)
Parameter Type Description
value number New value.
count int Number of frames to add. Can be zero.

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.get

Gets the value at a specific frame.

get(frame)
Parameter Type Description
frame int Frame to get

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 constructor

Creates an empty tween.

TweenVector(value=(0, 0))
Parameter Type Description
value number sequence Initial current value.

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.wait

Adds extra frames with the current value.

wait(count)
Parameter Type Description
count int Number of frames to add.

TweenVector.set

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

set(value, count=0)
Parameter Type Description
value number sequence New value.
count int Number of frames to add. Can be zero.

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=0)
Parameter Type Description
value number sequence New value.
count int Number of frames to add. Can be zero.

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 sequence.

On exit, the new current value will be value.

TweenVector.get

Gets the value at a specific frame.

get(frame)
Parameter Type Description
frame int Frame to get

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

Copyright (c) Axlesoft Ltd 2020