com.ignotus.aifile
Class Turtle

java.lang.Object
  com.ignotus.aifile.Turtle

All Implemented Interfaces:

ColorableINF

public class Turtle
extends Object
implements ColorableINF

Implements a basic 2D TurtleGraphics command set that can be used to draw shapes in Processing and export them to Adobe Illustrator.

A turtle is an imaginary denizen of computer graphics that had its origins in the LOGO language, which was a subset of LISP used for teaching programming. LOGO was designed for children, but was a powerful language. Its model of a "local geometry" implemented through the orientation and location of the turtle offered many intuitive advantages over the "global geometry" used in most computer graphics packages.

A turtle is created facing right (east) at the center of the screen or at user-supplied coordinates. It moves across the display upon receiving forward(double), backward(double), move(double) or moveTo(double, double) commands, and changes its orientation in response to left(double), right(double) and turn(double) commands. It carries with it a "pen" that may be up or down. When the pen is down, the turtle leaves a mark that can be displayed by calling the turtle's draw() command from Processing's draw() method. A shape (also referred to here as a "trail" or a "turtle trail") is created by moving the turtle while the turtle pen is down (penDown() command). A shape is finished by a penUp() command. Each shape is stored into an array, the turtleTrails array, which is also drawn by the draw() method. Shapes in the turtleTrails array and the current trail can be deleted with the clear() command.

The graphics state of trails/shapes is controlled through the commands in the ColorableINF interface, which allow you to get and set fill color, stroke color, and stroke weight. The setNoFill() and setNoStroke() commands turn off filling and stroking of shapes. Commands apply to the current trail or to new trails, but not to previously stored trails.

The location, orientation, pen state and visibility of the turtle are stored in a TurtleState object. The turtle x-coordinate, turtle y-coordinate, orientation, pen state and visibility can be set directly, by "divine intervention," bypassing the move, moveTo and turn commands. Turtle states can be pushed onto the turtleStack (push(TurtleState), examined via peek() and retrieved and deleted with pop(). The clearStack() command clears the stored states.

Shapes can be written to an Adobe Illustrator 7.0 file with the write(PrintWriter) command; however, a preferred and simpler techniques is to call getTrails(), which returns a GroupComponent that can be added to a DocumentComponent or a LayerComponent. A DocumentComponent can handle the creation of an Illustrator document and export geometry to it with its DocumentComponent.write(PrintWriter) command.

See Also:

DocumentComponent, LayerComponent, ColorableINF

Field Summary

float	r turtle radius
static double	TWOPI useful constant

Constructor Summary

Turtle(PApplet parent)
Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down).

Turtle(PApplet parent, double x, double y)
Instantiates a Turtle facing right at coordinates (x, y), ready to draw (pen down).

Method Summary

void	backward(double distance) Moves the turtle in the direction opposite to the current direction (i.e., -turtle angle) by a specified distance.
void	clear() Clears all trails, both those saved in turtleTrails and the current trail.
void	clearStack() Clears the turtleStack of all stored states.
void	draw() Draws all trails, both those saved in turtleTrails and the current trail, to the display.
void	draw(PGraphics pg) Draws all trails, both those saved in turtleTrails and the current trail, to an instonce of PGraphics used as an offscreen buffer.
void	drawCurrent() Draws the current trail only to the display.
int	fillColor() Returns the fill color of the current trail.
int	fillOpacity() Returns opacity component of current fill color, in the range 0..255.
void	forward(double distance) Moves the turtle in the current direction (turtle angle) by a specified distance.
BezShape	get(int index) Gets trail (BezShape) at suppled index.
BezShape	getCurrentTrail()
int	getMaxTrails()
int	getTrailIndex()
GroupComponent	getTrails() Returns a GroupComponent with all the trails created by this Turtle instance.
double	getTurtleAngle() Returns the current turtle angle.
ArrayList<TurtleState>	getTurtleStack() Returns the turtle stack, an array of turtle states.
ArrayList<BezShape>	getTurtleTrails() Returns the list of all stored turtle trails, not including the current trail if it is still being draw (i.e., no penUp() command has been issued to store it).
PVector	getTurtleVector() Returns current turtle angle as a normalized PVector
double	getTurtleX() Returns x-coordinate of turtle location.
double	getTurtleY() Returns y-coordinate of turtle location.
boolean	hasFill() Returns true if current trail is filled, false otherwise.
boolean	hasStroke() Returns true if the current trail is stroked.
void	hide() Gets ready to hide the visible representation of the turtle on the next draw command.
void	home() returns the turtle to its original position with a turtle angle of 0 (facing right).
boolean	isClosed() Returns current value of isClosed, true if current trail is a closed shape.
boolean	isEmpty() Returns true if there are no shapes stored in turtleTrails array.
boolean	isFull() Returns true if maximum number of trails have been stored in turtleTrails array.false otherwise.
boolean	isPenDown() Returns true if the pen is down (ready to draw), false otherwise.
boolean	isTurtleVisible() Returns true if turtle is visible, false otherwise.
Iterator<BezShape>	iterator() Returns an iterator over the stored turtle trails.
void	left(double angle) Turns the turtle to the left (counterclockwise) a specified number of radians from its current direction (turtle angle).
void	move(double distance) Moves the turtle by a specified distance in the current direction (turtle angle).
void	moveTo(double x2, double y2) Moves the turtle to a specified point (x2, y2).
TurtleState	peek() Retrieves, but does not remove, the most recently pushed turtle state, or returns null if turtleStack is empty.
void	penDown() Prepares the turtle to create a trail on the next forward, backward, or move command.
void	penUp() Stops drawing by the turtle and adds the current trail (if there is one) to the turtleTrails array.
TurtleState	pop() Retrieves and removes the most recently pushed turtle state.
void	push(TurtleState state) Pushes a turtle state onto the stack.
void	right(double angle) Turns the turtle to the right (clockwise) a specified number of radians from its current direction (turtle angle).
void	setFillColor(int newFillColor) Sets fill color of this Turtle instance.
void	setFillOpacity(int opacity) Sets fill color opacity of this Turtle instance.
void	setIsClosed(boolean newIsClosed) Sets isClosed of this Turtle instance to supplied value.
void	setMaxTrails(int maxTrails)
void	setNoFill() Sets hasFill of this Turtle instance to false.
void	setNoStroke() Sets hasStroke of this Turtle instance to false.
void	setStrokeColor(int newStrokeColor) Sets stroke color of this Turtle instance.
void	setStrokeOpacity(int opacity) Sets opacity value of stroke color of this Turtle instance.
void	setTurtleAngle(double turtleAngle) Sets the orientation of the turtle by divine intervention.
void	setTurtleAngle(PVector vec) Sets the orientation of the turtle from a supplied PVector.
void	setTurtleX(double turtleX) Sets the x-coordinate of the turtle by divine intervention.
void	setTurtleY(double turtleY) Sets the y-coordinate of the turtle by divine intervention.
void	setWeight(float newWeight) Sets value of stroke weight of this Turtle instance.
void	show() Gets ready to show the turtle as an oriented triangle on the next draw command.
int	size() Returns number of elements in the turtleTrails array.
int	stackSize() Returns the number of elements in the turtle state stack.
int	strokeColor() Returns current stroke color.
int	strokeOpacity() Returns opacity component of current stroke color, in the range 0..255.
int	trailSize() Returns number of vertices in the current trail.
void	turn(double angle) Turns the turtle a specified number of radians from its current direction (turtle angle).
float	weight() Returns weight of current stroke.
void	write(PrintWriter pw) Writes the geometry of all trails, both those saved in turtleTrails and the current trail, in Adobe Illustrator 7.0 format, to the file or output stream specified.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

r

public float r

turtle radius

TWOPI

public static double TWOPI

useful constant

Constructor Detail

Turtle

public Turtle(PApplet parent)

Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down).

Parameters:

parent - a PApplet, typically a reference to the host applet, as in Turtle t = new Turtle(this);

Turtle

public Turtle(PApplet parent,
              double x,
              double y)

Instantiates a Turtle facing right at coordinates (x, y), ready to draw (pen down).

Parameters:

parent - a PApplet, typically a reference to the host applet, as in Turtle t = new Turtle(this, x, y);

Method Detail

show

public void show()

Gets ready to show the turtle as an oriented triangle on the next draw command.

hide

public void hide()

Gets ready to hide the visible representation of the turtle on the next draw command.

penUp

public void penUp()

Stops drawing by the turtle and adds the current trail (if there is one) to the turtleTrails array. If the number of trails in the turtleTrails array exceeds maxTrails, indexing will wrap around and trails will be overwritten. The default value of maxTrails is 255.

penDown

public void penDown()

Prepares the turtle to create a trail on the next forward, backward, or move command. Has no effect if the pen is already down.

move

public void move(double distance)

Moves the turtle by a specified distance in the current direction (turtle angle). If the pen is down, adds a segment to the current trail or starts a new trail.

Parameters:

distance -

moveTo

public void moveTo(double x2,
                   double y2)

Moves the turtle to a specified point (x2, y2). If the pen is down, adds a segment to the current trail or starts a new trail.

Parameters:

x2 - the x-coordinate of the point to move to

y2 - the y-coordinate of the point to move to

forward

public void forward(double distance)

Moves the turtle in the current direction (turtle angle) by a specified distance.

Parameters:

distance -

backward

public void backward(double distance)

Moves the turtle in the direction opposite to the current direction (i.e., -turtle angle) by a specified distance.

Parameters:

distance -

turn

public void turn(double angle)

Turns the turtle a specified number of radians from its current direction (turtle angle).

Parameters:

angle -

left

public void left(double angle)

Turns the turtle to the left (counterclockwise) a specified number of radians from its current direction (turtle angle).

Parameters:

angle -

right

public void right(double angle)

Turns the turtle to the right (clockwise) a specified number of radians from its current direction (turtle angle).

Parameters:

angle -

home

public void home()

returns the turtle to its original position with a turtle angle of 0 (facing right).

clear

public void clear()

Clears all trails, both those saved in turtleTrails and the current trail.

draw

public void draw()

Draws all trails, both those saved in turtleTrails and the current trail, to the display. If the turtle is visible, draws the turtle icon.

draw

public void draw(PGraphics pg)

Draws all trails, both those saved in turtleTrails and the current trail, to an instonce of PGraphics used as an offscreen buffer. User is responsible for calling beginDraw() and endDraw() to enable drawing on the PGraphics instance. If the turtle is visible, draws the turtle icon.

Parameters:

pg - a PGraphics instance.

drawCurrent

public void drawCurrent()

Draws the current trail only to the display. If the turtle is visible, draws the turtle icon.

write

public void write(PrintWriter pw)

Writes the geometry of all trails, both those saved in turtleTrails and the current trail, in Adobe Illustrator 7.0 format, to the file or output stream specified. It is probably simpler just to add the GroupComponent obtained from getTrails to a Document component, as shown in the examples.

Parameters:

pw - the output stream (file) to write to.

getTrails

public GroupComponent getTrails()

Returns a GroupComponent with all the trails created by this Turtle instance. Trails are ready to add to a DocumentComponent or LayerComponent and export to Adobe Illustrator.

Returns:

a GroupComponent with all the trails created by this Turtle instance.

See Also:

LayerComponent.add(DisplayComponent), DocumentComponent.add(DisplayComponent)

getTurtleStack

public ArrayList<TurtleState> getTurtleStack()

Returns the turtle stack, an array of turtle states. Useful with L-systems.

Returns:

the turtleStack

See Also:

TurtleState

getTurtleTrails

public ArrayList<BezShape> getTurtleTrails()

Returns the list of all stored turtle trails, not including the current trail if it is still being draw (i.e., no penUp() command has been issued to store it).

Returns:

the turtleTrails

getMaxTrails

public int getMaxTrails()

Returns:

the maxTrails, maximum number of stored trails

setMaxTrails

public void setMaxTrails(int maxTrails)

Parameters:

maxTrails - the maxTrails to set

getTrailIndex

public int getTrailIndex()

Returns:

the trailIndex, index to most recently inserted element in turtleTrails

getCurrentTrail

public BezShape getCurrentTrail()

Returns:

the current trail, may be null

getTurtleAngle

public double getTurtleAngle()

Returns the current turtle angle.

Returns:

current turtle angle

See Also:

TurtleState.getTurtleAngle()

getTurtleVector

public PVector getTurtleVector()

Returns current turtle angle as a normalized PVector

Returns:

current turtle angle as a PVector

See Also:

TurtleState.turtleVector()

setTurtleAngle

public void setTurtleAngle(double turtleAngle)

Sets the orientation of the turtle by divine intervention.

Parameters:

turtleAngle - the angle the turtle is facing

See Also:

TurtleState.setTurtleAngle(double)

setTurtleAngle

public void setTurtleAngle(PVector vec)

Sets the orientation of the turtle from a supplied PVector.

Parameters:

vec - a PVector

See Also:

TurtleState.setTurtleAngle(PVector)

isPenDown

public boolean isPenDown()

Returns true if the pen is down (ready to draw), false otherwise.

Returns:

true if the pen is down, false if it is up

See Also:

TurtleState.isPenDown()

isTurtleVisible

public boolean isTurtleVisible()

Returns true if turtle is visible, false otherwise. Visibility is not yet implemented.

Returns:

true if turtle is visible, false if it is not

See Also:

TurtleState.isTurtleVisible()

getTurtleX

public double getTurtleX()

Returns x-coordinate of turtle location.

Returns:

the x-coordinate of the turtle's location

See Also:

TurtleState.getTurtleX()

setTurtleX

public void setTurtleX(double turtleX)

Sets the x-coordinate of the turtle by divine intervention. Does no drawing: Use moveTo instead to do drawing.

Parameters:

turtleX - x-coordinate to assign to the turtle's location

See Also:

TurtleState.setTurtleX(double)

getTurtleY

public double getTurtleY()

Returns y-coordinate of turtle location.

Returns:

the y-ccordinate of the turtle's location

See Also:

TurtleState.getTurtleY()

setTurtleY

public void setTurtleY(double turtleY)

Sets the y-coordinate of the turtle by divine intervention. Does no drawing: Use moveTo instead to do drawing.

Parameters:

turtleY - y-coordinate to assign to the turtle's location

See Also:

TurtleState.setTurtleY(double)

peek

public TurtleState peek()

Retrieves, but does not remove, the most recently pushed turtle state, or returns null if turtleStack is empty.

Returns:

most recently pushed turtle state

See Also:

ArrayList.get(int)

pop

public TurtleState pop()

Retrieves and removes the most recently pushed turtle state. Throws a NoSuchElementException if the turtleStack is empty.

Returns:

a TurtleState

See Also:

ArrayList.remove(int)

push

public void push(TurtleState state)

Pushes a turtle state onto the stack.

Parameters:

state - the state to push

See Also:

ArrayList.add(java.lang.Object)

stackSize

public int stackSize()

Returns the number of elements in the turtle state stack.

Returns:

number of elements in the turtle state stack

See Also:

ArrayList.size()

clearStack

public void clearStack()

Clears the turtleStack of all stored states.

isClosed

public boolean isClosed()

Returns current value of isClosed, true if current trail is a closed shape.

Returns:

current isClosed value of this Turtle instance

See Also:

BezShape.isClosed()

setIsClosed

public void setIsClosed(boolean newIsClosed)

Sets isClosed of this Turtle instance to supplied value. If a trail has been started, sets its isClosed value.

Parameters:

newIsClosed -

See Also:

BezShape.setIsClosed(boolean)

hasFill

public boolean hasFill()

Returns true if current trail is filled, false otherwise.

Specified by:

hasFill in interface ColorableINF

Returns:

current hasFill value of this Turtle instance

See Also:

BezShape.hasFill()

fillColor

public int fillColor()

Returns the fill color of the current trail.

Specified by:

fillColor in interface ColorableINF

Returns:

current fill color of this Turtle instance

See Also:

BezShape.fillColor()

setFillColor

public void setFillColor(int newFillColor)

Sets fill color of this Turtle instance. If a trail has been started, sets fill color of trail.

Specified by:

setFillColor in interface ColorableINF

Parameters:

newFillColor -

See Also:

BezShape.setFillColor(int)

setNoFill

public void setNoFill()

Sets hasFill of this Turtle instance to false. If a trail has been started, sets its hasFill to false.

Specified by:

setNoFill in interface ColorableINF

See Also:

BezShape.setNoFill()

hasStroke

public boolean hasStroke()

Returns true if the current trail is stroked.

Specified by:

hasStroke in interface ColorableINF

Returns:

current hasStroke value of this Turtle instance.

See Also:

BezShape.hasStroke()

strokeColor

public int strokeColor()

Returns current stroke color.

Specified by:

strokeColor in interface ColorableINF

Returns:

current stroke color of this Turtle instance.

See Also:

BezShape.strokeColor()

setStrokeColor

public void setStrokeColor(int newStrokeColor)

Sets stroke color of this Turtle instance. If a trail has been started, sets stroke color of trail.

Specified by:

setStrokeColor in interface ColorableINF

Parameters:

newStrokeColor -

See Also:

BezShape.setStrokeColor(int)

setNoStroke

public void setNoStroke()

Sets hasStroke of this Turtle instance to false. If a trail has been started, sets its hasStroke to false.

Specified by:

setNoStroke in interface ColorableINF

See Also:

BezShape.setNoStroke()

fillOpacity

public int fillOpacity()

Returns opacity component of current fill color, in the range 0..255.

Specified by:

fillOpacity in interface ColorableINF

Returns:

opacity component of fill color of this Turtle instance

See Also:

BezShape.fillOpacity()

setFillOpacity

public void setFillOpacity(int opacity)

Sets fill color opacity of this Turtle instance. If a trail has been started, sets fill color opacity of trail.

Specified by:

setFillOpacity in interface ColorableINF

Parameters:

opacity - opacity to set (0..255)

See Also:

BezShape.setFillOpacity(int)

strokeOpacity

public int strokeOpacity()

Returns opacity component of current stroke color, in the range 0..255.

Specified by:

strokeOpacity in interface ColorableINF

Returns:

opacity component of stroke color of this Turtle instance

See Also:

BezShape.strokeOpacity()

setStrokeOpacity

public void setStrokeOpacity(int opacity)

Sets opacity value of stroke color of this Turtle instance. If a trail has been started, sets opacity of stroke color of trail.

Specified by:

setStrokeOpacity in interface ColorableINF

Parameters:

opacity - opacity to set (0..255)

See Also:

BezShape.setStrokeOpacity(int)

weight

public float weight()

Returns weight of current stroke.

Specified by:

weight in interface ColorableINF

Returns:

value of stroke weight of this Turtle instance

setWeight

public void setWeight(float newWeight)

Sets value of stroke weight of this Turtle instance. If a trail has been started, sets stroke weight of trail.

Specified by:

setWeight in interface ColorableINF

Parameters:

newWeight -

See Also:

BezShape.setWeight(float)

trailSize

public int trailSize()

Returns number of vertices in the current trail. Returns 0 if the current trail is null.

Returns:

the number of vertices in the current trail

get

public BezShape get(int index)

Gets trail (BezShape) at suppled index. Throws an error if index is out of bounds.

Parameters:

index -

Returns:

the BezShape located at the supplied index

See Also:

ArrayList.get(int)

isEmpty

public boolean isEmpty()

Returns true if there are no shapes stored in turtleTrails array.

Returns:

true if turtleTrails array is empty, false otherwise.

See Also:

ArrayList.isEmpty()

isFull

public boolean isFull()

Returns true if maximum number of trails have been stored in turtleTrails array.false otherwise.

Returns:

true if the turtleTrails array holds maxTrails number of elements, false otherwise.

iterator

public Iterator<BezShape> iterator()

Returns an iterator over the stored turtle trails.

Returns:

and Interator that can step through the turtleTrails array.

See Also:

AbstractList.iterator()

size

public int size()

Returns number of elements in the turtleTrails array.

Returns:

size of the turtleTrails array.

See Also:

ArrayList.size()