pyembroidery

The library follows a specific data flow for reading, writing, and converting embroidery files. The core data structure is the EmbPattern object.

Data Flow Models

• Read: File $\rightarrow$ Reader $\rightarrow$ Pattern (An EmbPattern is created from a file object/stream).
• Write: Pattern $\rightarrow$ Encoder $\rightarrow$ Pattern $\rightarrow$ Writer $\rightarrow$ File (The encoder ensures data is coherent for the specific writer/format).
• Convert: File $\rightarrow$ Reader $\rightarrow$ Pattern $\rightarrow$ Encoder $\rightarrow$ Pattern $\rightarrow$ Writer $\rightarrow$ File (A full round-trip conversion).

Key Components

• Reader: Parses files and populates an EmbPattern with metadata, threads, and stitches.
• EmbPattern: The central object containing all pattern data.
• Encoder: Converts low-level and middle-level commands into a format suitable for the writer. It can be called directly on a pattern using .get_normalized_pattern() to return a new, encoded pattern without modifying the original.

The library distinguishes between COLOR_CHANGE and NEEDLE_SET commands to accurately represent different machine behaviors (e.g., Barudan machines).

Command Encoding

Commands can encode specific needle or thread information using a bit-packed format: 0bnnnnnnnnttttttttcccccccc where:

• n = needle encoding
• t = thread encoding
• c = command encoding

Middle-level Commands

• SET_CHANGE_SEQUENCE: Used to preset the thread change sequence. For example, encode_thread_change(SET_CHANGE_SEQUENCE, 17) makes the first color change switch to the thread at index 17 in the threadlist, after which subsequent changes follow the standard order (index 0, 1, 2, etc.).
• COLOR_BREAK: Can be used to encode desired thread change orders.

Implementation Note

To parse these complex commands, use the helper functions in EmbFunctions.py: encode_thread_change and decode_embroidery_command. If information is unknown (e.g., a DST file that doesn't support color info), the value will be returned as unknown thread, unknown needle.

Units

• The core unit is 1/10th mm.
• While you can use floating-point numbers, fractional values may be lost when writing to certain formats. pyembroidery attempts to maintain precision by encoding relative distances as integer changes from the last integer position.

Coordinate System

• Orientation: The +y direction is down and -y is up (when viewed horizontally). +x is right and -x is left. This matches modern graphics systems.
• Origin: All patterns start at the origin (0,0).
• Centering: Because absolute positioning is maintained, an off-center pattern will stay at its absolute position. Use pattern.move_center_to_origin() to center the pattern at (0,0), though this will lose the original absolute position data.
• Interfacing: pyembroidery automatically flips the y-axis when reading from or writing to embroidery formats (except SVG) to ensure seamless interfacing.

When you load a pattern from a file, it is filled with raw basic stitch data. To make this data easier to work with or to prepare it for specific operations, you should use one of the following methods:

• get_stable_pattern(): Creates a new pattern by iterating through the current pattern's stitchblocks and re-adding them. This results in a pattern without raw jumps or trims, making it a clean series of stitches and breaks.
• get_pattern_interpolate_trim(): Introduces trim commands after a series of JUMP commands as specified and merges untrimmed jumps.
• get_as_stitchblock(): A generator that produces stitch blocks from the raw loaded data.
• get_pattern_merge_jumps(): Returns a pattern where all sequences of JUMP are replaced with a single STITCH_BREAK command, allowing the encoder to produce optimized jumps.

Note: Calling get_normalized_pattern() is done automatically during the write process. Saving a pattern to disk does not modify the original pattern object; it writes a modified version to the file.

To create an embroidery pattern from scratch, instantiate an EmbPattern object. You can add stitches using absolute coordinates, relative coordinates, or by adding blocks of coordinates. Once the pattern is composed, use write_dst (or other format-specific write functions) to save it to a file.

Common methods for adding data include:

• add_block(coordinates, color): Adds a sequence of points as a single block.
• add_stitch_relative(command, dx, dy): Adds a stitch relative to the current position.
• add_stitch_absolute(command, x, y): Adds a stitch at an absolute coordinate.
• add_command(command): Adds a positionless command (like TRIM or COLOR_CHANGE).

Note: When using add_command, the command is treated as positionless. If you add a command that includes x and y operands, behavior is undefined. Internally, elements are stored as [x, y, command] to facilitate position usage, but the API expects command, x, y (or just command).

from pyembroidery import *

# Create a new pattern
pattern = EmbPattern()

# Add a square block of stitches in red
pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0), (0, 0)], "red")

# Save the pattern to a DST file
write_dst(pattern, "file.dst")