Java Graphics Turtle com.lrdev.turtle

// Samples // Sources [javaturtle.zip] // back //

What is it

The Graphics Turtle is a cursor that has a position (X and Y coordinates), a heading and a pen up/down state. Procedures such as forward, left, etc are used as drawing idioms.

Turtle Graphics are typically known from the Logo programming language. All Logo Turtle primitives are implemented, including their abbreviated versions. Turtle Graphics have proven to be intuitively useable, well suited to start (graphics-) programming. Lots of shapes can be easily drawn using Turtle Graphics.

Linewidth, linejoin, linecap, etc are implicit part of the used graphics context (java.awt.Graphics, etc). These properties can be changed while using the Turtle.

Ideas implemented

--Motivation lies in the cool stuff.

Full Logo Turtle primitives: The full set of Logo Turtle primitives has been implemented (see below).
String representations: The Turtle can be used via the StringTurtle API.
Applet interface: An applet StringTurtleApplet is provided, to program the Turtle from HTML documents.
Control structures supported: Control structures such as repeat are supported too. This allows Turtle commands such as repeat 5 [forward 40 left 72] (as an easy representation of a pentagon).
Java-like aliases to the Turtle functions: Function aliases using the Java naming conventions are implemented.
Different heading modes: Different heading modes (i.e. units of measurement) are provided: RADIANS, DEGREE, GRAD.
Stackable Turtle calls: Most Turtle methods return the Turtle object itself, so Turtle calls can be stacked, e.g.: forward(10).left(90);.
Fat API: The com.lrdev.turtle.Turtle public API is rather fat (87 methods). However many of the methods are abbreviations and other kind of aliases to the core Turtle primitives, that consist of 18 methods.
High precision floating point representations: com.lrdev.turtle.Turtle uses high precision floating point representations (double type) to minimize calculation errors.
Ratios of doubles: Ratios (of doubles), e.g. 360/7, ease the representation of high precision data.
Scaling and transforming: Scaling and transforming are supported, to e.g. separate shape centering from the actual shape drawing.
Graphic-less operation mode: A graphic-less operation mode is supported to allow e.g. pre-calculations of shape extents.
Access to the Graphics object: Access to the Graphics object is provided to be able to change Graphics properties.
Argument-less method versions: Additional argument-less method versions enable polymorphic command use.
Command hierarchies supported: Lists ([...]) support hierarchical data structures, which are e.g. used with control statements.
Automatic centering: Automatic centering and scaling are supported, to have the drawing conveniently positioned all the time.
Indirection layer: An indirection layer is implemented to control the public API's polymorphic behavior.
Undoable commands: The PersistentTurtle class implements Turtle command-undoing.
Clipping: Clipping regions are implemented, in a somewhat optimized manner (few floating point multiplications / divisions vs. additions / subtractions / comparisions), using classifications by spatial sections. Comments provide hints on possible further optimizations.
Wrapping: The Logo language's wrapping mode is implemented, technically similar to clipping.

Usage

Instantiate a com.lrdev.turtle.Turtle with a Graphics object and component bounds.
Paint using the Turtle primitives (forward, back, left, right, ...):

    import com.lrdev.turtle.Turtle;
    ...
    public void paint(Graphics graphics)
    {
        Turtle turtle = new Turtle(graphics, bounds());
        turtle.forward(20).left(90);
        ...
    }

Or instantiate a com.lrdev.turtle.PersistentTurtle and paint after drawing. This enables e.g. centered paintings:

    import com.lrdev.turtle.PersistentTurtle;
    ...
    public void paint(Graphics graphics)
    {
        PersistentTurtle turtle = new PersistentTurtle();
        turtle.forward(20).left(90);
        ...
        turtle.center();
        turtle.paint(graphics, bounds());
    }

See also the Java Turtle samples to the com.lrdev.turtle Java Turtle code, also for samples of StringTurtleApplet usage. And see also the sources' 'samples/' section.

Logo Turtle Primitives

penup()

Set penstate in up position. Moving the Turtle will not draw, just change position.

pendown()

Set penstate in down position. Moving the Turtle will draw and change position.

forward(double distance)

Advance in current direction. The penup/pendown state determines whether the Turtle draws or not.

back(double distance)

Back up in current direction.

left(double omega)

Change heading (direction) to the left (counterclockwise, positive direction).

right(double omega)

Change heading (direction) to the right (clockwise, negative direction).

setxy(double x, double y)

Move to a specified point.

setx(double x)

Move to a specified point (only X coordinate changes).

sety(double y)

Move to a specified point (only Y coordinate changes).

setheading(double phi)

Set the heading (direction). Zero is to the right (X axis).

towards(double x, double y)

Set heading towards a point.

home()

Go home ({0, 0}); heading to zero.

wrap()

Set wrapping mode.

nowrap()

Unset wrapping mode.

double xcor()

Get X coordinate.

double ycor()

Get Y coordinate.

double heading()

Get heading.

boolean drawstate()

Get pen state.

Abbreviated versions:

pu()

Abbreviation for penup.

pd()

Abbreviation for pendown.

fd(double distance)

Abbreviation for forward.

bk(double distance)

Abbreviation for back.

lt(double omega)

Abbreviation for left.

rt(double omega)

Abbreviation for right.

seth(double phi)

Abbreviation for setheading.

Copyright Notice and Disclaimer

Copyright (C) 1997-2003 Eric Laroche.  All rights reserved.

This program is free software;
you can redistribute it and/or modify it.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Sources

javaturtle.zip: current sources, with samples, including Java byte code
javaturtle-20030107.zip javaturtle-20021227.zip: older versions

Changes

2003/02/16: Clipping and wrapping.
center() does now scale at least at one coordinate (was at two).
PersistentTurtle: scale and transform are only (re-)set if center() is chosen.
2003/01/07: Core Turtle API is not indirectly called anymore, to allow proper interaction with derived classes such as PersistentTurtle.
Generalized center() method has been implemented (PersistentTurtle).
PersistentTurtle is provided and can be used instead of Turtle.
StringTurtleApplet now provides a center parameter.

Restrictions

PersistentTurtle.undo(): The extents are not updated after undo().

F.A.Q. (Frequently Asked Questions) List

Is an explicit support for Graphics2D objects needed?

No, it seems not necessary, since com.lrdev.turtle.Turtle only uses the drawLine() method of java.awt.Graphics. Other Graphics or Graphics2D calls are to be made by the client application. Also backward compatibility to older Java versions and older web browsers are provided this way.

Is Swing an issue?

No. The Turtle core classes are graphic renderers, not user interface components.

Will there be other Logo programming language non-Turtle constructs (besides repeat)?

Probably no, since the Java programming language has the clearer syntax.

How can I use rotate, shear and flip transformations (as well as generalized matrix transformations)?

Use the underlying graphics' (e.g. Graphics2D) modes. Only scale, translate, clip and wrap modes are directly supported by com.lrdev.turtle.

Can you provide support for the com.lrdev.turtle package?

No, unfortunately not, with this opensource project. However, answers to some of your problems may appear in this f.a.q. list.

Will bugfixes be included in the product?

Yes. Please send them to Eric Laroche <laroche@lrdev.com>.

Is there a mailing list for the com.lrdev.turtle Turtle package?

No, not at the moment. If you want to get notified on changes, drop a mail to laroche@lrdev.com.

Links

Author's Java page / Author's site / PostScript Turtle / Samples / Sources

PersistentTurtle.java / StringTurtle.java / StringTurtleApplet.java / Turtle.java / TurtleCore.java

InteractiveTurtleApplet.java / InteractiveTurtleApplet2.java / PolygonApplet.java // Callback.java / DirectiveParser.java

http://www.lrdev.com/lr/java/javaturtle.html
Eric Laroche, laroche@lrdev.com / Sat Dec 28 2002 .. Sun Feb 16 2003