Terrapin Turtle Graphics

Infobox_Software
name = Terrapin Turtle Graphics
developer = Spencer Tipping
latest_release_version = 2.1
latest_release_date = May 17, 2008
operating_system = Linux, Unix, Microsoft Windows, Mac OS, other operating systems with JRE implementations
genre = Educational software
license = LGPL
website = [http://xenon.truman.edu/~sjt309/ http://xenon.truman.edu/~sjt309]

Terrapin Turtle Graphics is a simple turtle graphicsprogramming library for Java. It is released under the LGPL. Distinguishing characteristics include an extension intothree dimensions and the ability to create highly detailed and realisticdrawings using colors and antialiased rendering.

Architecture

Terrapin is broken into two major pieces: The "turtle", which executes drawingcommands, 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 turtlemust each be created, the turtle must be added to the window, and then drawingcommands must be issued to the turtle. This code, for example, will produce asquare:

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 segmentsthat are rendered by the window. Other objects that produce line segments, suchas 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 beproduced simultaneously:

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); }

Turtle API

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/ http://xenon.truman.edu/~sjt309] .
** pushTurtleState(), popTurtleState(): Each turtle maintains a stack of "state"s, 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.)

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.

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.

See Also

* Polar coordinate system
* Cylindrical coordinate system
* Spherical coordinate system
* Fractal
* Turtle Graphics

External Links

* [http://xenon.truman.edu/~sjt309/ Terrapin Turtle Graphics] official site