Embroidery format DST
DST is a very commonly-used proprietary embroidery format originally from Tajima. The files contain only stitch commands for the embroidery machines. And a metadata information of label. It is not very nicely designed but because of its age (it came about from punchcard days) but the general ubiquity means it is as close to a standard as exists within embroidery. Some format changes are made such as to not affect the reading by embroidery machines and yet have the ability to be interpreted different on newer machines with newer functionality.
- DST files have a maximum stitch/jump length of 121.
- DST files contain metadata element: label
- DST files do not contain colors.
- DST files do not contain vectors.
- DST files do not contain thumbnails.
Each file consists of two parts: a header, and a body.
Header
DST headers are always 512 bytes long. These headers only actually use 125 bytes of data that is actually expected. When reading a dst file these can be safely entirely skipped as only the label would contain any information that might not exist otherwise or be more safely recalculated from the file itself. While this document does include references to other bits of metadata that might be critical like thread colors or author, those are so rare as to be ignorable.
The best explanation of the header information is from the Embroidermodder source code:
"The header seems to contain information about the design. Seems to be ASCII text delimited by 0x0D (carriage returns). This must be in the file for most new software or hardware to consider it a good file! This is much more important than I originally believed. The header is 125 bytes in length and padded out by 0x20 to 512 bytes total. All entries in the header seem to be 2 ASCII characters followed by a colon, then it's (sic) value trailed by a carriage return."
| prefix | meaning | length | contents |
|---|---|---|---|
| LA | Label | 16+1 | First is the 'LA' entry, which is the design name with no path or extension information. The blank is 16 characters in total, but the name must not be longer that 8 characters and padded out with 0x20. |
| ST | Stitches | 7+1 | Next is the stitch count ST, this is a 7 digit number padded by leading zeros. This is the total stitch count including color changes, jumps, nups, and special records. |
| CO | Colors | 3+1 | CO or colors, a 3 digit number padded by leading zeros. This is the number of color change records in the file. |
| +X | +X Extends | 5+1 | Next is +X or the positive X extent in centimeters, a 5 digit non-decimal number padded by leading zeros. |
| -X | -X Extends | 5+1 | Next is -X or the negative X extent in centimeters, a 5 digit non-decimal number padded by leading zeros. |
| +Y | +Y Extends | 5+1 | Next is +Y or the positive Y extent in centimeters, a 5 digit non-decimal number padded by leading zeros. |
| -Y | -Y Extends | 5+1 | Next is -Y or the negative Y extent in centimeters, a 5 digit non-decimal number padded by leading zeros. |
| AX | Difference | 6+1 | AX and AY should express the relative coordinates of the last point from the start point in 0.1 mm. If the start and last points are the same, the coordinates are (0,0). |
| AY | Difference | 6+1 | AX and AY should express the relative coordinates of the last point from the start point in 0.1 mm. If the start and last points are the same, the coordinates are (0,0). |
| MX | Multi-Design Start | 6+1 | MX and MY should express coordinates of the last point of the previous file for a multi-volume design. A multi-volume design means a design consisted of two or more files. This was used for huge designs that can not be stored in a single paper tape roll. It is not used so much (almost never) nowadays. |
| MY | Multi-Design Start | 6+1 | MX and MY should express coordinates of the last point of the previous file for a multi-volume design. A multi-volume design means a design consisted of two or more files. This was used for huge designs that can not be stored in a single paper tape roll. It is not used so much (almost never) nowadays. |
| PD | Previous Design? | 9+1 | PD is also storing some information for multi-volume design. Modernly this is always "******" |
Do note that when writing these *are* required. Some machines do load up the first aspects of these to calculate things like percent complete for the file by counting the process stitches and using ST as the total. And may do things like using the extends to calculate whether it fits in the hoop, rather than recalculating these from reprocessing the stitches. However, AX, AY, MX, and MY are almost always set to zero and PD always to "******".
Additional headers
There are some DST files that contain some additional header information of arbitrary size:
These are exceptionally rare. It is unknown what would make files with these metadata tags. However these extensions would allow DST files to contain proper thread information simply adding on a reference for each thread color as needed. The actual used header within DSTs is 125 out of the 512 byte static size header so there is clearly 387 bytes of nothing in most files. Using these seems to be pretty easy expansion.
| prefix | meaning | length | contents |
|---|---|---|---|
| AU | Author | variable | Author information. |
| CP | Copyright | variable | Copyright information. |
| TC | Thread Color | 9,variable,variable | "#RRGGBB,Description,Catalog Number" hex color code, thread description, and catalog number comma delimited. |
Example
LA:sequin3 ST: 685 CO: 1 +X: 270 -X: 270 +Y: 224 -Y: 224 AX:+ 0 AY:+ 0 MX:+ 0 MY:+ 0 PD:******
You will notice that AX and AY is nearly always 0, MX and MY are also zero. PD is typically just six asterixis. Most of these fields are not used. However, label is almost always read and stitches is read quite often by machines to calculate how far through the design the current embroidery is. The extends might also be used to calculate whether the design will properly fit within the hoop.
Body
DST commands are always 3 bytes long. Most other embroidery formats are 2 bytes long with special commands using two additional bytes.
The earliest decoding of the stitches from DST seems to appear on http://www.achatina.de/sewing/main/TECHNICL.HTM
| BYTE | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| 1 | y+1 | y-1 | y+9 | y-9 | x-9 | x+9 | x-1 | x+1 |
| 2 | y+3 | y-3 | y+27 | y-27 | x-27 | x+27 | x-3 | x+3 |
| 3 | c0 | c1 | y+81 | y-81 | x-81 | x+81 | set | set |
Control Codes
While the author of that early decoding interpreted c0 and c1 as "jump" and "color change" it's actually a bit more complicated.
| C0 | C1 | meaning |
|---|---|---|
| 0 | 0 | Normal Stitch. |
| 1 | 0 | Jump Stitch. |
| 1 | 1 | Color Change |
| 0 | 1 | Sequin Mode |
Further an extra distinction is make with regard to Stop and Color Change this is done by setting y+81 and y-81 in a command that would normally have no relative movement. These stitches do not have DX and DY set but by setting them in ways to that cancel out, it can trigger other events without affecting other normal reading of the file. The reason for this is likely that prior to the existence of multi-needle machines it was standard to have machines with only one needle and each and every color change required stopping the machine and manually changing the thread. So originally STOP and COLOR_CHANGE were the same command. The introduction of multi-needle machines would do the colorchange without user interaction. However, this creates a practical difference if the stop was not to change the thread but to do something like apply applique.
| Command | Byte1 | Byte2 | Byte3 |
|---|---|---|---|
| Stitch +0, +0 | 0b00000000 | 0b00000000 | 0b00000011 |
| Jump +0, +0 | 0b00000000 | 0b00000000 | 0b10000011 |
| ColorChange +0, +0 | 0b00000000 | 0b00000000 | 0b11000011 |
| Stop +0, +0 | 0b00000000 | 0b00000000 | 0b11110011 |
| Sequin +0, +0 | 0b00000000 | 0b00000000 | 0b01000011 |
| Wilcom End | 0b00011010 | file has ended | file has ended |
END command
The end of an embroidery file often are seen as having an END command. In DST this is just a STOP. At least it is for programs like EO. With modern filesystems you can know that a file has ended when you reach the end of the file and do not read beyond the file size. However prior to this with punch cards there might not have been any particular way to know this easily. Wilcom output for DST files ends with 0x1A. It is unknown if this is a compatibility thing for some embroidery machine out there or why it exists or whether it should be duplicated.
As an aside: this does interestingly mean that you can detect any Wilcom DST file by filesize alone. Namely all DST files are going to have ((file_size - 512) % 3) == 0. With Wilcom this will be ((file_size - 512) % 3) == 1
TRIM command
TRIM command is assumed to exist after a set number of jump commands in a row. This is often 3 but could be as high as 5. In order to ensure the machine that a the embroidery machine trims appropriately it is conventional to insert several small fake jumps such as +2 +2, -4 -4, +2 +2 which results in going nowhere, but hits the jump limit on the machine and requires it to trim.
SEQUIN command
The Sequin command appears to turn on and off sequin mode. In that when the sequin command is issued, it thereafter interprets the JUMP command as an EJECT command for drop a sequin in this position.