API Reference
Contents
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 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.
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
Display information about this turtle's embroidery pattern.
speed
([s])dummy method - to be overwritten by child class
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.
- 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.
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)
- 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.
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)
- 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)
- 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.