API Reference#

Main functionality#

class turtlethread.Turtle(pattern=None, scale=1, angle_mode='degrees', mode='standard')[source]#

Turtle object that to make embroidery files. Mirrored after the official turtle library.

Any undocumented functions have the same interface as the official turtle library.

One turtle-step is equivalent to 0.1 mm.

Parameters

patternpyembroidery.EmbPattern (optional)

The embroidery pattern to work with. If not supplied, then an empty pattern will be created.

scalefloat (optional, default=1)

Scaling between turtle steps and units in the embroidery file. Below are some example scaling

scale=1 - One step is one unit in the embroidery file (0.1 mm)

scale=10 - One step equals 1 mm

scale=2 - The scaling TurtleStitch uses

angle_mode“degrees” or “radians” (optional, default=”degrees”)

How angles are computed.

mode“standard”, “world” or “logo” (optional, default=”standard”)

Mode “standard” is compatible with turtle.py. Mode “logo” is compatible with most Logo-Turtle-Graphics. Mode “world” is the same as ‘standard’ for TurtleThread.

Mode Initial turtle heading positive angles

————|-------------------------|——————-

“standard” to the right (east) counterclockwise
“logo” upward (north) clockwise

Attributes

angle
angle_mode: The angle mode, either “degrees” or “radians”.

Methods

`back`(distance)	Move the turtle backward by distance.
`backward`(distance)	Move the turtle backward by distance.
`bk`(distance)	Move the turtle backward by distance.
`circle`(radius[, extent, steps])	Draw a circle, see the official documentation.
`cleanup_stitch_type`()	Cleanup after switching to running stitch.
`degrees`([fullcircle])	Set angle measurement units to degrees.
`distance`(x[, y])	Return the distance from the turtle to (x,y) in turtle step units.
`fd`(distance)	Move the turtle forward by the specified distance.
`forward`(distance)	Move the turtle forward by the specified distance.
`goto`(x[, y])	Move turtle to an absolute position.
`heading`()	Return the turtle's current heading.
`home`()	Move the needle home (position (0, 0)), see the official documentation.
`jump_stitch`()	Set the stitch mode to jump-stitch and cleanup afterwards.
`left`(angle)	Turn turtle left by angle units.
`lt`(angle)	Turn turtle left by angle units.
`pos`()	Return the turtle's current location (x,y), as a Vec2D-vector.
`position`()	Return the turtle's current location (x,y), as a Vec2D-vector.
`radians`()	Set the angle measurement units to radians.
`reset`()	reset turtle to its initial values
`right`(angle)	Turn turtle right by angle units.
`rt`(angle)	Turn turtle right by angle units.
`running_stitch`(stitch_length)	Set the stitch mode to running stitch and cleanup afterwards.
`save`(filename)	Save the embroidery pattern as an embroidery or image file.
`seth`(to_angle)	Set the orientation of the turtle to to_angle.
`setheading`(to_angle)	Set the orientation of the turtle to to_angle.
`setpos`(x[, y])	Move turtle to an absolute position.
`setposition`(x[, y])	Move turtle to an absolute position.
`setx`(x)	Set the turtle's first coordinate to x
`sety`(y)	Set the turtle's second coordinate to y
`show_info`()	Display information about this turtle's embroidery pattern.
`speed`([s])	dummy method - to be overwritten by child class
`start_jump_stitch`()	Set the stitch mode to jump-stitch (not recommended, use `jump_stitch`-context instead).
`start_running_stitch`(stitch_length)	Set the stitch mode to running stitch (not recommended, use `running_stitch`-context instead).
`towards`(x[, y])	Return the angle of the line from the turtle's position to (x, y).
`visualise`([turtle, width, height, scale, ...])	Use the builtin `turtle` library to visualise this turtle's embroidery pattern.
`xcor`()	Return the turtle's x coordinate.
`ycor`()	Return the turtle's y coordinate

property angle_mode#: The angle mode, either “degrees” or “radians”.

back(distance)#

Move the turtle backward by distance.

Aliases: back | backward | bk

Argument: distance – a number

Move the turtle backward by distance, opposite to the direction the turtle is headed. Do not change the turtle’s heading.

Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 0.00) >>> turtle.backward(30) >>> turtle.position() (-30.00, 0.00)

backward(distance)#

Move the turtle backward by distance.

Aliases: back | backward | bk

Argument: distance – a number

Move the turtle backward by distance, opposite to the direction the turtle is headed. Do not change the turtle’s heading.

Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 0.00) >>> turtle.backward(30) >>> turtle.position() (-30.00, 0.00)

bk(distance)#

Move the turtle backward by distance.

Aliases: back | backward | bk

Argument: distance – a number

Move the turtle backward by distance, opposite to the direction the turtle is headed. Do not change the turtle’s heading.

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)[source]#: Draw a circle, see the official documentation.

cleanup_stitch_type()[source]#: Cleanup after switching to running stitch.

degrees(fullcircle=360.0)#

Set angle measurement units to degrees.

Optional argument: fullcircle - a number

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

distance(x, y=None)#

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

Arguments: x – a number or a pair/vector of numbers or a turtle instance y – a number None None

call: distance(x, y) # two coordinates –or: distance((x, y)) # a pair (tuple) of coordinates –or: distance(vec) # e.g. as returned by pos() –or: distance(mypen) # where mypen is another turtle

Example (for a Turtle instance named turtle): >>> turtle.pos() (0.00, 0.00) >>> turtle.distance(30,40) 50.0 >>> pen = Turtle() >>> pen.forward(77) >>> turtle.distance(pen) 77.0

fd(distance)#

Move the turtle forward by the specified distance.

Aliases: forward | fd

Argument: distance – a number (integer or float)

Move the turtle forward by the specified distance, in the direction the turtle is headed.

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)

forward(distance)#

Move the turtle forward by the specified distance.

Aliases: forward | fd

Argument: distance – a number (integer or float)

Move the turtle forward by the specified distance, in the direction the turtle is headed.

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(x, y=None)#

Move turtle to an absolute position.

Aliases: setpos | setposition | goto:

Arguments: x – a number or a pair/vector of numbers y – a number None

call: goto(x, y) # two coordinates –or: goto((x, y)) # a pair (tuple) of coordinates –or: goto(vec) # e.g. as returned by pos()

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

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.

No arguments.

Example (for a Turtle instance named turtle): >>> turtle.left(67) >>> turtle.heading() 67.0

home()[source]#: Move the needle home (position (0, 0)), see the official documentation.

jump_stitch()[source]#

Set the stitch mode to jump-stitch and cleanup afterwards.

With a jump-stitch, trim the thread and move the needle without sewing more stitches.

left(angle)#

Turn turtle left by angle units.

Aliases: left | lt

Argument: angle – a number (integer or 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. (See this.)

Example (for a Turtle instance named turtle): >>> turtle.heading() 22.0 >>> turtle.left(45) >>> turtle.heading() 67.0

lt(angle)#

Turn turtle left by angle units.

Aliases: left | lt

Argument: angle – a number (integer or 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. (See this.)

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

No arguments.

Example (for a Turtle instance named turtle): >>> turtle.pos() (0.00, 240.00)

position()#

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

Aliases: pos | position

No arguments.

Example (for a Turtle instance named turtle): >>> turtle.pos() (0.00, 240.00)

radians()#

Set the angle measurement units to radians.

No arguments.

Example (for a Turtle instance named turtle): >>> turtle.heading() 90 >>> turtle.radians() >>> turtle.heading() 1.5707963267948966

reset()#

reset turtle to its initial values

Will be overwritten by parent class

right(angle)#

Turn turtle right by angle units.

Aliases: right | rt

Argument: angle – a number (integer or 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. (See this.)

Example (for a Turtle instance named turtle): >>> turtle.heading() 22.0 >>> turtle.right(45) >>> turtle.heading() 337.0

rt(angle)#

Turn turtle right by angle units.

Aliases: right | rt

Argument: angle – a number (integer or 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. (See this.)

Example (for a Turtle instance named turtle): >>> turtle.heading() 22.0 >>> turtle.right(45) >>> turtle.heading() 337.0

running_stitch(stitch_length)[source]#

Set the stitch mode to running stitch and cleanup afterwards.

With a running stitch, we get stitches with a constant distance between each stitch.

One step is equivalent to 0.1 mm, we recommend setting the minimum length between each stitch to 30 (3 mm).

Parameters

stitch_lengthint: Number of steps between each stitch.

save(filename)[source]#

Save the embroidery pattern as an embroidery or image file.

Saves the embroiery pattern to file. Supports standard embroidery file formats, such as .dst, .jef and .pes, and utility formats such as .png, .svg and .txt. For a full list of supported file formats, see the pyembroidery documentation.

Parameters

filenamestr

seth(to_angle)#

Set the orientation of the turtle to to_angle.

Aliases: setheading | seth

Argument: to_angle – a number (integer or float)

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

setheading(to_angle)#

Set the orientation of the turtle to to_angle.

Aliases: setheading | seth

Argument: to_angle – a number (integer or float)

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

setpos(x, y=None)#

Move turtle to an absolute position.

Aliases: setpos | setposition | goto:

Arguments: x – a number or a pair/vector of numbers y – a number None

call: goto(x, y) # two coordinates –or: goto((x, y)) # a pair (tuple) of coordinates –or: goto(vec) # e.g. as returned by pos()

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

setposition(x, y=None)#

Move turtle to an absolute position.

Aliases: setpos | setposition | goto:

Arguments: x – a number or a pair/vector of numbers y – a number None

call: goto(x, y) # two coordinates –or: goto((x, y)) # a pair (tuple) of coordinates –or: goto(vec) # e.g. as returned by pos()

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

setx(x)#

Set the turtle’s first coordinate to x

Argument: x – a number (integer or float)

Set the turtle’s first coordinate to x, leave second 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(y)#

Set the turtle’s second coordinate to y

Argument: y – a number (integer or float)

Set the turtle’s first coordinate to x, second coordinate remains unchanged.

Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 40.00) >>> turtle.sety(-10) >>> turtle.position() (0.00, -10.00)

show_info()[source]#: Display information about this turtle’s embroidery pattern.

speed(s=0)#: dummy method - to be overwritten by child class

start_jump_stitch()[source]#

Set the stitch mode to jump-stitch (not recommended, use jump_stitch-context instead).

With a jump-stitch, trim the thread and move the needle without sewing more stitches.

start_running_stitch(stitch_length)[source]#

Set the stitch mode to running stitch (not recommended, use running_stitch-context instead).

With a running stitch, we get stitches with a constant distance between each stitch.

One step is equivalent to 0.1 mm, we recommend setting the minimum length between each stitch to 30 (3 mm).

It is recommended to use the running_stitch-context instead of the start-functions since they will automatically cleanup afterwards.

Parameters

stitch_lengthint: Number of steps between each stitch.

towards(x, y=None)#

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

Arguments: x – a number or a pair/vector of numbers or a turtle instance y – a number None None

call: distance(x, y) # two coordinates –or: distance((x, y)) # a pair (tuple) of coordinates –or: distance(vec) # e.g. as returned by pos() –or: distance(mypen) # where mypen is another turtle

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

visualise(turtle=None, width=800, height=800, scale=1, done=True, bye=True)[source]#

Use the builtin turtle library to visualise this turtle’s embroidery pattern.

Parameters

patternpyembroidery.EmbPattern: Embroidery pattern to visualise
turtleturtle.Turtle (optional): Python turtle object to use for drawing. If not specified, then the default turtle is used.
widthint: Canvas width
heightint: Canvas height
scaleint: Factor the embroidery length’s are scaled by.
donebool: If True, then turtle.done() will be called after drawing.
byebool: If True, then turtle.bye() will be called after drawing.

xcor()#

Return the turtle’s x coordinate.

No arguments.

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.

Example (for a Turtle instance named turtle): >>> reset() >>> turtle.left(60) >>> turtle.forward(100) >>> print turtle.ycor() 86.6025403784

Additional utilities#

turtlethread.visualise.visualise_pattern(pattern, turtle=None, width=800, height=800, scale=1, done=True, bye=True)[source]#

Use the builtin turtle library to visualise an embroidery pattern.

Parameters

patternpyembroidery.EmbPattern: Embroidery pattern to visualise
turtleturtle.Turtle (optional): Python turtle object to use for drawing. If not specified, then the default turtle is used.
widthint: Canvas width
heightint: Canvas height
scaleint: Factor the embroidery length’s are scaled by.
donebool: If True, then turtle.done() will be called after drawing.
byebool: If True, then turtle.bye() will be called after drawing.

API Reference

Contents

API Reference#

Main functionality#

Additional utilities#