# Using The Turtle Class#

The Turtle class is inspired by the [Logo programming language](https://en.wikipedia.org/wiki/Logo_(programming_language). It lets you draw lines and shapes by moving a pen that looks like a turtle around a canvas. This notebook will show you all of the things you can do with the pen. Before the pen can used you have to run the code in the cell below:

[ ]:

from p4e.drawing import Turtle


You only have to run the import cell once unless you restart the python kernel.

## Creating a Canvas#

The Turtle draws on a Canvas. In Python parliance you create an instance of a Turtle and give the instance a name. The code below creates an instnace named tu. In subsequent cells we tell the turtle what to do using the name tu and the changes are reflected on the canvas. The canvas won’t show unless you ask for it. The statement display(tu) says to display the canvas you created. You can also show the canvas by just putting tu on the last line of the cell by itself.

[ ]:

tu = Turtle()
display(tu)


## Drawing Lines#

The draw function of the pen draws a line. After you’re done drawing the show function shows your drawing. The cell below draws a line.

[ ]:

tu = Turtle()
display(tu)
tu.draw(20)


You can also draw in reverse.

[ ]:

tu = Turtle()
display(tu)
tu.draw(50) # Go forward 50 steps.
tu.draw(-20) # Go back 20 steps.


## Turns#

The turn function turns the turtle. The number provided to the turn function is the angle to turn in degrees. A positive angle is a left turn and a negative angle is a right turn.

[ ]:

tu = Turtle()
display(tu)
tu.draw(30)
tu.turn(45) # Turn left
tu.draw(30)
tu.turn(-45) # Turn right
tu.draw(30)


## Picking Up and Putting Down the Pen#

You can control the drawing by picking up the pen. When the pen is up moves don’t draw a line. When you want to draw lines again you can put the pen back down. The up and down functions control the pen.

[ ]:

tu = Turtle()
display(tu)
tu.draw(30)
tu.up()      # Pick up the pen
tu.draw(20)  # There will be no line from this draw.
tu.down()    # Put down the pen
tu.draw(30)


## The Color and Width of the Pen#

The You can control the color and the thickness of the lines that the pend draws using the color and width functions.

[ ]:

tu = Turtle()
display(tu)
tu.width(30)      # Draw a 30px line.
tu.color('red')   # Draw red
tu.draw(150)
tu.turn(120)
tu.color('green') # Draw green
tu.draw(150)
tu.turn(120)
tu.color('blue')  # Draw blue
tu.draw(150)
tu.turn(120)


The pen can use any colors that are valid in HTML. You can see HTML color codes on this page.

[ ]:

tu = Turtle()
display(tu)
tu.width(30)         # Draw a 30px line.
tu.color('fuchsia')  # Draw a fuchsia
tu.draw(150)
tu.turn(120)
tu.color('#ff1010')  # Use #RRGGBB notation.
tu.draw(150)
tu.turn(120)
tu.color('#00ff00')
tu.draw(150)
tu.turn(120)


## Moving the Pen to Absolute Coordinates#

The goto function moves the pen to a particular location. If the pen is down it will draw a line on the path to that location. If the pen is up no line will be drawn.

[ ]:

tu = Turtle()    # The pen starts at (0, 0) facing up.
display(tu)
tu.draw(150)     # The pen is now at (0, 50)
tu.goto(50, -50)
tu.draw(150)     # The pen is now at (20, 50)
tu.goto(100, -50)
tu.draw(150)     # The pen is now at (40, 50)


You can turn the pen to a particular direction in degrees using the heading funciton.

[ ]:

tu = Turtle()    # The pen starts at (0,0), heading 90 degrees
display(tu)
tu.draw(100)
tu.goto(0,0)
tu.draw(100)
tu.goto(0,0)
tu.draw(100)
tu.goto(0,0)
tu.draw(100)


## Writing Text#

The turtle can write text. The text position and orientation is based on the turtle.

[ ]:

tu = Turtle()
display(tu)

tu.up()
tu.write("Python")
tu.turn(30)
tu.draw(-30)
tu.write("is")
tu.turn(30)
tu.draw(-30)
tu.write("fun")
tu.hide()


## Drawing a Polygon#

The polygon function fills a shape given absolute coordinates. Unlike other drawing functions, polygon does not depend on the position or orientation of the turtle.

[ ]:

tu = Turtle()
display(tu)

tu.polygon([(0,0), (0,100), (100,100), (100,0)])


## Setting a Background Image#

You can set a custom background image for the arena. The image is automatically scaled to the size of the arena.

[ ]:

tu = Turtle(image='../Labs/files/maze.png')
display(tu)


The background image can be changed using the background function.

## Controlling the Shape of the Arena#

The show function takes arguments that control how the final plot is rendered. The default arena is square with x = [-200, 200] and y = [-200, 200]. You can control the shape of the arena by passing the size parameter when you create the Turtle. For example, to create a smaller canvas you can create it this way:

[ ]:

tu = Turtle(size=(100,100))
display(tu)
tu.draw(20)
tu.turn(-120)
tu.draw(20)
tu.turn(-120)
tu.draw(20)


## Face Recognition#

The turtle is capable of recognizing faces in the image loaded into the canvas. The find_face function returns a list with information about each of the faces that it found. Each list contains a dict with landmarks in the face.

[ ]:

tu = Turtle(image="images/forrest_gump.jpeg")
display(tu)

faces = tu.find_faces()
face = faces[0] # The first face in the list

# Draw a box around the face. The top/bottom, left_right
# landmarks show us where the face was found and contain
# a single point.
tu.width(2)
tu.color('yellow')
tu.up()
tu.goto(face['top_right'])
tu.down()
tu.goto(face['top_left'])
tu.goto(face['bottom_left'])
tu.goto(face['bottom_right'])
tu.goto(face['top_right'])

# The feature landmarks are outlines of facial features.
tu.color('red')
tu.polygon(face['bottom_lip'])
tu.polygon(face['top_lip'])


## Getting Help#

The help function in Python can show you the documentation for an object like the pen.

[ ]:

help(Turtle)