Timelines Isis software documentation

Timelines

A timeline is a special storage construct that might be considered an array with real-number indices and interpolation. Values can be placed at real-numbered key points along a one-dimensional line. Linear or cubic interpolation may be specified between each consecutive pair of key points. The timeline may then be queried for its value at arbitrary real-numbered locations.

Timelines express a relationship between two variables. For example, you can create timelines that relates time to position or scale to create animations. Also, timelines don't necessarily have to be used for time-related variables. They could be used to relate frame numbers to transparency levels, or positions to images, or temperatures to noise volumes. Dynamic behaviors are made possible by the fact that the key points on a timeline may be added, changed, or removed at will.

Creating a timeline

(set tl (new-timeline)) # creates a new timeline new-timeline creates a new timeline object and returns it as a procedure. You can modify and query the timeline by calling this procedure with different kinds of arguments.

Placing key points and using interpolation

(tl time val) # insert key value at time (tl time val interp) # insert key with interpolation (tl time leftsideval interp rightsideval) # two-sided key value Calling the timeline with 2 or more arguments adds a new "key point" on the timeline. The first argument is the time and the second is the value that should be placed at that time. If a point at that time already exists, it is replaced.

By default, this value becomes the value of the timeline at all points to the right of that point on the timeline, up to the next defined point. However, you can also apply linear or cubic interpolation between each pair of consecutive points by passing a third argument which represents the type of interpolation that should occur between the point being defined and the previous point on the timeline. Here are the recognized interpolation types:

interp-none interp-linear interp-cubic

You may place any kind of Isis value on the timeline, but interpolation will only occur if the key points involved are of the same type and are numeric in some way.

Sometimes it is necessary to define a point on the timeline that has one value on the left (used for interpolation with the previous point) and a different value on the right. You can do this by passing a fourth argument which will become the value on the "right" of the point.

Retrieving the value at a particular point

(tl time) # retrieve value at time Calling the timeline with a single argument returns the value of the timeline at that time. The type of returned value will be the same as the type of the key point directly before the location being queried. Also, where cubic interpolation has been specified, there must be at least 2 key points on each side of the location being queried. If the location queried is before all defined key points, Null is returned.

Repeating a pattern

(tl 'w' wraptime) # wrap to 0.0 at this interval If you want to create a timeline with a repeating pattern at a certain interval, call the timeline with the character 'w' (for wrap) and the interval time. The section of the timeline from 0.0 to that time will effectively repeat itself, in both the positive and negative directions. Wrapping does not affect the placement of new points on the timeline--they may be placed outside of the wrap zone with no problem. Set the interval time to 0.0 to disable wrapping.
(set wtl (new-timeline)) (wtl 0 0.0) (wtl 10 100.0 'l') (wtl 'w' 3.0) # specifies wrap every 3.0 time units -> (wtl 2.0) 20.000000 -> (wtl 2.5) 25.000000 -> (wtl 3.0) # will wrap to time value 0.0 0.000000 -> (wtl 3.5) 5.000000

Examples

Here is a simple example of a timeline with 2 key points and linear interpolation between them:
(set tl (new-timeline)) (tl 0 100) (tl 10 200 interp-linear) -> (tl 6) 160 -> (tl 6.6) 165 -> (tl 13.0) 200 -> (tl -3) Null
In the following example, time is related to a 3-dimensional location, with both linear and cubic interpolation between different key points:
(set rtl (new-timeline)) (rtl 0.0 [2.0 4.0 6.0]) (rtl 20.0 [10.0 42.0 85.0] interp-linear) (rtl 30.0 [-34.0 -40.1 -234.4] interp-cubic) (rtl 40.0 [23.3 354.3 123.4] interp-cubic) -> (rtl 10) [ 6.000000 23.000000 45.500000 ] -> (rtl 4.6793) [ 3.871720 12.890670 24.483235 ] -> (rtl 20.3) [ 9.369685 41.024039 80.745221 ] -> (rtl 28.5) [ -32.391944 -52.456888 -219.376075 ]
The following example shows a simple timeline with a two-sided key point as discussed above:
(set dtl (new-timeline)) (dtl 0 10.0) (dtl 1 200.0 interp-linear "fred") -> (dtl 0.345) 75.550000 -> (dtl 0.95) 190.500000 -> (dtl 1.3) "fred"

Longer examples

Here is a longer example that demonstrates how several timelines can be used together to control animations. More examples can be found on the Macaroni documentation page.

Copying a timeline

(tl) # return entire timeline in a list (set tlcopy (new-timeline (tl))) # make separate copy of timeline new-timeline itself can also accept a single list argument which represents a timeline. This provides a handy way to create a new timeline from an old one. Important: the key points in this list must be in chronological order! They will not be sorted automatically.
-> (dtl) [ [ 0.000000 10.000000 ] [ 1.000000 200.000000 'l' 42 ] ] -> (set dtlcopy (new-timeline (dtl))) Proc -> (dtlcopy 0.53343) 111.351700

Requirements:
Scripts: (load "timeline.isis")