### Transcoding an EmbPattern Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Example showing how to initialize an EmbPattern, add a block of stitches, and use the EmbEncoder to transcode the pattern with specific constraints. ```python from pyembroidery import EmbPattern, EmbEncoder pattern = EmbPattern() pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0)], "red") transcoder = EmbEncoder.Transcoder({"max_stitch": 40, "max_jump": 40}) encoded = transcoder.transcode(pattern, EmbPattern()) ``` -------------------------------- ### Install pyembroidery with pip Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Install the pyembroidery library using pip. Requires Python 3; Python 2 support was dropped at end-of-life 1-1-2020. ```bash pip install pyembroidery ``` -------------------------------- ### Usage Example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Example of using EmbEncoder.Transcoder to transcode a pattern with custom max stitch and jump lengths. ```APIDOC ## Usage Example ```python from pyembroidery import EmbPattern, EmbEncoder pattern = EmbPattern() pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0)], "red") transcoder = EmbEncoder.Transcoder({"max_stitch": 40, "max_jump": 40}) encoded = transcoder.transcode(pattern, EmbPattern()) ``` ``` -------------------------------- ### Add block and merge pattern example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md Example usage of add_block to add a square block with thread "red" and add_pattern to merge another pattern shifted by (40, 40). ```python pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0), (0, 0)], "red") pattern.add_pattern(other, dx=40, dy=40) # merge shifted by (40, 40) ``` -------------------------------- ### Basic pattern composition with add_block and write_dst Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Creates an EmbPattern, adds a block of coordinates with a color, and writes it to a .dst file. Use this as the starting point for any pattern. ```python from pyembroidery import * pattern = EmbPattern() pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0), (0, 0)], "red") write_dst(pattern, "file.dst") ``` -------------------------------- ### decode_embroidery_command usage example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embfunctions.md Shows how to encode a command and then decode it back, verifying the round-trip with an assertion. ```python from pyembroidery import decode_embroidery_command, encode_thread_change cmd = encode_thread_change(5, thread=2, needle=1, order=0) flags, thread, needle, order = decode_embroidery_command(cmd) assert (flags, thread, needle, order) == (5, 2, 1, 0) ``` -------------------------------- ### Configure embroidery writing settings Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/configuration.md Example of passing a settings dictionary to pyembroidery.write to define tie-on/off contingencies, stitch/jump limits, translation, and trimming behavior. ```python pyembroidery.write( pattern, "file.dst", { "tie_on": pyembroidery.CONTINGENCY_TIE_ON_THREE_SMALL, "tie_off": pyembroidery.CONTINGENCY_TIE_OFF_THREE_SMALL, "max_stitch": 121, "max_jump": 121, "translate": (40, 50), "explicit_trim": True, }, ) ``` -------------------------------- ### EmbThread usage example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embthread.md Demonstrates creating EmbThread instances from various inputs and using set_color and hex_color. Shows that 'red' is an X11 name, '#ff00ff' with 'Magenta' and '010' sets color and metadata, and set() accepts a dict. Outputs '#ff0000' and 255 for the red channel. ```python from pyembroidery import EmbThread thread = EmbThread("red") # X11 name thread = EmbThread("#ff00ff", "Magenta", "010") thread.set({"hex": "f00", "name": "Bright Red", "brand": "Madeira"}) thread.set_color(255, 0, 0) print(thread.hex_color(), thread.get_red()) # '#ff0000' 255 ``` -------------------------------- ### encode_thread_change usage example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embfunctions.md Shows how to use encode_thread_change to add commands to a pattern. The first example sets a change sequence to threadlist index 17, and the second sets a needle to needle #2. ```python from pyembroidery import encode_thread_change, SET_CHANGE_SEQUENCE, COLOR_CHANGE, NEEDLE_SET # First color change switches to threadlist index 17, then 0, 1, 2, ... pattern.add_command(encode_thread_change(SET_CHANGE_SEQUENCE, 17)) # A needle set to needle #2 pattern.add_command(encode_thread_change(NEEDLE_SET, None, 2)) ``` -------------------------------- ### Using write_int_16le and read_int_16le Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/io-helpers.md Example showing how to write a 16-bit little-endian integer to a stream and read it back using the helper functions. The read returns None at EOF. ```python from pyembroidery.WriteHelper import write_int_16le from pyembroidery.ReadHelper import read_int_16le write_int_16le(f, 0x1234) value = read_int_16le(f) # 0x1234, or None at EOF ``` -------------------------------- ### get_common_name_dictionary usage example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embfunctions.md Shows how to retrieve the common name dictionary and print the name for command 0, which is 'STITCH'. ```python from pyembroidery import get_common_name_dictionary names = get_common_name_dictionary() print(names[0]) # 'STITCH' ``` -------------------------------- ### Adding stitch blocks with add_block() Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Shows two examples of adding stitch blocks to a pattern. The first uses a list of tuples and a color name, the second uses a flat list of integers and a hex color string. ```python pattern.add_block([(0, 0), (0, 100), (100, 100), (100, 0), (0, 0)], "red") pattern.add_block([0, 0, 0, 100, 100, 100, 100, 0, 0, 0], "#f00") ``` -------------------------------- ### Reading embroidery files with pyembroidery Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Example usage of pyembroidery reading functions. Shows extension dispatch via read, an explicit reader call, and appending to an existing pattern by passing the pattern as the third argument. ```python import pyembroidery pattern = pyembroidery.read("myembroidery.exp") # extension dispatch pattern = pyembroidery.read_dst(file_object) # explicit reader merged = pyembroidery.read("second.dst", None, pattern) # append ``` -------------------------------- ### EmbCompress.__init__ Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/types.md Initializes an EmbCompress instance. ```APIDOC ## EmbCompress.__init__ ### Description Initializes a new EmbCompress instance. ### Method Constructor ### Signature ```python EmbCompress() ``` ### Parameters None ### Returns None ``` -------------------------------- ### Huffman.__init__ Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/types.md Initializes a Huffman coding table with optional lengths and value. ```APIDOC ## Huffman.__init__ ### Description Initializes a Huffman coding table. ### Method Constructor ### Signature ```python Huffman(lengths=None, value=0) ``` ### Parameters - **lengths** (optional) - Initial code lengths. - **value** (int, optional) - Initial value. ### Returns None ``` -------------------------------- ### Write with settings dictionary Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Writes a pattern with a settings dictionary that configures tie-on, tie-off, and translation. The dictionary can override format defaults. ```python pyembroidery.write(pattern, file.dst, { "tie_on": CONTINGENCY_TIE_ON_THREE_SMALL, "tie_off": CONTINGENCY_TIE_OFF_THREE_SMALL, "translate": (40, 50) } ``` -------------------------------- ### Access stitch by index Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Gets a particular stitch of the pattern using indexing. ```python pattern[0] ``` -------------------------------- ### GenericWriter.open_pattern() / open_document() / open_color() / open_block() Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/genericwriter.md Deferred opening flags; write_opens emits *_start (and color_join/block_join when index > 0). ```APIDOC ## GenericWriter.open_pattern() / open_document() / open_color() / open_block() ### Description Deferred opening flags; `write_opens` emits `*_start` (and `color_join`/`block_join` when index > 0). ### Method Method ### Signatures - `open_pattern(self)` - `open_document(self)` - `open_color(self)` - `open_block(self)` ### Returns None ``` -------------------------------- ### Transcoder.__init__(settings=None) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Initializes a Transcoder instance with optional encoding settings. The settings dictionary controls stitch limits, thread change behavior, contingencies, and geometric transformations. ```APIDOC ## Transcoder.__init__(settings=None) ### Description Initializes a Transcoder instance with optional encoding settings. The settings dictionary controls stitch limits, thread change behavior, contingencies, and geometric transformations. ### Method Constructor ### Signature ```python def __init__(self, settings=None): ``` ### Parameters #### settings (dict, optional) - **Type**: dict - **Default**: `None` - **Required**: No - **Description**: Encoding settings; see configuration.md for the full reference. ### Settings Keys | Key | Type | Default | Meaning | |-----|------|---------|---------| | `max_stitch` | float | `float("inf")` | Maximum encodable stitch length in 1/10 mm. | | `max_jump` | float | `float("inf")` | Maximum encodable jump length in 1/10 mm. | | `full_jump` | bool | `False` | When set, a final full jump is emitted even if already within range. | | `round` | bool | `False` | Round transformed coordinates to integers. | | `needle_count` | int | `5` | Needles available for the machine; if `<= 1` and `thread_change_command == NEEDLE_SET`, the thread-change command degrades to `STOP`. | | `thread_change_command` | int | `COLOR_CHANGE` | Command used for thread changes (`COLOR_CHANGE`, `NEEDLE_SET`, or `STOP`). | | `strip_sequins` | bool | `True` | *(deprecated)* `True` → sequin contingency `CONTINGENCY_SEQUIN_JUMP`, `False` → `CONTINGENCY_SEQUIN_UTILIZE`; overridden by `sequin_contingency` when present. | | `sequin_contingency` | int | see left | One of the `CONTINGENCY_SEQUIN_*` constants. | | `writes_speeds` | bool | `True` | Whether `SLOW`/`FAST` commands are emitted. | | `explicit_trim` | bool | `False` | Emit an explicit `TRIM` before thread changes. | | `tie_on` | int | `CONTINGENCY_TIE_ON_NONE` | Tie-on contingency; boolean `True`/`False` are coerced to `THREE_SMALL`/`NONE`. | | `tie_off` | int | `CONTINGENCY_TIE_OFF_NONE` | Tie-off contingency; boolean coercion as above. | | `long_stitch_contingency` | int | `CONTINGENCY_LONG_STITCH_JUMP_NEEDLE` | Behavior for over-long stitches. | | `translate` | tuple/object | `None` | `(tx, ty)` or object with `.x`/`.y`; applied as `post_translate`. | | `scale` | tuple/object/scalar | `None` | `(sx, sy)` or object with `.x`/`.y` or scalar; applied as `post_scale`. | | `rotate` | float | `None` | Degrees; applied as `post_rotate`. | ### Notes - All transformations compose onto a single working `EmbMatrix` in the order translate → scale → rotate. - `max_stitch`, `max_jump`, `needle_count`, `thread_change_command`, `sequin_contingency`, and friends are normally supplied automatically by `write_embroidery` from the target writer's module attributes (see pyembroidery-api.md). ### Example ```python from pyembroidery.EmbEncoder import Transcoder transcoder = Transcoder({ "max_stitch": 12.0, "max_jump": 100.0, "needle_count": 6, "thread_change_command": 2, # NEEDLE_SET "translate": (10, 20), "scale": 1.5, "rotate": 45.0 }) ``` ``` -------------------------------- ### EmbThreadPec instantiation example Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embthread.md Creates a Brother PEC thread with red color (237, 23, 31), description 'Red', and catalog number '5'. The EmbThreadPec class is part of the pyembroidery namespace. ```python from pyembroidery import EmbThreadPec pec_red = EmbThreadPec(237, 23, 31, "Red", "5") ``` -------------------------------- ### metadata(name, data) and get_metadata(name, default=None) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md Sets and gets metadata key-value pairs. The name 'name' is honored by writers (e.g., DST header LA:, PEC title, PES metadata). ```APIDOC ## metadata(name, data) / get_metadata(name, default=None) ### Description Sets and gets metadata key-value pairs. The name 'name' is honored by writers (DST header `LA:`, PEC title, PES metadata). ### Method metadata / get_metadata ### Parameters - **name** (str) - Required - Metadata key. - **data** (any) - Required - Metadata value (for set). - **default** (any) - Optional - Returned value if key not found (for get). ### Returns - metadata: None - get_metadata: stored value or default ``` -------------------------------- ### GenericWriter.__init__(self, pattern, f, settings) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/genericwriter.md Constructor for the GenericWriter class. Initializes the writer with a pattern, output stream, and template settings. ```APIDOC ## GenericWriter.__init__(self, pattern, f, settings) ### Description Initializes a GenericWriter instance with the given pattern, output stream, and template settings. ### Method Constructor ### Signature `__init__(self, pattern, f, settings)` ### Parameters - **pattern** (EmbPattern) - Required - Source pattern; all settings formats read `pattern.extras`, `threadlist`, `stitches`. - **f** (text-mode stream) - Required - Output stream. - **settings** (dict) - Required - Template settings; may be empty `{}`. ### Returns None ### Notes - Reads template keys from `settings`: `metadata_entry`, `thread_entry`, `pattern_start`, `pattern_end`, `document_start`, `document_end`, `color_start`, `color_end`, `color_join`, `block_start`, `block_end`, `block_join`, `segment_start`, `segment`, `segment_end`, `segment_join`, `stitch_first`, `stitch_last`, `stitch`, `stop`, `jump`, `trim`, `needle_set`, `color_change`, `sequin`, `sequin_mode`, `slow`, `fast`, `end`, and `stitch_z_travel` (default `10.0`). ``` -------------------------------- ### EmbPattern constructor signature Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md The constructor accepts optional arguments. With no arguments, it returns an empty pattern. With an EmbPattern, it copies the pattern. With a filename string, it loads the file into the instance. ```python def __init__(self, *args, **kwargs): ``` -------------------------------- ### transcode(source_pattern, destination_pattern) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Runs metadata and main transcoding. If both patterns are the same object, the source is copied first and the destination cleared. ```APIDOC ## transcode(source_pattern, destination_pattern) ### Description Runs metadata + main transcoding. If both patterns are the same object, the source is copied first and the destination cleared. ### Method N/A (Python method) ### Endpoint N/A ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **source_pattern** (EmbPattern) - Required - The source embroidery pattern. - **destination_pattern** (EmbPattern) - Required - The destination embroidery pattern. ### Request Example ```python # Example usage emb_encoder.transcode(source_pattern, destination_pattern) ``` ### Response #### Success Response (200) - **destination_pattern** (EmbPattern) - The transcoded destination pattern. #### Response Example ```python # Returns the destination_pattern ``` ``` -------------------------------- ### Using expand to decompress a HUS payload Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embcompress.md Example of using the expand function to decompress a HUS payload. The header and payload reading are placeholders; the actual HUS header layout is in HusReader. expand returns a list of decompressed bytes. ```python from pyembroidery import expand with open("design.hus", "rb") as f: header = f.read(...) # HUS header layout lives in HusReader ... payload = f.read(...) # compressed bytes from the format stream restored = expand(payload) # list of decompressed bytes ``` -------------------------------- ### build_thread_change_sequence() Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Plans every color change: fills unset command with thread_change_command, unset thread with sequential 0-based indexes, unset needle with a 1-based needle (wrapping at needle_count), and resolves thread objects via get_thread_or_filler. ```APIDOC ## build_thread_change_sequence() ### Description Plans every color change: fills unset command with thread_change_command, unset thread with sequential 0-based indexes, unset needle with a 1-based needle (wrapping at needle_count), and resolves thread objects via get_thread_or_filler. ### Method N/A (Python method) ### Endpoint N/A ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python # Example usage sequence = emb_encoder.build_thread_change_sequence() ``` ### Response #### Success Response (200) - **dict** (dict {order: [command, thread, needle, EmbThread]}) - A dictionary mapping order to a list of command, thread, needle, and EmbThread. #### Response Example ```python # Returns a dictionary like {0: [command, thread, needle, EmbThread]} ``` ``` -------------------------------- ### Adding middle-level stitch commands with add_command Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embconstant.md Shows how to add middle-level stitch commands to an EmbPattern. Use add_command for constants without position operands (like CONTINGENCY_TIE_ON_THREE_SMALL and OPTION_IMPLICIT_TRIM) and add_stitch_relative for position-taking commands. The example toggles encoder state on the fly: ties on, stitches, then implies a trim before a color change. ```python import pyembroidery pattern = pyembroidery.EmbPattern() pattern.add_command(pyembroidery.CONTINGENCY_TIE_ON_THREE_SMALL) # tie on from here on pattern.stitch(0, 0) pattern.stitch(20, 20) pattern.add_command(pyembroidery.OPTION_IMPLICIT_TRIM) # trims implied by color change pattern.color_change() ``` -------------------------------- ### transcode_main() Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md The state machine. Iterates source stitches, applies the matrix, dispatches per command (low-level, middle-level, option, contingency, and matrix commands), and always finishes with an END (appended when absent). ```APIDOC ## transcode_main() ### Description The state machine. Iterates source stitches, applies the matrix, dispatches per command (low-level, middle-level, option, contingency, and matrix commands), and always finishes with an END (appended when absent). ### Method N/A (Python method) ### Endpoint N/A ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python # Example usage emb_encoder.transcode_main() ``` ### Response #### Success Response (200) - **None** - No return value. #### Response Example ```python # No return value ``` ``` -------------------------------- ### EmbThread.__init__ Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embthread.md Constructor for the EmbThread class, which models a spool of thread with an RGB color and catalog metadata. ```APIDOC ## EmbThread Constructor ### Description Creates a new EmbThread instance representing a spool of thread with an RGB color and optional catalog metadata. ### Method Constructor ### Endpoint `EmbThread(thread=None, description=None, catalog_number=None, details=None, brand=None, chart=None, weight=None)` ### Parameters - **thread** (int / str / dict / EmbThread) - Optional - Initializer forwarded to `set()`. - **description** (str) - Optional - Human-readable color name. - **catalog_number** (str) - Optional - Thread company catalog/dye number. - **details** (str) - Optional - Free-form details. - **brand** (str) - Optional - Brand name. - **chart** (str) - Optional - Color chart name. - **weight** (str) - Optional - Thread weight. ### Request Example ```python from pyembroidery import EmbThread thread = EmbThread("red") thread = EmbThread("#ff00ff", "Magenta", "010") ``` ### Response #### Success Response Returns an EmbThread instance with `color` defaulting to `0x000000` (black). ``` -------------------------------- ### convert and get_extension_by_filename method signatures Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Declares the static methods convert and get_extension_by_filename. convert reads from filename_from via static_read and writes to filename_to via static_write; if reading returns None, convert returns None without writing. get_extension_by_filename returns the extension without the dot using os.path.splitext. ```python @staticmethod def convert(filename_from, filename_to, settings=None): @staticmethod def get_extension_by_filename(filename): ``` -------------------------------- ### Huffman.build_table Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/types.md Builds the Huffman lookup table. ```APIDOC ## Huffman.build_table ### Description Builds the Huffman decoding table. ### Method Method ### Signature ```python build_table(self) -> None ``` ### Parameters None ### Returns None ``` -------------------------------- ### Using EmbPattern shorthand methods to build a pattern Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md Creates an EmbPattern and appends commands using the shorthand methods: two STITCH commands, a TRIM, a COLOR_CHANGE, and an END. All methods mutate self.stitches and return None. ```python import pyembroidery pattern = pyembroidery.EmbPattern() pattern.stitch(0, 0) # STITCH at (0, 0) pattern.stitch(50, 50) pattern.trim() # TRIM, no movement pattern.color_change() pattern.end() ``` -------------------------------- ### EmbPattern add/insert/prepend method signatures Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md Method signatures for adding, inserting, and prepending content to an EmbPattern. All methods return None except get_metadata, which returns the stored value or default. Note that insert, prepend_command, and add_command treat x, y as parameters and do not update _previousX/_previousY. ```python def add_thread(self, thread): def metadata(self, name, data): def get_metadata(self, name, default=None): def add_stitch_absolute(self, cmd, x=0, y=0): def add_stitch_relative(self, cmd, dx=0, dy=0): def insert_stitch_relative(self, position, cmd, dx=0, dy=0): def insert(self, position, cmd, x=0, y=0): def prepend_command(self, cmd, x=0, y=0): def add_command(self, cmd, x=0, y=0): def add_block(self, block, thread=None): def add_stitchblock(self, stitchblock): def add_pattern(self, pattern, dx=None, dy=None, sx=None, sy=None, rotate=None): def append_translation(self, x, y): ``` -------------------------------- ### read_vp3(f, settings=None, pattern=None) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Reads a VP3 embroidery file and returns an EmbPattern. Accepts a file object or filename, optional settings dict, and optional pattern to append to. ```APIDOC ## read_vp3(f, settings=None, pattern=None) ### Description Reads a VP3 embroidery file and returns an EmbPattern. Accepts a file object or filename, optional settings dict, and optional pattern to append to. ### Method read_vp3 ### Parameters #### Path Parameters - **f** (file object or str) - Required - Input. File object passed straight to the reader; string opened in binary mode. #### Query Parameters - **settings** (dict) - Optional - Reader settings. - **pattern** (EmbPattern) - Optional - When provided, the reader appends into this pattern and it is returned. ### Request Example ```python import pyembroidery pattern = pyembroidery.read_vp3("myembroidery.vp3") ``` ### Response #### Success Response - **EmbPattern** - The populated embroidery pattern. #### Response Example ```python pattern # EmbPattern object ``` ``` -------------------------------- ### supported_formats() Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Returns a generator of dictionaries, one per supported format, describing each format's properties such as extension, category, and read/write capabilities. ```APIDOC ## supported_formats() ### Description Returns a generator of dictionaries, one per supported format, describing each format's properties such as extension, category, and read/write capabilities. ### Method Static method ### Signature ```python @staticmethod def supported_formats(): ``` ### Returns - **generator of dict** - Each dict contains the following keys: - `description` (str) - Always present - Human-readable description of the format. - `extension` (str) - Always present - Canonical extension used for dispatch. - `extensions` (tuple of str) - Always present - Aliases for the extension (often a 1-tuple). - `mimetype` (str) - Always present - MIME type of the format. - `category` (str) - Always present - One of `"embroidery"`, `"vector"`, `"debug"`, `"color"`, `"stitch"`, `"image"`. - `reader` (module) - Present when readable - Module that reads the format. - `writer` (module) - Present when writable - Module that writes the format. - `versions` (tuple of str) - Present when writer supports version selection - Supported versions. - `metadata` (tuple of str) - Present when format reads/writes extras - Names of extras. - `read_options` (dict) - Present when readable - Accepted reader settings and allowed values. - `write_options` (dict) - Present when writable - Accepted writer settings and allowed values. ### Example ```python for fmt in pyembroidery.supported_formats(): print(fmt["extension"], fmt["category"], "R" if "reader" in fmt else "-", "W" if "writer" in fmt else "-") ``` ``` -------------------------------- ### __copy__ / __deepcopy__ Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embpattern.md Both delegate to the `copy()` method. ```APIDOC ## __copy__ / __deepcopy__ ### Description Both delegate to `copy()`. ### Signature `(self)` ### Returns - **EmbPattern** - A copy of the pattern. ``` -------------------------------- ### List supported formats with reader/writer flags Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Iterates over the formats returned by supported_formats and prints the extension, category, and whether the format has a reader or writer. The output uses 'R' and 'W' markers. ```python for fmt in pyembroidery.supported_formats(): print(fmt["extension"], fmt["category"], "R" if "reader" in fmt else "-", "W" if "writer" in fmt else "-") ``` -------------------------------- ### convert(filename_from, filename_to, settings=None) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Converts an embroidery file from one format to another. Reads the input file using the appropriate reader based on its extension and writes the output using the appropriate writer. ```APIDOC ## convert(filename_from, filename_to, settings=None) ### Description Converts an embroidery file from one format to another. Reads the input file using the appropriate reader based on its extension and writes the output using the appropriate writer. ### Method Static method ### Signature ```python @staticmethod def convert(filename_from, filename_to, settings=None): ``` ### Parameters - **filename_from** (str) - Required - Input path; read via `static_read` (extension dispatch). If reading returns `None`, `convert` returns `None` without writing. - **filename_to** (str) - Required - Output path; written via `static_write`. - **settings** (dict) - Optional - Passed to both reader and writer. ### Example ```python import pyembroidery pyembroidery.convert("embroidery.jef", "converted.dst") # Reader -> Pattern -> Encoder -> Writer ``` ``` -------------------------------- ### Read pattern from disk with pyembroidery.read Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Loads an embroidery pattern from a file path. The file extension determines the reader used; for .dat files, the reader detects the format automatically. ```python pattern = pyembroidery.read("myembroidery.exp") ``` -------------------------------- ### EmbEncoder Constructor Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Initializes the Transcoder with optional encoding settings. ```python def __init__(self, settings=None): ``` -------------------------------- ### read_xxx(f, settings=None, pattern=None) Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Reads an XXX embroidery file and returns an EmbPattern. Accepts a file object or filename, optional settings dict, and optional pattern to append to. ```APIDOC ## read_xxx(f, settings=None, pattern=None) ### Description Reads an XXX embroidery file and returns an EmbPattern. Accepts a file object or filename, optional settings dict, and optional pattern to append to. ### Method read_xxx ### Parameters #### Path Parameters - **f** (file object or str) - Required - Input. File object passed straight to the reader; string opened in binary mode. #### Query Parameters - **settings** (dict) - Optional - Reader settings. - **pattern** (EmbPattern) - Optional - When provided, the reader appends into this pattern and it is returned. ### Request Example ```python import pyembroidery pattern = pyembroidery.read_xxx("myembroidery.xxx") ``` ### Response #### Success Response - **EmbPattern** - The populated embroidery pattern. #### Response Example ```python pattern # EmbPattern object ``` ``` -------------------------------- ### Import pyembroidery Source: https://github.com/embroidepy/pyembroidery/blob/main/README.md Import the pyembroidery library to access its reading and writing functions. ```python import pyembroidery ``` -------------------------------- ### Writer method signatures for pyembroidery Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/pyembroidery-api.md Lists the static method signatures for all format-specific writers (write_dst, write_pec, etc.) plus the generic write_embroidery and static_write entry points. All return None and never mutate the pattern. ```python @staticmethod def write_dst(pattern, stream, settings=None): def write_pec(pattern, stream, settings=None): def write_pes(pattern, stream, settings=None): def write_exp(pattern, stream, settings=None): def write_vp3(pattern, stream, settings=None): def write_jef(pattern, stream, settings=None): def write_u01(pattern, stream, settings=None): def write_csv(pattern, stream, settings=None): def write_json(pattern, stream, settings=None): def write_txt(pattern, stream, settings=None): def write_gcode(pattern, stream, settings=None): def write_xxx(pattern, stream, settings=None): def write_tbf(pattern, stream, settings=None): def write_svg(pattern, stream, settings=None): def write_png(pattern, stream, settings=None): @staticmethod def write_embroidery(writer, pattern, stream, settings=None): @staticmethod def static_write(pattern, filename, settings=None): ``` -------------------------------- ### expand Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/types.md Expands compressed data and returns a list of integers. ```APIDOC ## expand ### Description Expands compressed data. ### Method Function ### Signature ```python expand(data, uncompressed_size=None) -> list ``` ### Parameters - **data** - The compressed data. - **uncompressed_size** (optional) - The expected uncompressed size. ### Returns - **list** - A list of integers. ``` -------------------------------- ### Command Handling Inside transcode_main Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/embencoder.md Behavior of the transcoder for each input command type during transcoding. ```APIDOC ## Command Handling Inside `transcode_main` | Input command | Behavior | |---------------|----------| | `NO_COMMAND` | Skipped. | | `STITCH` / `SEW_TO` / `NEEDLE_AT` | When currently trimmed: jump within stitch range, stitch, tie-on. When jumping: `needle_to`. Otherwise `stitch_with_contingency` (`SEW_TO` → sew-to; `NEEDLE_AT` → needle-to). | | `STITCH_BREAK` | Sets the jumping state; following jumps reallocated. | | `FRAME_EJECT` | Tie off/trim, jump to position, stop. | | `SEQUENCE_BREAK` | Tie off and trim if needed. | | `COLOR_BREAK` | `color_break()` — no-op before any stitch or when no stitching remains. | | `TIE_OFF` / `TIE_ON` | Executes the respective contingency. | | `TRIM` | Tie off/trim if needed. | | `JUMP` | `jump_to` when not already jumping. | | `SEQUIN_MODE` / `SEQUIN_EJECT` | Mode toggle / sequin emission with sequin contingency. | | `COLOR_CHANGE` / `NEEDLE_SET` | `tie_off_trim_color_change()` — tie off, optional explicit trim, advance change sequence. | | `STOP` | `stop_here()`. | | `SLOW` / `FAST` | Emitted only when `writes_speeds`. | | `END` | `end_here()` and stop processing. | | `OPTION_MAX_STITCH_LENGTH` / `OPTION_MAX_JUMP_LENGTH` | Overrides `max_stitch` / `max_jump` from the command x operand. | | `OPTION_EXPLICIT_TRIM` / `OPTION_IMPLICIT_TRIM` | Toggle `explicit_trim`. | | `CONTINGENCY_*` (tie/stitch/sequin) | Sets the corresponding live contingency. | | `MATRIX_*` | Updates the working `EmbMatrix` (see [embmatrix.md](embmatrix.md)). | ``` -------------------------------- ### WriteHelper Functions Source: https://github.com/embroidepy/pyembroidery/blob/main/_autodocs/api-reference/io-helpers.md Functions for writing binary data to a stream, including integers of various sizes and endianness, floats, and strings. ```APIDOC ## write_int_array_8(stream, int_array) ### Description Writes each element of `int_array` as a single byte to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **int_array** (iterable of int) - Required - Array of integers to write. ### Returns None ## write_int_8(stream, value) ### Description Writes a single byte (`value & 0xFF`) to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_16le(stream, value) ### Description Writes a 2-byte little-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_16be(stream, value) ### Description Writes a 2-byte big-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_24le(stream, value) ### Description Writes a 3-byte little-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_24be(stream, value) ### Description Writes a 3-byte big-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_32le(stream, value) ### Description Writes a 4-byte little-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_int_32be(stream, value) ### Description Writes a 4-byte big-endian integer to the stream. ### Parameters - **stream** (file-like object) - Required - Object with `.write(bytes)` method. - **value** (int) - Required - Value to write. ### Returns None ## write_float_32le(stream, value) ### Description Writes an IEEE-754 single-precision float in little-endian order using `struct.pack("_count`, e.g. `stitch_count`), `stitch_total`, `thread_total`, `extents_left/top/right/bottom`, `extends_*` aliases and widths/heights. ### Method Method ### Signature `set_document_statistics(self)` ### Returns None ```