VP3

Status

Field	Value
Extension(s)	.vp3
Common ecosystem	Pfaff / Husqvarna Viking
Format family	Structured machine-specific file
Satin Studio status	Planned
Open / import	No
Export	No
Confidence	Medium-high for structure; variants need tests.

What it is

VP3 is a newer Pfaff / Husqvarna Viking / VSM-family format. It is structured into file, design, color-block, and stitch-block areas rather than being one flat command stream.

Satin Studio direction

Satin Studio expects VP3 support after simpler stitch-stream formats establish the importer/exporter reporting architecture.

Versions and variants

VP3 can contain multiple designs and multiple color blocks, although many files contain one design with several color blocks. Multi-hoop positioning and bitmap/preview behavior need separate validation.

File identification notes

Known structural clues:

• Magic text begins with %vsm%.
• Numeric fields are commonly big-endian.
• Text strings may be UTF-16BE in file/design notes and production strings.
• Tagged sections include file-level 020, design-level 030, color-block 050, and stitch-data 010 areas.
• Position and extent values are stored in micrometers; Y values need embroidery-coordinate handling rather than screen-coordinate assumptions.

Color blocks carry start position, thread metadata, block movement shift, and stitch data. Thread metadata can include RGB, material, thread weight, catalog number, description, and brand.

Stitch data uses short dx, dy bytes plus 0x80 control pairs:

• 0x80 0x01: enable long form.
• 0x80 0x02: disable long form.
• 0x80 0x03: trim or block-end marker, depending on context and reader behavior.
• Long form stores signed 16-bit big-endian x, y deltas.

Observed structure notes

• Observed VP3 files begin with %vsm%\0, followed by length-prefixed producer/comment strings, positioning metadata, and color-block data.
• Observed top-level coordinates are stored as big-endian signed 32-bit values scaled by 1/100 in common readers. Thread metadata includes 24-bit RGB, material/part counts, type, weight, catalog number, description, and brand.
• Observed color blocks contain a three-byte lead marker, a big-endian block distance/length, start position, thread metadata, a 15-byte gap, a three-byte stitch-data lead marker, and then stitch bytes.
• Observed stitch bytes are signed dx, dy pairs. 0x80 0x01 switches to a long movement form using signed 16-bit big-endian X/Y deltas; 0x80 0x02 is a long-form terminator/no-op in observed readers; 0x80 0x03 is interpreted as trim or block-end context.
• Observed writers use block tags 00 02 00 for the file block, 00 03 00 for the design block, 00 05 00 for each color block, and 00 01 00 for each stitch block.
• Observed writers reserve four-byte big-endian block-distance placeholders after block tags and patch them after writing the block.
• Observed writers encode thread metadata as single-color/no-transition, 24-bit RGB, material/weight bytes, and three length-prefixed UTF-8 strings for catalog, description, and brand.

Structure sketch

VP3 is sectioned, big-endian, and color-block oriented:

struct Vp3File<'a> {
    magic: [u8; 6],                     // observed b"%vsm%\0"
    header_strings_and_metadata: &'a [u8],
    center_x_scaled: i32,               // big-endian, observed scale / 100
    center_y_scaled: i32,
    color_count: u16,
    color_blocks: &'a [Vp3ColorBlock<'a>],
}

struct Vp3ColorBlock<'a> {
    lead_marker: [u8; 3],               // observed 00 05 00 in common files
    distance_to_next_050: u32,
    start_x_scaled: i32,
    start_y_scaled: i32,
    thread: Vp3Thread<'a>,
    pre_stitch_gap: [u8; 15],
    stitch_marker: [u8; 3],             // observed 0A F6 00 in common files
    stitch_data: &'a [Vp3StitchRecord],
}

struct Vp3Thread<'a> {
    color_count: u8,
    transition: u8,
    rgb_and_parts: &'a [u8],
    thread_type: u8,
    weight: u8,
    catalog_number: &'a str,
    description: &'a str,
    brand: &'a str,
}

enum Vp3StitchRecord {
    Short { dx: i8, dy: i8 },
    Long { dx: i16, dy: i16 },           // introduced by 0x80 0x01, signed 16-bit BE x/y
    LongTerminator,                     // 0x80 0x02 in observed streams
    TrimOrBlockEnd,                     // 0x80 0x03
}

What we still need

Signature edge cases, multi-design/multi-hoop examples, thread metadata variants, coordinate-unit tests, and required machine metadata.