# Plot Animations

::

There is no specific animation function in the Racket plot package, but animations can be build by repeatedly plotting individual frames onto a canvas or image using `plot/dc`. The technique requires drawing the entire plot every frame, which will be inefficient for complex plots. In this blog post we explore how to construct plot animations using the `set-overlay-renderers` method of a plot snip, which is a more efficient method when plots are embedded in GUI applications.

To illustrate the technique, we’ll build an animation which shows how the Sine function is generated when a point moves along the unit circle. The sine function generated is generating by taking the Y coordinate of the point and dragging if out over time:

Let’s start by plotting a single frame of the animation, the generated sine function at a fixed moment in time. Here is the Racket program which builds the single plot frame:

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16``` ```#lang racket (require plot) (define a (* 10 (/ pi 3))) ; angle at which we draw the line and sine function (plot (list (axes) (polar (lambda (theta) 1)) (lines (list (vector 0 (sin a)) (vector (cos a) (sin a)))) (lines (list (vector (cos a) 0) (vector (cos a) (sin a)))) (lines (list (vector 0 0) (vector (cos a) (sin a)))) (polar-label (lambda (theta) 1) a "") (point-label (vector 0 (sin a)) "") (function (lambda (x) (sin (+ a x))) 0 (* 2 pi))) #:height (exact-round (* 100 2)) #:width (exact-round (* 100 (+ 1 (* 2 pi))))) ```

Plots are generated using the `plot` function, which creates the plot image from a list of “renderers”, each renderer representing one element of the plot. The animated plot will need to be drawn at various angles as the “dot” travels around the unit circle, so it is a good idea to separate the angle `a` from the rest of the plot, even if it is a constant in this example. Here is an explanation of each renderer used in the image above:

• `(axes)` will draw the X, Y plot axes which intersect at origin
• `(polar (lambda (theta) 1))` will draw the unit circle at origin — the `polar` renderer will plot in polar coordinates, taking a function which converts an angle (theta) into a distance from origin, for a circle, this is simply 1.
• the next three `lines` renderers will draw the radius at the current angle, `a`, and the projections onto the X and Y axes.
• `polar-label` will place a label in polar coordinates on the unit circle at the angle `a` — the renderer will draw a dot by default plus a text value. Since we are using an empty string for the label, only the dot will be visible, marking the position on the unit circle.
• `point-label` will place a label at a specified position — this time on the Y axis, just as with `polar-label`, we use an empty label, so only a dot will be displayed.
• `(function (lambda (x) (sin (+ a x))) 0 (* 2 pi))` will draw the sine function. The `function` renderer will plot the supplied function between two values (0 and 2Π in our case), and the argument to the sine function is offset by the angle `a` to make sure the sine function has the same value at origin as the projection from the unit circle

If you are not familiar with the plot package, it would be a good idea to experiment with changing the angle `a` to various values and re-plot the image to see how the plot changes with the angle. You can also experiment with commenting out different renderers are and see what their contribution is to the overall plot.

The previous plot uses the same color and line widths for all plot elements, making it difficult to tell them apart. However, each renderer has keyword arguments which control the drawing parameters, such as colors and line widths. The documentation for the renderers shows the full list, but these are the most common arguments:

• `#:color` determines the color of the renderer. This can be a RGB triplet, but it can also be a string, naming a color from the color database
• `#:style` determines the line style, such as dashed, solid, or even transparent
• `#:width` specifies the width of the line
• `#:point-size` and `#:point-color` represent the size and color of the dots for labels.

This is the same `plot` call, but this time each renderer has been styled to use different color, sizes and line styles:

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16``` ```#lang racket (require plot) (define a (* 10 (/ pi 3))) ; angle at which we draw the line and sine function (plot (list (axes) (polar (lambda (theta) 1) #:color "firebrick" #:style 'short-dash) (lines (list (vector 0 (sin a)) (vector (cos a) (sin a))) #:style 'long-dash #:color "gray" #:width 2) (lines (list (vector (cos a) 0) (vector (cos a) (sin a))) #:style 'long-dash #:color "gray" #:width 2) (lines (list (vector 0 0) (vector (cos a) (sin a)))#:color "steelblue" #:width 2) (polar-label (lambda (theta) 1) a "" #:point-size 10 #:point-color "firebrick") (point-label (vector 0 (sin a)) "" #:point-size 5 #:point-color "firebrick") (function (lambda (x) (sin (+ a x))) 0 (* 2 pi) #:width 3)) #:height (exact-round (* 100 2)) #:width (exact-round (* 100 (+ 1 (* 2 pi))))) ```

There are several ways to generate plot animations, for example, you can generate individual images for each angle value `a`, save them to a file and use external tools to create a “movie”. Racket even has a library for writing animated GIF files. Here we’ll focus on writing plot animations which can be embedded in GUI applications.

The call to `plot` (and `plot-snip`) produces a `snip%` object, which is an interactive object that knows how to display itself and interact with the mouse — DrRacket REPL recognizes these objects and draws them in the REPL. The snip returned by the plot functions is a [2d-plot-snip%][2d-plot-snip] which provides two extra methods: `set-mouse-event-callback` and `set-overlay-renderers`. Together these methods can be used to implement interactive plots, but they can also be used separately.

The `set-overlay-renderers` method can be used to add new renderers to an existing plot and this can be used to implement animations: we can create a plot containing the “fixed” parts such as the axes and the unit circle and use `set-overlay-renderers` to construct the remaining elements periodically as the angle `a` increases:

Unfortunately, manipulating snips this way cannot be done when the snips are displayed in the REPL. This is because the REPL itself will create a copy of the snip and display the copy. The user program has no access to this copy so it cannot update it. However, we can add snips to GUI applications using the plot-container package and this will allow us to keep a reference to the plot snip and update it as needed. `plot-container` is not part of the standard Racket installation and will need to be installed using a raco command: `raco pkg install plot-container`.

Here is a simple GUI application with a single toplevel window that shows the plot snip. The program still has access to the plot snip itself as the `snip` global variable:

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17``` ```#lang racket/gui (require plot plot-container) (plot-x-label #f) (plot-y-label #f) (define toplevel (new frame% [label "Sine Function Animation"] [height (exact-round (* 100 2.6))] [width (exact-round (* 100 (+ 1 (* 2 pi))))])) (define container (new plot-container% [parent toplevel])) (define snip (plot-snip (list (axes) (polar (lambda (theta) 1) #:color "firebrick" #:style 'short-dash)) #:x-min -1 #:x-max (* 2 pi) #:y-min -1.1 #:y-max 1.1)) (send container set-snip snip) (send toplevel show #t) ```

Running this program will create the empty looking plot in a separate window:

The actual renderers for the sine function can be produced by a separate function, which takes an angle as a parameter and returns the renderers. Note that this function does not call any of the `plot` functions but simply returns these renderers, these renderers can be passed to `set-overlay-renderers` to update the plot:

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13``` ```(define origin (vector 0 0)) (define (make-sine-renderers a) (define sin-a (sin a)) (define cos-a (cos a)) (define point-on-circle (vector cos-a sin-a)) (list (lines (list (vector 0 sin-a) point-on-circle) #:style 'short-dash #:color "gray" #:width 2) (lines (list (vector cos-a 0) point-on-circle) #:style 'short-dash #:color "gray" #:width 2) (lines (list origin point-on-circle) #:color "steelblue" #:width 2) (polar-label (lambda (theta) 1) a "" #:point-size 10 #:point-color "firebrick") (point-label (vector 0 sin-a) "" #:point-size 5 #:point-color "firebrick") (function (lambda (x) (sin (- a x))) 0 (* 2 pi) #:width 3))) ```

In the DrRacket REPL we can call `set-overlay-renderers` with different arguments to `make-sine-renderers` to see how it all fits together, for example:

 `1` ```(send snip set-overlay-renderers (make-sine-renderers 1)) ```

What remains is to create a function which produces sine function renderers at regular intervals and passes them to the plot snip for rendering. This can be a simple loop with a `sleep` call, but this will not produce good results for two reasons: first, the canvas redraw time cannot be controlled, so a call to `set-overlay-renderers` will simply queue a redraw request which will happen later and second, the mechanism we chose will produce a lot of garbage: each time we call `make-sine-renderers` the function will allocate data for the renderers, these will be displayed once, than never used again — as memory accumulates, Racket will stop the running program to reclaim the memory.

We cannot perfectly address these issue, but we can alleviate it: we’ll keep track of the animation time and run the garbage collector at regular intervals, hoping that its impact on performance will be smaller.

Instead of animating based on angle, we will animate based on time and we’ll use an angular velocity to calculate the angle corresponding to a timestamp: `make-animation-frame` produces the renderers at a time `t` and it does so simply by calculating the angle and calling `make-sine-renderers`:

 ```1 2 3 4``` ```(define angular-velocity (* 0.1 (* 2 pi))) ;; 2 PI is 1 rotation / second (define (make-animation-frame t) (make-sine-renderers (* t angular-velocity))) ```

The `do-animation` function is responsible for keeping track of the animation time, periodically calling `make-animation-frame` and updating the plot snip with the new renderers followed by a minor garbage collection. To ensure that each frame starts at a reasonably precise interval, the function keeps track of the duration of the redraw and garbage collection which is subtracted from the amount of time the function sleeps before starting a new iteration:

 ```1 2 3 4 5 6 7 8 9``` ```(define (do-animation fn #:frame-rate [frame-rate 60]) (define frame-time (/ 1 frame-rate)) (define start-timestamp (current-inexact-milliseconds)) (let loop ([timestamp (current-inexact-milliseconds)]) (send snip set-overlay-renderers (fn (/ (- timestamp start-timestamp) 1000.0))) (collect-garbage 'incremental) (define remaining (- frame-time (- (current-inexact-milliseconds) timestamp))) (sleep/yield (max 0 remaining)) (loop (current-inexact-milliseconds)))) ```

Calling `(do-animation make-animation-frame)` produces a smooth looking animation:

Originally, `set-overlay-renderers` was indented to be used to add plot annotations, such as hover labels, in response to mouse events, however, the method can be used separately. Since, the “fixed” plot part will be rendered to a bitmap only once, and only the additional renderers will have to be recalculated and plotted, this can be more efficient than creating animations which render the entire plot area every frame.