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.

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.
`s8`	1	'\0'	maybe null terminator for the string.
`16be`	2	byte_length	Production String Bytes (N0)
`UTF-16BE`	N0	"Produced by ...."	Production String

020 Location And Data

The 0x0 tags are some of the more recognizable tags as they always denote a location in the file. So I will break at them.

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	unknown string, always 00 (N1)
`UTF-16BE`	N1	""	Rumor has it this is a string.

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

Thread Count and Unknown

Type	Bytes	Value	Description
`u8`	1	\x00	unknown
`u8`	1	count_threads	the number of expected colorblocks
`u8`	1	\x0C	Unknown
`u8`	1	\x00	Unknown
`u8`	1	\x01	Unknown

030 Location And Hoop.

Type	Bytes	Value	Description
`s8`	3	\x00\x03\x00	Tag indicates the following is a location.
`32be`	2	Bytes_to_EOF	bytes the the end of the file.
`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	unknown string, always 00 (N0)
`UTF-16BE`	N0	""	Rumor has it this is a string.
`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

Color Blocks

Each vp3 stitchblock contains:

Description

Type	Description
`u16be`	Color Blocks Expected (N)
Color_Block	N Color Blocks

Color Block

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

Note sources claim the intro is table length and that some of the information is part of a multi-color table.

Type	Bytes	Value	Description
`s8`	1	\x01	Unknown, might be table size.
`s8`	1	\x00	Unknown, maybe higher level bits for color?
`u24be`	3	RRGGBB	Thread Opaque Color.
`s8`	1	\x00	Unknown
`s8`	1	\x00	Unknown
`s8`	1	\x00	Unknown
`s8`	1	\x05	Unknown
`s8`	1	\x28	Unknown
`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.

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.

Also See

• https://community.kde.org/Projects/Liberty/File_Formats/Viking_Pfaff
• http://www.jasonweiler.com/VP3FileFormatInfo.html
• https://github.com/Embroidermodder/Embroidermodder/blob/master/libembroidery/format-vp3.c