Terrapin Turtle Graphics

From Wikipedia, the free encyclopedia

Terrapin Turtle Graphics
Developed by	Spencer Tipping
Latest release	2.1 / May 17, 2008
OS	Linux, Unix, Microsoft Windows, Mac OS, other operating systems with JRE implementations
Genre	Educational software
License	LGPL
Website	http://xenon.truman.edu/~sjt309

Terrapin Turtle Graphics is a simple turtle graphics programming library for Java. It is released under the LGPL. Distinguishing characteristics include an extension into three dimensions and the ability to create highly detailed and realistic drawings using colors and antialiased rendering.

Sphere example included with Terrapin

1 Architecture
2 Turtle API
3 User Interface
4 Known Bugs
5 See Also
6 External Links

[edit] Architecture

Terrapin is broken into two major pieces: The turtle, which executes drawing commands, and the turtle drawing window, which displays the output. Materially, these are analogous to a piece of chalk and a chalkboard, respectively. To create visible output, a turtle drawing window and a turtle must each be created, the turtle must be added to the window, and then drawing commands must be issued to the turtle. This code, for example, will produce a square:

 import terrapin.*;
 public class Square {
   public static void main (String[] args) {
     TurtleDrawingWindow w = new TurtleDrawingWindow ();
     Turtle t = new Turtle ();
     w.add (t);
     w.setVisible (true);
     for (int i = 0; i < 4; i++) {
       t.move (100);
       t.turn (90);
     }
   }
 }

Internally, a turtle is represented as an object that produces line segments that are rendered by the window. Other objects that produce line segments, such as grids or axes, are also available and may be added to a window; for example, this code will produce a square positioned on a grid:

 TurtleDrawingWindow w = new TurtleDrawingWindow ();
 AxialGrid g = new AxialGrid (AxialGrid.XY_PLANE);
 Turtle t = new Turtle ();
 w.add (t);
 w.add (g);
 w.setVisible (true);
 for (int i = 0; i < 4; i++) {
   t.move (100);
   t.turn (90);
 }

Multiple turtles can be added as well, allowing for two separate drawings to be produced simultaneously:

Multiple turtle example included with Terrapin

 TurtleDrawingWindow w  = new TurtleDrawingWindow ();
 Turtle t1 = new Turtle ();
 Turtle t2 = new Turtle ();
 w.add (t1);
 w.add (t2);
 w.setVisible (true);
 t2.turn (-45);
 for (int i = 0; i < 4; i++) {
   t1.move (100);
   t1.turn (90);
   t2.move (100);
   t2.turn (90);
 }

[edit] Turtle API

Fractal tree example included with Terrapin

Complete API documentation is maintained in AsciiDoc format in the Terrapin distribution, however here is an overview of the basic methods provided by the turtle and window classes:

Turtle class
- move(distance): Moves the turtle distance units forward (by default, a unit is a pixel) if distance is positive, and distance units backwards if distance is negative. If distance is zero, then move does nothing. A line is drawn between the turtle's old location and new location if the turtle's pen is down.
- jump(distance): Identical to move, but does not draw a line.
- turn(angle): Turns the turtle within its plane by angle degrees. By default, the turtle is facing due east, or directly to the right on a computer screen. The official method for this operation is turnTheta, which explicitly specifies the theta axis of rotation.
- turnPhi(angle): Turns the turtle's plane or cone, depending on the coordinate model being used, by angle degrees. The example files included with the Terrapin distribution include examples of the role of the phi coordinate, as does the Terrapin website, http://xenon.truman.edu/~sjt309.
- pushTurtleState(), popTurtleState(): Each turtle maintains a stack of states, which are defined by the turtle's location and headings. Together, these methods may be used to define fractal formations (see the "Tree" example in the Terrapin distribution).
- replicate(): Returns a copy of the current turtle. The copy is already added to the window and can begin drawing immediately.
Window class
- add(object): Adds a grid, axis, or turtle to the window.
- setVisible(true|false): Sets the visibility of the window. By default, the window is not visible. If the window is visible while the turtle is drawing, the drawing proceeds more slowly. (This can be useful for debugging.)

[edit] User Interface

Terrapin has a minimalistic user interface. All that is shown are the turtle and what is being drawn. However, the drawing may be explored from any angle and 3D position, and the zoom level can be changed. Mouse-dragging without any modifier keys (e.g. Shift, Control) will pan the view so that more of the drawing can be seen if it extends off the edge of the display area. Shift-dragging will rotate the viewpoint in 3D space about the center of the bounding box of the drawing. Control-dragging will move the viewpoint in 3D space, and control-shift-dragging vertically will change the zoom level.

All of the fields in the TurtleDrawingWindow class are defined as protected, so the user interface may be extended by subclassing TurtleDrawingWindow. In the future, there will be a way to include a turtle drawing surface as an AWT component in other applications.

[edit] Known Bugs

If the window is visible while the turtle is drawing, there is sometimes distortion of newly drawn line segments. This is because the center of rotation is being recomputed as the new line segments redefine the extremities of the drawing, resulting in a perspective shift with each new line segment.
If the window is visible and the turtle is still running, closing the window does not terminate the program until the turtle is finished. If the program is being run from the terminal, the user must press Control-C to interrupt execution.