5. turtleplot module reference¶

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.

5.1. Interface functions¶

5.1.1. init¶

This function is called to initialize and configure the robot.

5.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.

5.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.

5.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.

5.2. Class Methods Reference¶

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.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

class turtleplot.TurtlePlot(mode='standard')¶

TurtlePlot Class

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'

reset()¶: Reset turtle’s scale, position and orientation to its initial values

degrees(fullcircle=360.0)¶

Set angle measurement units to degrees.

Parameters: fullcircle (Optional[int, float]) – Set angle measurement units, i. e. set number of ‘degrees’ for a full circle. Default value is 360 degrees.

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

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

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

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)

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)

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

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

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)

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

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)

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

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)

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

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

heading()¶

Return the turtle’s current heading.

Parameters: None –

Example (for a Turtle instance named turtle):

>>> turtle.left(67)
>>> turtle.heading()
67.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

circle(radius, extent=None, steps=None)¶

Draw a circle with given radius.

Parameters: radius – radius of circle in turtle units

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

penup()¶

Pull the pen up – no drawing when moving.

Aliases:: penup | pu | up

No argument

Example (for a Turtle instance named turtle):

>>> turtle.penup()

pendown()¶

Pull the pen down – drawing when moving.

Aliases:: pendown | pd | down

No argument.

Example (for a Turtle instance named turtle):

>>> turtle.pendown()

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

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:

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.

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

5. turtleplot module reference¶

5.1. Interface functions¶

5.1.1. __init__¶

5.1.2. _turn(angle)¶

5.1.3. _move(distance)¶

5.1.4. _pen(down)¶

5.2. Class Methods Reference¶

5.1.1. init¶