VP3

Status

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 behavior

Satin Studio preserves VP3 design, color-block, and stitch-block boundaries on import. Export carries the selected machine, hoop placement, thread blocks, and supported previews into the structured file.

Versions and variants

A VP3 file can contain several designs and color blocks. Satin Studio reports multi-design and multi-hoop placement explicitly rather than flattening them into one unexplained stitch stream.

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
}

Compatibility evidence

Compatibility checks cover signatures, metadata, command boundaries, malformed records, and files from the machines and software named above. Unsupported variants stop with a specific report instead of being silently rewritten.