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")
|