What is the timeline?

The timeline is a combination tool and library designed for Processing. It lets you draw variables.

The timeline tool is a graphical tool for the Processing Development Environment that allows you to draw curves representing variables over time. The timeline library allows you to use these variables in your sketches.

The timeline tool looks like a traditional timeline that you might see in multimedia applications like Flash, Reason, Final Cut Pro, etc. In all of these applications, the timeline has a very specific purpose. In this Processing timeline, you can use the timeline to control whatever you want in your code.

The timeline tool uses Bézier splines to represent each variable. These splines give you a lot of control, and you might already be used to this kind of drawing tool (e.g., the pen tool in Illustrator/Photoshop/Flash). However, the Bézier splines in the timeline tool have a restriction: they must never backtrack. Since we are plotting time vs. value, we have to be careful to never have more than one value for a given time.

The timeline library works by loading a data file created by the timeline tool. Using the library allows you to retrieve the value of the timeline variables at the current moment in time.

How to install

Download the latest release of the library and tool here:

Timeline (v. a003, released July 18, 2009)

This release has been testing with Processing 1.0.3 on Mac OS X and Windows XP. Unzip the file and place "TimelineLibrary" within the "libraries" folder of your Processing sketchbook and "TimelineTool" within the "tools" folder of your Processing sketchbook. Create the "libraries" and "tools" folders if they don't already exist.

Here is a description of the location of the Processing sketchbook (as described on the Processing.org libraries reference page): "To find the Processing sketchbook location on your computer, open the Preferences window from the Processing application and look for the "Sketchbook location" item at the top."

Using the tool

Launch PDE and go to "Tools" → "Timeline". Press the "Add" button in the bottom left corner to add a new variable track. Press the "Rename" button on the new track and give the variable a better name.

The current mode you're in is indicated by the selected button at the top of the screen. There are currently three modes:

Draw points — Click and drag anywhere to the right of the spline to create a new point. Click on the curve to insert a point on the curve, without changing the shape of the curve.

Move points — Click and drag points to change their location. While dragging a tangent (the circular handles), hold down the "alt" key to adjust only that tangent. With an anchor (the square handles) selected, hit "backspace" to remove that anchor and its corresponding tangents.

Draw Tangents — If you move a tangent very close to its anchor point, it will disappear. This allows you to draw sharp points. However, if you want the tangent back, use the Draw Tangents mode. Click and drag an anchor point to recreate its tangents.

The y-axis will auto-pan and auto-zoom to keep everything on screen. To pan along the time-axis, grab and drag the time ruler at the top. To zoom along the time-axis, adjust the zoom slider at the bottom of the window.

Hit the "Save" button to save to a file called "timeline-data.txt" in your sketch folder. Hitting the "Load" button will load from this file if it exists, discarding any changes you've made since your last save. Don't forget to save — the data file is the means of communication between the tool and library.

Using the library

The library is simple. In PDE, go to "Sketch" → "Import Library..." → "TimelineLibrary". This will add the following import code to the top of your sketch:

    import timeline.*; 
    

You'll want to make a global Timeline variable:

    Timeline timeline; 
    

Now in your setup code, you need to create the Timeline object. Pass it "this" so it knows about your sketch.

    void setup() {
      ...

      timeline = new Timeline(this);

      ...
    }
    

There's an optional second parameter in the constructor for sketches that do not run in realtime (i.e., the sketch is going to be rendered into a movie). The parameter is an integer that specifies the frame rate of the movie. When this parameter is specified, the library determines the current time (that corresponds to the time-axis in the timeline tool) based on the current frame, instead of the time elapsed.

Now in your drawing code, you can retrieve the current value of a variable using the getValue() method. For example, you may have created a variable in the timeline tool called "brightness". You retrieve the value by passing getValue() the name of the variable:

    void draw() {
      ...

      float value = timeline.getValue("brightness");

      ...
    }
    

That's it. Now you can do just about anything with the retrieved value. Of course, you can create multiple variable tracks in the timeline tool and use getValue() multiple times to get the value of each variable.

If you want to set the current time of a specific variable, use the setTime() method. It takes a string specifying the variable name, along with a float that specifies the time in seconds. For example, if you wanted to reset a particular variable to the beginning, you could use the following code:

    timeline.setTime("variableName", 0.0);
    

An example sketch that uses setTime is provided with the library.

Examples

There are examples distributed with the library. Once you've installed the library, go to File → Sketchbook → TimelineLibrary → Examples to look at them.

I'll go through a particularly simple example. Here's the code:

    import timeline.*;
    Timeline timeline;

    void setup() {
      timeline = new Timeline(this);
      stroke(255, 0, 255);
    }

    void draw() {
      background(0);
      float pointHeightValue = 
               timeline.getValue("pointHeight");
      point(width/2.0f, pointHeightValue);
    }
    

Now that we've got the code, we need to draw the "pointHeight" variable in the timeline tool. Go to the timeline tool by clicking on Tools → Timeline.

Create a new variable track using the "Add" button in the lower left corner and rename it to "pointHeight" by clicking the "Rename" button. Now draw a curve that represents the the y-location of the point drawn in the draw() method. Try to keep the curve between the values 0 and 400 (the height of the sketch). Press the "Save" button.

Now run the sketch. A magenta point will be drawn in the middle of the screen, with the height following the curve you drew. You are now ready to come up with your own, much more exciting examples.

Give Feedback

The best place to discuss the timeline is the timeline thread on the Processing forums. If you prefer email, send it to drifkin at the domain name of this site.