net.paulhertz.aifile
Class Turtle

java.lang.Object
  extended by net.paulhertz.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()
          Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down).
Turtle(double x, double y)
          Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down).
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(double x,
              double y)
Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down). Obtains a reference to the host PApplet from the initialized library class IgnoCodeLib.

Parameters:
x - x-coordinate
y - y-coordinate

Turtle

public Turtle()
Instantiates a Turtle facing right in the center of Processing's display, ready to draw (pen down). Obtains a reference to the host PApplet from the initialized library class IgnoCodeLib.


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);
x - x-coordinate
y - y-coordinate
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()


Processing library IgnoCodeLib by Paul Hertz. (C) 2013