3. turtleplot module

The turtleplot module contains the TurtlePlot class that is responsible for converting turtle graphics primitives into robot movements. It is based on the python turtle.py module and tries to be faithful to the original module so turtle programs are largely compatible within the limits of the robot’s capability and accuracy.

The TurtlePlot class can be used control new robots by creating a new subclass and overriding the four interface functions __init__, _turn, _move and _pen. These functions are responsible for controlling the actual movement of a robot. The new class will inherit all the turtle graphics primitives.

3.1. Interface Methods

These are the four interface methods that need to be implemented to control a TurtlePlot based robot. They are not called directly by user programs.

3.1.1. __init__

This function is called to initialize and configure the robot.

3.1.2. _turn(angle)

This function tells the robot to turn left the number of degrees passed in angle. Negative numbers indicate that the robot should turn to the right.

3.1.3. _move(distance)

This function tells the robot to move forward the distance passed to it. The distance can be any unit of measure you wish but is commonly millimeters. Negative values indicate the robot should move backwards.

3.1.4. _pen(down)

This function tells the draw bot to lower or raise the drawing pen. True values indicate the pen should be lowered and False values indicate the pen should be raised.

3.2. Class Methods Reference

These are the user callable methods that do the bulk of the work running a TurtlePlotBot and keeping track of it’s location. They very closely follow the original turtle.py python module. One notable difference is that in the original turtle module the direction the turtle is facing is not changed when issuing a cartesian goto command. Since this robot can only move forward or backward in the direction it is facing, it will turn to face the direction of it’s destination. If this causes issues with your Turtle program you can save the direction the robot is facing before the goto command and turn back to it after the move. I had initially made this automatic but it resulted in too many unnecessary turns.

Attribution

The turtleplot module and documentation is based on the turtle.py: a Tkinter based turtle graphics module for Python Version 1.1b - 4. 5. 2009 by Gregor Lingl

# turtle.py: a Tkinter based turtle graphics module for Python
# Version 1.1b - 4. 5. 2009
#
# Copyright (C) 2006 - 2010  Gregor Lingl
# email: glingl@aon.at
#
# This software is provided 'as-is', without any express or implied
# warranty.  In no event will the authors be held liable for any damages
# arising from the use of this software.
#
# Permission is granted to anyone to use this software for any purpose,
# including commercial applications, and to alter it and redistribute it
# freely, subject to the following restrictions:
#
# 1. The origin of this software must not be misrepresented; you must not
#    claim that you wrote the original software. If you use this software
#    in a product, an acknowledgment in the product documentation would be
#    appreciated but is not required.
# 2. Altered source versions must be plainly marked as such, and must not be
#    misrepresented as being the original software.
# 3. This notice may not be removed or altered from any source distribution.
#
class turtleplot.TurtlePlot(mode='standard')

TurtlePlot Class

back(distance)

Move the turtle backward by distance.

Aliases:

back | backward | bk

Args:

distance (int, float): Move the turtle backward by distance, opposite to the direction the turtle is headed. Does not change the turtle’s heading.

Note

Negative distances move the turtle forward without turning

Example (for a Turtle instance named turtle):

>>> turtle.position()
(0.00, 0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00, 0.00)
circle(radius, extent=None, steps=None)

Draw a circle with given radius.

Parameters
  • radius (int, float) – radius of circle in turtle units

  • extent (optional[int, float]) – arc length

  • steps (optional[int]) – number of steps

Draw a circle with given radius. The center is radius units left of the turtle; extent - an angle - determines which part of the circle is drawn. If extent is not given, draw the entire circle. If extent is not a full circle, one endpoint of the arc is the current pen position. Draw the arc in counterclockwise direction if radius is positive, otherwise in clockwise direction. Finally the direction of the turtle is changed by the amount of extent.

As the circle is approximated by an inscribed regular polygon, steps determines the number of steps to use. If not given, it will be calculated automatically. Maybe used to draw regular polygons.

Parameters

Result

circle(radius)

full circle

circle(radius, extent)

arc

circle(radius, extent, steps)

partial polygon

circle(radius, steps=6)

6-sided polygon

Example (for a Turtle instance named turtle):

>>> turtle.circle(50)
>>> turtle.circle(120, 180)  # semicircle
degrees(fullcircle=360.0)

Set angle measurement units to degrees.

Parameters
  • fullcircle (Optional[int, float]) – Set angle measurement units,

  • set number of 'degrees' for a full circle. Default value (i.e.) –

  • 360 degrees. (is) –

Example (for a Turtle instance named turtle):

>>> turtle.left(90)
>>> turtle.heading()
90

Change angle measurement unit to grad (also known as gon, grade, or gradian and equals 1/100-th of the right angle.):

>>> turtle.degrees(400.0)
>>> turtle.heading()
100
distance(target_x, target_y=None)

Return the distance from the turtle to (x,y) in turtle step units.

Parameters
  • target_x (int, float, tuple) – x value or vector

  • target_y (int, float, None) – y value coordinate

Calling method

Parameters

distance(x, y)

two coordinates

distance((x, y))

a pair (tuple) of coordinates

distance(vec)

Vec2D as returned by pos()

Example (for a Turtle instance named turtle):

>>> turtle.pos()
(0.00, 0.00)
>>> turtle.distance(30,40)
50.0
forward(distance)

Move the turtle forward by the specified distance.

Aliases:

forward | fd

Parameters
  • distance (int, float) – Move the turtle forward by the specified

  • in the direction the turtle is headed. (distance,) –

Note

Negative distances move the turtle backwards without turning

Example (for a Turtle instance named turtle):

>>> turtle.position()
(0.00, 0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)
goto(new_x, new_y=None)

Move turtle to an absolute position.

Aliases:

setpos | setposition | goto

Parameters
  • new_x – x value or vector

  • new_y – y value coordinate

Move turtle to an absolute position. If the pen is down, a line will be drawn. The turtle’s orientation does not change.

Calling method

Parameters

goto(x, y)

two coordinates

goto((x, y))

a pair (tuple) of coordinates

goto(vec)

Vec2D as returned by pos()

Example (for a Turtle instance named turtle):

>>> tp = turtle.pos()
>>> tp
(0.00, 0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)
heading()

Return the turtle’s current heading.

Parameters

None

Example (for a Turtle instance named turtle):

>>> turtle.left(67)
>>> turtle.heading()
67.0
home()

Move turtle to the origin - coordinates (0,0).

Parameters

None

Move turtle to the origin - coordinates (0,0) and set its heading to its start-orientation (which depends on mode).

Example (for a Turtle instance named turtle):

>>> turtle.home()
>>> turtle.position()
(0.00, 0.00)
>>> turtle.heading()
0.0
isdown()

Return True if pen is down, False if it’s up.

No argument.

Returns

True if the pen is down, false if the pen is up

Return type

bool

Example (for a Turtle instance named turtle):

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True
left(angle)

Turn turtle left by angle units.

Aliases:

left | lt

Parameters

angle (int, float) – Turn turtle left by angle units.

Units are by default degrees, but can be set via the degrees() and radians() functions. Angle orientation depends on mode.

Example (for a Turtle instance named turtle):

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
mode(mode=None)

Set turtle-mode (‘standard’ or ‘logo’) and perform reset.

Parameters

mode (str) – ‘standard’ or ‘logo’. Mode ‘standard’ is compatible with turtle.py. Mode ‘logo’ is compatible with most Logo-Turtle-Graphics.

Returns

If mode is not given, return the current mode.

Mode

Initial turtle heading

Positive angles

‘standard’

to the right (east)

counterclockwise

‘logo’

upward (north)

clockwise

Examples:

>>> mode('logo')   # resets turtle heading to north
>>> mode()
'logo'
pendown()

Pull the pen down – drawing when moving.

Aliases:

pendown | pd | down

No argument.

Example (for a Turtle instance named turtle):

>>> turtle.pendown()
penup()

Pull the pen up – no drawing when moving.

Aliases:

penup | pu | up

No argument

Example (for a Turtle instance named turtle):

>>> turtle.penup()
pos()

Return the turtle’s current location (x,y), as a Vec2D-vector.

Aliases:

pos | position

Parameters

None

Returns

Tuple (x, y) containing the current location

Example (for a Turtle instance named turtle):

>>> turtle.pos()
(0.00, 240.00)
radians()

Set the angle measurement units to radians.

Parameters

None

Example (for a Turtle instance named turtle):

>>> turtle.heading()
90
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966
reset()

Reset turtle’s scale, position and orientation to its initial values

right(angle)

Turn turtle right by angle units.

Aliases:

right | rt

Parameters

angle (int, float) – Turn turtle right by angle units.

Units are by default degrees, but can be set via the degrees() and radians() functions. Angle orientation depends on mode.

Example (for a Turtle instance named turtle):

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
setheading(to_angle)

Set the orientation of the turtle to to_angle.

Aliases:

setheading | seth

Parameters

to_angle (float, integer) – Set the orientation of the turtle to to_angle.

Here are some common directions in degrees:

standard mode

logo mode

0 - east

0 - north

90 - north

90 - east

180 - west

180 - south

270 - south

270 - west

Example (for a Turtle instance named turtle):

>>> turtle.setheading(90)
>>> turtle.heading()
90
setscale(scale=None)

Sets the scaling factor

Parameters

scale (int, float) – sets scale, if None returns current scale

Returns

current scale

Return type

float

Example (for a Turtle instance named turtle):

>>> turtle.scale()
1.0
>>> turtle.scale(1.5)
1.5
setx(new_x)

Set the turtle’s first coordinate to x

Parameters

new_x (int, float) – new x coordinate

Set the turtle’s first coordinate to x, leaving the y coordinate unchanged.

Example (for a Turtle instance named turtle):

>>> turtle.position()
(0.00, 240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00, 240.00)
sety(new_y)

Set the turtle’s second coordinate to y

Parameters

new_y (int, float) – new y coordinate

Set the turtle’s y coordinate leaving the x coordinate unchanged.

Example (for a Turtle instance named turtle):

>>> turtle.position()
(0.00, 40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00, -10.00)
towards(target_x, target_y=None)

Return the angle of the line from the turtle’s position to (x, y).

Parameters
  • target_x (int, float, tuple) – x value or vector

  • target_y (int, float, None) – y value coordinate

Calling method

Parameters

distance(x, y)

two coordinates

distance((x, y))

a pair (tuple) of coordinates

distance(vec)

Vec2D as returned by pos()

Return the angle, between the line from turtle-position to position specified by x, y and the turtle’s start orientation. (Depends on modes - “standard” or “logo”)

Example (for a Turtle instance named turtle)::
>>> turtle.pos()
(10.00, 10.00)
>>> turtle.towards(0,0)
225.0
write(message, font_file='/fonts/romans.fnt')

Draws a message starting at the current location.

Parameters
  • message (str) – The message to write

  • font_file (str) – The Hershy font file to use. Defaults to rowmans.fnt if not specified.

Provided font_files:

astrol.fnt

greekp.fnt

marker.fnt

romanp.fnt

cyrilc.fnt

greeks.fnt

meteo.fnt

romans.fnt

gotheng.fnt

italicc.fnt

misc.fnt

romant.fnt

gothger.fnt

italiccs.fnt

music.fnt

scriptc.fnt

gothita.fnt

italict.fnt

romanc.fnt

scripts.fnt

greekc.fnt

japan.fnt

romancs.fnt

symbol.fnt

greekcs.fnt

lowmat.fnt

romand.fnt

uppmat.fnt

Example (for a Turtle instance named turtle):

>>> turtle.write('Howdy!', '/fonts/cursive.fnt')

Note

If a scale factor is set using scale(), the size of the message glyphs are multiplied by the current scale setting.

The default scale setting is is 1.0, a scale of ‘2’ would double the size of the glyphs.

xcor()

Return the turtle’s x coordinate.

Parameters

None

Returns

float containing the current x coordinate.

Example (for a Turtle instance named turtle):

>>> reset()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print turtle.xcor()
50.0
ycor()

Return the turtle’s y coordinate — No arguments.

Returns

float containting the current y coordinate.

Example (for a Turtle instance named turtle):

>>> reset()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print turtle.ycor()
86.6025403784
class turtleplot.Vec2D(x, y)

A 2 dimensional vector class, used as a helper class for implementing turtle graphics. May be useful for turtle graphics programs also. Derived from tuple, so a vector is a tuple!

Provides (for a, b vectors, k number)
  • a+b vector addition

  • a-b vector subtraction

  • a*b inner product

  • k*a and a*k multiplication with scalar

  • |a| absolute value of a

  • a.rotate(angle) rotation

rotate(angle)

rotate self counterclockwise by angle

Parameters

angle (int, float) – number of angle units to rotate counterclockwise