Embroidery format VP3
VP3 format is a Pfaff format. Unlike most other embroidery formats. It's divided into stitchblocks. Conceptually it's typical to think of embroidery rather than the set of low level commands which control the machine but as sets of unbroken stitches in a particular color. While this is quite common at the level of embroidery software, most formats typically consist of large dumps of direct embroidery commands with some various cruft for the machines in question.
Hierarchy
Within VP3 there are several places where what appear to tags and locations. For example 010 is just before the stitch block and points to the end of the stitches excluding a zero. Outside of that, there's a 050 tag that also points to the end of the stitches, but outside of the trailing \0. There are two sections that appear to point to end of file. 020 points to the end of file and 030 points to end of current design. There is almost always just one design.
A PES2Card utility change-log includes some interesting changes like "Corrected positioning for VP3 multi hoop designs", and "Corrected out of bounds bitmap for positioned vp3 files" -- This document contains no documentation on multi-hoop or any bitmaps linked to or contained within the files. However, as with a lot of embroidery, everything tends to write out the bare minimum and reads the bare minimum.
- Files
- File Data
- Design (Can be multiples)
- ColorBlock (Can be multiples)
- StitchBlock
- Additonal ColorBlocks*
- ColorBlock (Can be multiples)
- Addition Designs*
Few files have multiple designs. Most have multiple color blocks.
Header
VP3 consists of: a magic code, some hoop and design information, a number for the number of stitch blocks and stitch blocks.
| Type | Bytes | Value | Description |
|---|---|---|---|
| `string` | 5 | %vsm% | Magic String. ( vsmsoftware produced the format ) |
| `s8` | 1 | '\0' | maybe null terminator for the string. |
| `16be` | 2 | byte_length | Production String Bytes (N0) |
| `UTF-16BE` | N0 | "Produced by ...." | Production String |
File Data 020
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 3 | \x00\x02\x00 | Tag indicates the following is a location. |
| `32be` | 2 | Bytes_To_EOF | bytes the the end of the file. |
| `16be` | 2 | byte_length | Notes String Length, 00 for blank (N1) |
| `UTF-16BE` | N1 | "" | Settings and Notes String. Usually blank. |
Note, at the file level the notes data is usually the sum of all the other designs data text. The settings section data is prefixed "Settings:"
Extends Section
VP3 like most embroidery is y-flipped from common programming languages. Most models put the origin point in the upper-left point programming in quadrant III whereas embroidery is almost always Quadrant I with the origin point in the lower-left. Consequently most overt numbers within embroidery have to be y-flipped.
VP3 however stores all position information as multiplied by 100 as a conversion between the standard units of Embroidery 1/10th mm. This actually gives the units therefore in 1*10^-6 and are micron or (micrometers or micrometres).
| Type | Bytes | Description |
|---|---|---|
| `s16be` | 2 | Right * 100 |
| `s16be` | 2 | -Top * 100 |
| `s16be` | 2 | Left * 100 |
| `s16be` | 2 | -Bottom * 100 |
File Count Information
| Type | Bytes | Value | Description |
|---|---|---|---|
| `u8` | 1 | \x00 | unknown |
| `u8` | 1 | count_threads | the number of expected total color blocks, in total |
| `u8` | 1 | \x0C | Unknown |
| `u8` | 1 | \x00 | Unknown |
| `u8` | 1 | count_designs | the expected number of designs in total, usually 1 |
Design Block 030
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 3 | \x00\x03\x00 | Tag indicates the following is a location. |
| `32be` | 2 | bytes to end of design | bytes the end of current design (EOF if 1 design) |
| `s32be` | 4 | center_x | Design center. In microns. max_x - half_width * 100 |
| `s32be` | 4 | -center_y | Design center. In microns. max_y - half_height * -100 |
| `u8` | 1 | \x00 | Unknown |
| `u8` | 1 | \x00 | Unknown |
| `u8` | 1 | \x00 | Unknown |
| `s32be` | 4 | -half_width | -half_width, If center_x were made zero, this is the extends. |
| `s32be` | 4 | half_width | +half_width |
| `s32be` | 4 | -half_height | -half_height |
| `s32be` | 4 | half_height | +half_height |
| `16be` | 2 | byte_length | Notes String Length, 00 for blank (N1) |
| `UTF-16BE` | N1 | "" | Settings and Notes String. For this design in particular. |
| `u8` | 1 | \x64 | 'd' maybe "dd", maybe 25700 (the 00 in dec end makes that seem like a position) |
| `u8` | 1 | \x64 | see above |
| `s32be` | 4 | 4096 | Unknown, b'\x00\x00\x10\x00' |
| `s32be` | 4 | 0 | Unknown, b'\x00\x00\x00\x00' |
| `s32be` | 4 | 0 | Unknown, b'\x00\x00\x00\x00' |
| `s32be` | 4 | 4096 | Unknown, b'\x00\x00\x10\x00' |
| `string` | 4 | "xxPP" | Magic String? |
| `u8` | 1 | \x01 | Unknown |
| `u8` | 1 | \x00 | Unknown |
| `16be` | 2 | byte_length | Production String Bytes (N1) |
| `UTF-16BE` | N1 | "Produced by ...." | Production String |
| `u16be` | 2 | color_blocks_in_design_block | Color blocks in this design block |
Color Blocks
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 3 | \x00\x05\x00 | Tag indicates the following is a location. |
| `32be` | 2 | Bytes_to_next_block | Distance to the next block. +Seek on this location takes you to the next 050 |
| `s32be` | 4 | start_position_from_center_x | In microns, initial position relative to center_x |
| `s32be` | 4 | start_position_from_center_y | In microns, initial position relative to center_y |
| vp3_thread | x | thread_data | Thread for this color block |
| `s32be` | 4 | position_shift_in_block_x | In microns, first stitch to last stitch difference |
| `s32be` | 4 | position_shift_in_block_y | In microns, first stitch to last stitch difference |
| stitch_data | x | stitch_data | Stitch information for this data. |
| `s8` | 1 | \x00 | End of color_block |
Keep in mind the 050 flag ends here, after the 1 byte \x00. The 010 inside the stitch data ends within that block, without the 0. Some explanations miss this point.
VP3 Thread
In most typical use case of 1 color:
- 01 00 00 RR GG BB 00 00 00 05 28
- This reads: 1 thread, standard integration, RRGGBB, zero parts, for zero length, Rayon 40 weight.
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 1 | colors_in_thread | Color Entries. (typically this is 1) |
| `s8` | 1 | \x00 | Flag between method of color mixing. 0 == hard transition, 1 gradient. |
| `s8` | 6 * colors_in_thread | thread table entries | Color Elements |
| `s8` | 1 | \x01 | \x0A | Material 05 is Rayon, 0A is Silk, 04 Cotton, 06 Polyester, 03 Metallic Holographic, ect |
| `s8` | 1 | 40, 30 | This is thread weight. 40 weight is standard. So \0x28 is most common. |
| `u16be` | 2 | string_length (N0) | Length of Catalog String |
| `UTF-8` | N0 | Catalog String | Catalog Number of Thread Described. |
| `u16be` | 2 | string_length (N1) | Length of Description String |
| `UTF-8` | N1 | Description String | Description of Thread Described. (Eg. Meadow Red) |
| `u16be` | 2 | string_length (N2) | Length of Brand String |
| `UTF-8` | N2 | Brand String | Brand of Thread Described. |
| Type | Bytes | Value | Description |
|---|---|---|---|
| `u24be` | 3 | RRGGBB | Thread Color |
| `s8` | 1 | \x0A | Color Parts (larger values mean shorter thread), rare to see not \x0A |
| `s16be` | 1 | \x00 | Length for this color within the thread. |
Stitch Data
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 3 | \x00\x01\x00 | Tag indicates the following is a location. |
| `32be` | 2 | bytes_to_end_of_stitch_data | Distance to the end of stitches. Usually there's only a trailing 0 left in the color block, then the next color_block starts. |
| `s8` | 3 | \x0A\xF6\x00 | Stitch start. |
| `s8` | N | Encoded stitches | Stitches |
Stitch Encode
| Type | Bytes | Value | Description |
|---|---|---|---|
| `s8` | 2 | 0x80, 0x01 | Enable Long Form. |
| `s8` | 2 | 0x80, 0x02 | Disable Long Form. |
| `s8` | 2 | 0x80, 0x03 | End. (Usually only found in final stitch block) |
| `s8` | 2 | x, y | Stitch dx, dy |
| `s16be` | 4 | LONG FORM: x, y | Uses 2 byte encoding for x and y. If 255 or greater, assume this is a trim. |
Jumps usually take the form \x80,\x01, x_highbits, x_lowbits, y_highbits, y_lowbits, \x80, \x02, however since there seems to be no way to force a trim (maybe jump away from the stitch location then jump back), threads less than 255 often get sewn.