Ctrl+K

Overview of stitch types in TurtleThread

Overview of stitch types in TurtleThread#

TurtleThread currently supports two stitch types: running stitch and jump stitch (zig-zag stitch is under development). In this tutorial, we will look at what a stitch type does and what the differences between these two types are.

No stitches#

Let’s start by creating a turtle to control our needle and ask the turtle to walk 60 steps forward.

1from turtlethread import Turtle
2
3needle = Turtle()
4needle.forward(60)

What happens when we visualize this?

1from turtlethread import Turtle
2
3needle = Turtle()
4needle.forward(60)
5needle.visualise()
Result from the above code. An image showing only a triangle that marks the location of the turtle

Here we only see the turtle marker! This is because we just asked the turtle to move forward. We have yet to ask the turtle to sew with stitches. We can see these clearly if we save the embroidery pattern as a text file and look at the file’s contents.

1from turtlethread import Turtle
2
3needle = Turtle()
4needle.forward(60)
5needle.save("pattern_no_stitch.txt")

0.0,0.0 color:9420183 command:END flags:4

The embroidery pattern doesn’t contain any stitches at all!

Running stitch#

To get the turtle to sew with stitches while it moves, we can use a context manager that decides the stitch type. So if we, for example, want a running stitch, we can write.

1from turtlethread import Turtle
2
3needle = Turtle()
4with needle.running_stitch(20):
5    needle.forward(60)
6
7needle.visualise()
8needle.save("pattern_running_stitch_20.txt")
:alt: Result from the above code. A horizontal blue line with four short vertical lines with equal distance between them. 
0.0,0.0 color:15867815 command:STITCH flags:0
20.0,0.0 color:15867815 command:STITCH flags:0
40.0,0.0 color:15867815 command:STITCH flags:0
60.0,0.0 color:15867815 command:STITCH flags:0
60.0,0.0 color:15867815 command:END flags:4

The visualization now shows some short lines across, indicating where the stitches are. We can also see from the text file that there are stitches placed at positions (0, 0), (20, 0), (40, 0) and (60, 0). So there are 20 steps between each stitch. This 20 step spacing comes from line 4, where we decided the length between stitches by writing with needle.running_stitch(20). If we want the stitches to be 30 steps long instead, we can write:

1from turtlethread import Turtle
2
3needle = Turtle()
4with needle.running_stitch(30):
5    needle.forward(60)
6
7needle.visualise()
8needle.save("pattern_running_stitch_30.txt")
Result from the above code. A horizontal blue line with three short vertical lines, one at each end and one in the middle. 
0.0,0.0 color:14703462 command:STITCH flags:0
30.0,0.0 color:14703462 command:STITCH flags:0
60.0,0.0 color:14703462 command:STITCH flags:0
60.0,0.0 color:14703462 command:END flags:4

Indentation is important#

Notice that line 5 is indented one step. Python uses indenting to group lines of code into one block. Suppose we add new lines that are indented equally. In that case, they will also belong to the same block, the running stitch block, and will be executed with a running stitch.

 1from turtlethread import Turtle
 2
 3needle = Turtle()
 4with needle.running_stitch(30):
 5    needle.forward(60)
 6    needle.right(90)
 7    needle.forward(30)
 8
 9needle.visualise()
10needle.save("pattern_angle.txt")
Result from the above code. A horizontal blue line is followed by a vertical line down, which is half as long as the horizontal line. Every line has short lines across to indicate the position of the stitches 
0.0,0.0 color:14030372 command:STITCH flags:0
30.0,0.0 color:14030372 command:STITCH flags:0
60.0,0.0 color:14030372 command:STITCH flags:0
60.0,-30.0 color:14030372 command:STITCH flags:0
60.0,-30.0 color:14030372 command:END flags:4

We see lines 5-7 belong together in a block under the running stitch context. We can continue to add as many lines as we want inside the same indent level, and they will be executed with a running stitch seam. Here is an example where we have placed a for loop inside the running stitch context:

1from turtlethread import Turtle
2
3needle = Turtle()
4with needle.running_stitch(30):
5    for side in range(4):
6        needle.forward(60)
7        needle.right(90)
8
9needle.visualise()
Result from the above code. A blue square with short lines across to mark the stitch positions

If we instead add a line outside the indent level, this line will not be executed with a running stitch seam.

1from turtlethread import Turtle
2
3needle = Turtle()
4with needle.running_stitch(30):
5    needle.forward(60)
6needle.right(90)
7needle.forward(30)
8
9needle.visualise()
Result from the above code. A horizontal blue line with three short vertical lines, one at each end and one in the middle.

Jump stitch#

If we want to move the needle without creating stitches, we can use the jump stitch. For example, the code below shows how we can use a jump stitch to draw two lines with a gap in between.

 1from turtlethread import Turtle
 2
 3needle = Turtle()
 4# Create 2 stitches with 30 steps between 
 5with needle.running_stitch(30):
 6    needle.forward(60)
 7    
 8# Jump 45 steps forwards without creating any stitches. 
 9# (If the machine supports it, the thread is trimmed.)
10with needle.jump_stitch():
11    needle.forward(45)
12
13# Create 2 stitches with 30 steps between 
14with needle.running_stitch(30):
15    needle.forward(60)
16
17needle.visualise()
18needle.save("pattern_jump.txt")
Result from the above code. A horizontal blue line with three short vertical lines, one at each end and one in the middle, followed by a black cross to indicate that the thread should be cut, a red line ending in a red circle, indicating that the needle should be moved without stitches and finally a new horizontal blue line with three short vertical lines. 
0.0,0.0 color:14300770 command:STITCH flags:0
30.0,0.0 color:14300770 command:STITCH flags:0
60.0,0.0 color:14300770 command:STITCH flags:0
60.0,0.0 color:14300770 command:TRIM flags:2
105.0,0.0 color:14300770 command:JUMP flags:1
105.0,0.0 color:14300770 command:STITCH flags:0
135.0,0.0 color:14300770 command:STITCH flags:0
165.0,0.0 color:14300770 command:STITCH flags:0
165.0,0.0 color:14300770 command:END flags:4

The visualization above shows that the first blue line ends with a black cross. If the embroidery machine you use supports it, the thread will be cut here (but not all machines support this). If your machine does not support thread cutting, you will have to manually cut it afterwards. In the pattern text file, we see the command TRIM on line 4, indicating that the thread should be cut if supported. On line 5, we see JUMP, indicating that the needle should move here without creating stitches.

What is a context manager?#

As we mentioned at the beginning of this tutorial, with needle.running_stitch(30) and with needle.jump_stitch() are context managers defining which stitch types the turtle should sew with while it moves. Context managers in Python are used when we have something that needs a start and end instruction. In our case, it is starting and ending a stitch type. Behind the scenes

1from turtlethread import Turtle
2
3needle = Turtle()
4with needle.running_stitch(30):
5    needle.forward(60)

Is the same as

1from turtlethread import Turtle
2
3needle = Turtle()
4needle.start_running_stitch(30)
5needle.forward(60)
6needle.cleanup_stitch_type()

But it is recommended to use the context manager in most cases. This is because it is cleaner and guarantees that you always end the stitch type you started in an orderly way.

Contents