Main functionality

class turtlethread.Turtle(pattern=None, scale=1, angle_mode='degrees', mode='standard', color=None)

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

This class has the same API as the builtin turtle.Turtle class with documented changes, for more information see the official documentation of the builtin turtle library

One turtle-step is equivalent to 0.1 mm (unless scaled otherwise).

Parameters

patternturtlethread.stitches.EmbroideryPattern (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

property angle_mode

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

begin_fill(mode=<turtlethread.fills.ScanlineFill object>, closed=True)

After begin_fill is called, the turtle will track the stitches made until end_fill is called, afterwhich the polygon formed by the stitches will be filled. The current implementation of fill is limited to straight lines between points of the polygon. This works well for “straight” stitches like running stitch and satin stitch, but will not fill in the spaces formed in stitches such as zigzag stitch.

Parameters

modeturtlethread.fills.Fill (optional, default = fills.ScanlineFill())

The fill mode to use. Refer to the API reference for the possible fills.

closedbool (optional, default=True)

Whether or not to automatically close the shape in the event it is not closed. This must be set to False if jump stitches are used to create a fill with a hollowed part.

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

Draw a circle or arc, for more info see the official turtle.circle() documentation.

Parameters

radius: float

Radius of the circle

extent: float

The angle of the arc, by default it is a full circle

steps: float

The circle is approximated as a sequence of steps line segments. If the steps are not given, then the optimal number of line segments for the current stitch length is selected.

cleanup_stitch_type()

Cleanup after switching stitch type.

cross_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to cross stitch.

end_fill()

End the current fill, and draw the filled polygon.

fast_visualise(turtle=None, width=800, height=800, scale=1, speed=6, extra_speed=1, trace_jump=False, skip=False, check_density=True, done=True, bye=True)

A fast version of the visualise() function, though it has undergone less testing.

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.

speedint

Speed that the turtle object moves at.

extra_speedint

Extra speed boost on top of everything. Defaults to 1, which is no speed boost. 0 is infinite speed boost

trace_jumpbool

If True, then draw a grey line connecting the origin and destination of jumps.

skipbool

If True, then skip the drawing animation and jump to the completed visualisation.

check_densitybool

If True, then check the density of the embroidery pattern. Recommended but slow.

donebool

If True, then turtle.done() will be called after drawing.

byebool

If True, then turtle.bye() will be called after drawing.

home()

Move the needle home (position (0, 0)), for more info see the official turtle.home() documentation

jump_stitch(skip_intermediate_jumps=True)

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.

Parameters

skip_intermediate_jumpsbool (optional, default=True)

If True, then multiple jump commands will be collapsed into one jump command. This is useful in the cases where there may be multiple subsequent jumps with no stitches inbetween. Multiple subsequent jumps doesn’t make sense but it can happen dependent on how you generate your patterns.

running_stitch(stitch_length=30)

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.

satin_stitch(width, center=True)

Set the stitch mode to satin stitch.

save(filename, color_inf_filename=None)

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

filename : str

show_info()

Display information about this turtle’s embroidery pattern.

start_cross_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to cross stitch.

start_jump_stitch()

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=30)

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.

start_satin_stitch(width, center=True)

Set the stitch mode to satin stitch.

start_triple_stitch(stitch_length)

Set the stitch mode to triple stitch (not recommended, use triple_stitch-context instead).

Triple stitch is equivalent to running stitch, but the thread moves back and forth three times for 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.

start_z_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to z stitch.

start_zigzag_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to zigzag stitch.

triple_stitch(stitch_length)

Set the stitch mode to triple stitch and cleanup afterwards.

Triple stitch is equivalent to running stitch, but the thread moves back and forth three times for 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.

visualise(turtle=None, width=800, height=800, scale=1, speed=6, trace_jump=False, skip=False, check_density=True, done=True, bye=True)

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.

speedint

Speed that the turtle object moves at.

trace_jumpbool

If True, then draw a grey line connecting the origin and destination of jumps.

skipbool

If True, then skip the drawing animation and jump to the completed visualisation.

check_densitybool

If True, then check the density of the embroidery pattern. Recommended but slow.

donebool

If True, then turtle.done() will be called after drawing.

byebool

If True, then turtle.bye() will be called after drawing.

z_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to z stitch.

zigzag_stitch(stitch_length: int | float, stitch_width: int | float, center: bool = False, auto_adjust: bool = True, enforce_end_stitch: bool = True, enforce_start_stitch: bool = True) → None

Set the stitch mode to zigzag stitch.