# teaching machines

## Timing in Twoville

Twoville serves two very different domains: physical fabrication and digital animation. Fabricators use Twoville to describe static geometric shapes that can be fed into a cutting machine and turned into a tangible object. Animators use Twoville to orchestrate purely virtual cinematic progressions in which the actors are geometric shapes. The thread binding these two domains together is geometry.

For most of Twoville’s life, I’ve focused on building up this shared geometric foundation. But this past summer, my collaborator and I read up on programmatic animation systems, and we were glad to find that not everything has been figured out. We are ready to blaze our own trail. I’m here to document my preliminary vision for an expressive, code-based animation system.

### Time Awareness

In general-purpose programming languages, time is not a recognized concept. There’s no builtin notion of state being a function of time. Such ideas are manufactured out of simpler primitives, requiring animation libraries to provide routines like this one:

rectangle.animate('size', startTime, startSize, endTime, endSize)


The syntax here is just a standard functional call. Only the names indicate that this call effects an animation.

I want Twoville to be aware of time. It should not just be another parameter to a function call. The syntax of the language should reflect that time is not just data but an integral part of the arc of the program.

### Property Major vs. Time Major

Many graphical animation systems provide a timeline editor. Time runs on the x-axis, and animated properties run along the y-axis. This two-dimensional layout affords animators two viable indices into the animation system. If I am concerned about what’s happening at a particular keyframe, I index into the animation using a time value. If I am concerned about a particular visual property, I index into the animation using the property name.

When we express an animation in code, we lose the organizational power of the timeline. In a callback-driven animation system, the notion of a timeline is implicit. Our draw callback is organized entirely around the properties that need to be updated, as seen in this projectile motion animation:

function draw(t)
position.x = velocity.x * t
position.y = -4.9 * t * t + velocity.y * t
if t > duration / 2
color = red
else
color = blue


In an imperative scheduling animation system, we might organize around either index. There is no natural ordering. To enlarge and then shrink a rectangle as we also change its color, for example, we might issue the following calls, which are “property major”:

rectangle.animate('size', startTime, smallSize, midTime, bigSize)
rectangle.animate('size', midTime, bigSize, endTime, smallSize)

rectangle.animate('color', startTime, blue, midTime, red)
rectangle.animate('color', midTime, red, endTime, blue)


We could just as easily choose this “time major” order:

rectangle.animate('size', startTime, smallSize, midTime, bigSize)
rectangle.animate('color', startTime, blue, midTime, red)

rectangle.animate('size', midTime, bigSize, endTime, smallSize)
rectangle.animate('color', midTime, red, endTime, blue)


In a declarative scheduling animation system, we tend to organize by time. This CSS keyframe animation is one such example:

@keyframes big-red {
0% {
width: 100px;
height: 100px;
background-color: blue;
}
50% {
width: 200px;
height: 200px;
background-color: red;
}
100% {
width: 100px;
height: 100px;
background-color: blue;
}
}


Twoville has imperative elements, but many programs are simple declarative descriptions. Therefore, I am favoring a syntax for animation that supports declarative scheduling. Following convention, the animations will be time major.

### Timelines and Intervals

Under the hood, each animatable property in Twoville is not a static memory cell but a data structure that I’ve named Timeline. To schedule a property to have a certain value at a certain time on a Timeline, we do not use keyframes. Keyframes assume continuity on both sides of a keyframe. As time nears the keyframe, we approach the target value. As time leaves the keyframe, we depart from the target value. But animations do not always exhibit such continuity. A ball may fly off one side of the screen only to reenter on a different side.

Graphical timeline editors often give us the option to make “two-sided” keyframes. I’m attempting to emulate this two-sidedness with a notation built on intervals rather than keyframes. A property’s Timeline is composed of one or more intervals. The syntax for intervals is inspired by the limit notation of calculus. The fragment t -> 100 means “as time approaches 100.” The fragment 100 -> t means “as time departs from 100.”

By composing these fragments, I’ve built up a small catalog of different interval structures that I have encountered in animations. Let’s walk through them.

#### From and To

To animate a simple progression from one value to another, we use a from-interval like 0 -> t and a to-interval like t -> 100. Together they form a closed interval on a Timeline.

Scrub on the slider in this example to see how the square’s size changes:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 100
size = [100, ~]

var twovilleDiv = jQuery('#twoville_to');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_to').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 100
size = [100, ~]



#### Between

If a property holds steady, we express this with a between-interval like 0 -> t -> 50. Here we have two between-intervals, with a discontinuity at frame 50:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> t -> 50
size = [5, ~]
50 -> t -> 100
size = [100, ~]

var twovilleDiv = jQuery('#twoville_between');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_between').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> t -> 50
size = [5, ~]
50 -> t -> 100
size = [100, ~]



Between-intervals are really just syntactic sugar for a from-interval connected to a subsequent to-interval.

#### Through

If we do want continuity, we use a through-interval like t -> 50 -> t. Here we enlarge the square and shrink it back down:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 50 -> t
size = [100, ~]
t -> 100
size = [5, ~]

var twovilleDiv = jQuery('#twoville_through');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_through').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 50 -> t
size = [100, ~]
t -> 100
size = [5, ~]



Through-intervals are really just syntactic sugar for a to-interval connected to a subsequent from-interval.

#### From Stasis

If we want steadiness followed by a smooth departure from that steadiness, we use a from-stasis-interval like 0 -> 50 -> t. Here the square holds small for a while and then shrinks:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> 50 -> t
size = [5, ~]
t -> 100
size = [100, ~]

var twovilleDiv = jQuery('#twoville_from-stasis');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_from-stasis').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> 50 -> t
size = [5, ~]
t -> 100
size = [100, ~]



From-stasis-intervals are really just syntactic sugar for a from-interval connected to a subsequent to-interval connected to a subsequent from-interval.

#### To Stasis

If we want to approach a value and then hold, we use a to-stasis-interval like t -> 50 -> 100. Here the square grows and then holds:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 50 -> 100
size = [100, ~]

var twovilleDiv = jQuery('#twoville_to-stasis');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_to-stasis').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 50 -> 100
size = [100, ~]



To-stasis-intervals are really just syntactic sugar for a to-interval connected to a subsequent from-interval connected to a subsequent to-interval.

#### Through Stasis

If we want to approach a value, then hold, and then depart from that value, we use a through-stasis-interval like t -> 25 -> 75 -> t. Here the square grows, holds, and shrinks:



with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 25 -> 75 -> t
size = [100, ~]
t -> 100
size = [5, ~]

var twovilleDiv = jQuery('#twoville_through-stasis');
twovilleDiv.closest('pre').replaceWith(twovilleDiv);
document.getElementById('twoville_form_through-stasis').submit();

with rectangle()
color = :cornflower
center = [50, ~]
0 -> t
size = [5, ~]
t -> 25 -> 75 -> t
size = [100, ~]
t -> 100
size = [5, ~]



Through-stasis-intervals are really just syntactic sugar for a to-interval connected to a subsequent from-interval connected to a subsequent to-interval connected to a subsequent from-interval.