libembroidery is a low-level library for reading, writing, and altering digital embroidery files in C.
libembroidery is the underlying library that is used by Embroidermodder 2 and is developed by The Embroidermodder Team. It handles over 45 different embroidery specific formats as well as several non-embroidery specific vector formats.
It also includes a CLI called embroider
that allows for better automation of changes to embroidery files and will be more up-to date than the Embroidermodder 2 GUI.
If you want to find a simple fix to contribute see the Development section of the manual.
https://embroidermodder.org
Copyright (c) 2013-2022 The EmbroiderModder Team
Libembroidery is distributed under the permissive zlib licence, see the LICENCE file. Libembroidery consists of roughly 16k source lines of code in C: embroidery.c
, embroidery.h
, thread-color.c
and formats.c
. There are 3 supporting files: the LICENCE
, this README
and a build file (CMakeLists.txt
). The licence covers these 7 files.
The Embroidermodder 2 project is a collection of small software utilities for manipulating, converting and creating embroidery files in all major embroidery machine formats. The program Embroidermodder 2 itself is a larger graphical user interface (GUI) which is at the heart of the project.
This manual, the website (embroidermodder.org
), mobile embroidery format viewers and tools (iMobileViewer
, MobileViewer
), the core library of functions (libembroidery
) and CLI (embroider
) are all tools to make the standard user experience of working with an embroidery machine better without expensive software which is locked to specific manufacturers and formats. But ultimately we hope that the core Embroidermodder 2 is a practical, ever-present tool in larger workshops, small cottage industry workshops and personal hobbyist’s bedrooms.
Embroidermodder 2 is licensed under the zlib license and we aim to keep all of our tools open source and free of charge. If you would like to support the project check out our Open Collective group. If you would like to help, please join us on GitHub. This document is written as developer training as well helping new users (see the last sections) so this is the place to learn how to start changing the code.
The Embroidermodder Team is the collection of people who’ve submitted patches, artwork and documentation to our three projects. The team was established by Jonathan Greig and Josh Varga. For a full list of members please see the Embroidermodder github page where it is actively maintained.
libembroidery and EmbroiderModder 2 use CMake builds so if you are building the project to use as a library we recommend you run:
git clone https://github.com/Embroidermodder/libembroidery
cd libembroidery
cmake .
cmake --build .
cmake --install .
This builds both the static and shared versions of the library as well as the command line program embroider
.
If you wish to help with development, run this debug script and send us the error log. Note: this is maintained outside of the repository because it gives us a oneliner for new systems with a stable URL:
curl https://embroidermodder.org/libembroidery_debugger.sh | sh
While we will attempt to maintain good results from this script as part of normal development it should be the first point of failure on any system we haven’t tested or format we understand less.
For basic use, we recommend you build as above, then run without arguments:
$ embroider
which will print out this advice on how to use these tools without digging straight into the rest of this manual.
EMBROIDER
A command line program for machine embroidery.
Copyright 2013-2021 The Embroidermodder Team
Licensed under the terms of the zlib license.
https://github.com/Embroidermodder/libembroidery
https://embroidermodder.org
Usage: embroider [OPTIONS] fileToRead...
Conversion:
-t, -to Convert all files given to the format specified
by the arguments to the flag, for example:
$ embroider -t dst input.pes
would convert \"input.pes\" to \"input.dst\"
in the same directory the program runs in.
The accepted input formats are (TO BE DETERMINED).
The accepted output formats are (TO BE DETERMINED).
Output:
-h, -help Print this message.
-f, -format Print help on the formats that
embroider can deal with.
-q, -quiet Only print fatal errors.
-V, -verbose Print everything that has reporting.
-v, -version Print the version.
Graphics:
-c, -circle Add a circle defined by the arguments
given to the current pattern.
-e, -ellipse Add a circle defined by the arguments
given to the current pattern.
-l, -line Add a line defined by the arguments
given to the current pattern.
-P, -polyline Add a polyline.
-p, -polygon Add a polygon.
-s, -satin Fill the current geometry with satin
stitches according
to the defined algorithm.
-S, -stitch Add a stitch defined by the arguments
given to the current pattern.
Quality Assurance:
-test Run the test suite.
For each of the flags described here we will go into greater detail in this manual.
The flag --test
runs the tests that take the least time and have the most utility. If you’re submitting a patch for review, please run:
$ embroider --test | tail -n 1
You’ll be presented with an overall PASS or FAIL for your build, if your build fails you can try and trace the error with:
$ valgrind embroider --verbose --test
or
$ gdb --args embroider --verbose --test
depending on your preferred debugging approach. Passing this test will be required for us to accept your patch.
The flag --full-test-suite
runs all the tests that have been written. Since this results in a lot of output the details are both to stdout and to a text file called test_matrix.txt
.
Patches that strictly improve the results in the test_matrix.txt
over the current version will likely be accepted and it’ll be a good place to go digging for contributions. (Note: strictly improve means that the testing result for each test is as good a result, if not better. Sacrificing one critera for another would require some design work before we would consider it.)
There are two forms of render that will be produced.
We have an EmbImage struct to store the raster format.
$ embroider test01.csv --render
currently creates a blank image. Previously the Hilbert curve test managed to create a correctly rendered version.
We need a current embroider
command line program download, so people can update without building.
The chart of successful from-to conversions (previously a separate issue) is something that should appear in the README.
One application I’d like to leave a reminder here for is automating embroidery for blind and partially sighted people.
There are many limitations to making braille (cost, poor support, lack of widespread adoption in the sighted world) and as such there is a strong DIY culture around it.
There are blind internet users who can also run terminal applications using a refreshable braille display, so in theory we could support an application like this for them:
$ embroider --braille "Hello, world!" hello.dst
which would produce braille that would read “Hello, world!” as an embroidery design.
Another option is tactile fills that use the same fill algorithms but are designed better to facilitate tactile art.
I think the way forward on this is to call up the RNIB business advice line and ask for assistance once we have a working model. That way they can get us in contact with experts to review how legible the output is and usable the software is for the intended audience.
This is less important than getting better machine support but given the high social impact I think it should be a priority.
A basic set of guidelines to use when submitting code.
For functions: please put each brace on a new line.
void function_definition(int argument)
{
}
For control statements: please put the first brace on the same line.
if (condition) {
}
Do not use ternary operator (?:) in place of if/else.
Do not repeat a variable name that already occurs in an outer scope.
When writing code, sometimes there are items that we know can be improved, incomplete or need special clarification. In these cases, use the types of comments shown below. They are pretty standard and are highlighted by many editors to make reviewing code easier. We also use shell scripts to parse the code to find all of these occurrences so someone wanting to go on a bug hunt will be able to easily see which areas of the code need more love.
libembroidery is written in C and adheres to C89 standards. This means that any C99 or C++ comments will show up as errors when compiling with gcc.
The table of read/write format support levels uses the status levels described here:
Status | Description |
---|---|
None (0) | Either the format produces no output, reporting an error. Or it produces a Tajima dst file as an alternative. |
Poor (1) | A file somewhat similar to our examples is produced. We don’t know how well it runs on machines in practice as we don’t have any user reports or personal tests. |
Basic (2) | Simple files in this format run well on machines that use this format. |
Standard (3) | Files with non-standard features work on machines and we have good documentation on the format. |
Reliable (4) | All known features don’t cause crashes. Almost all work as expected. |
Good (5) | All known features of the format work on machines that use this format. Translations from and to this format preserve all features present in both. |
So all formats can, in principle, have good read and good write support, because it’s defined in relation to files that we have described the formats for.
Status | Description |
---|---|
None (0) | No tests have been written to test the specifics of the format. |
Basic (1) | Stitch Lists and/or colors have read/write tests. |
Thorough (2) | All features of that format has at least one test. |
Fuzz (2) | Can test the format for uses of features that we haven’t thought of by feeding in nonsense that is designed to push possibly dangerous weaknesses to reveal themselves. |
Complete (3) | Both thorough and fuzz testing is covered. |
So all formats can, in principle, have complete testing support, because it’s defined in relation to files that we have described the formats for.
Status | Description |
---|---|
None (0) | We haven’t researched this beyond finding example files. |
Basic (1) | We have a rough sketch of the size and contents of the header if there is one. We know the basic stitch encoding (if there is one), but not necessarily all stitch features. |
Standard (2) | We know some good sources and/or have tested all the features that appear to exist. They mostly work the way we have described. |
Good (3) | All features that were described somewhere have been covered here or we have thoroughly tested our ideas against other softwares and hardwares and they work as expected. |
Complete (4) | There is a known official description and our description covers all the same features. |
Not all formats can have complete documentation because it’s based on what information is publically available. So the total score is reported in the table below based on what level we think is available.
For a total of 0% coverage.
The Toyota 100 format is a stitch-only format that uses an external color file.
The stitch encoding is in 4 byte chunks.
The Toyota 10o format is a stitch-only format that uses an external color file.
The stitch encoding is in 3 byte chunks.
We don’t know much about this format. TODO: Find a source.
We don’t know much about this format. TODO: Find a source.
The Bits and Volts bro format is a stitch-only format that uses an external color file.
The header is 256 bytes. There’s a series of unknown variables in the header.
The stitch list uses a variable length encoding which is 2 bytes for any stitch
The Melco cnd format is a stitch-only format.
We don’t know much about this format. TODO: Find a source.
An external color file format for formats that do not record their own colors.
It is a human-readable format that has a header that is a single line containing only the number of threads in decimal followed by the windows line break ‘’.
Then the rest of the file is a comma seperated value list of all threads with 4 values per line: the index of the thread then the red, green and blue channels of the color in that order.
If we had a pattern called “example” with four colors: black, red, magenta and cyan in that order then the file is (with the white space written out):
example.col
4\r\n
0,0,0,0\r\n
1,255,0,0\r\n
2,0,255,0\r\n
3,0,0,255\r\n
Stitch Only Format
Comma Seperated Values files aren’t a universal system, here we aim to offer a broad support.
Control Symbol | Type | |
---|---|---|
# |
COMMENT | |
> |
VARIABLE | To store records of a pattern’s width, height etc. This means that data stored in the header of say a .dst file is preserved. |
$ |
THREAD | |
* |
STITCH | |
* |
JUMP | |
* |
COLOR | To change a color: used for trim as well |
* |
END | To end a pattern. |
* |
UNKNOWN | For any feature that we can’t identify. |
Stitch Only Format
Stitch Only Format
.DST (Tajima) embroidery file read/write routines Format comments are thanks to [email protected] who’s notes appeared at under Tajima Format.
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 value trailed by a carriage return.
C memory | Description |
---|---|
char LA[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 spaces (0x20). |
char ST[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. |
char CO[3+1]; |
Next, is CO or colors, a 3 digit number padded by leading zeros. This is the number of color change records in the file. |
char POSX[5+1]; |
Next is +X or the positive X extent in centimeters, a 5 digit non-decimal number padded by leading zeros. |
char NEGX[5+1]; |
Following is the -X or the negative X extent in millimeters, a 5 digit non-decimal number padded by leading zeros. |
char POSY[5+1]; |
Again, the +Y extents. |
char NEGY[5+1]; |
Again, the -Y extents. |
char AX[6+1]; char AY[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). |
char MX[6+1]; char MY[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. |
char PD[9+1]; |
PD is also storing some information for multi-volume design. |
Uses 3 byte per stitch encoding with the format as follows:
The 3 byte encoding for the dxf format.
Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
---|---|---|---|---|---|---|---|---|
Byte 0 | y+1 | y-1 | y+9 | y-9 | x-9 | x+9 | x-1 | x+1 |
Byte 1 | y+3 | y-3 | y+27 | y-27 | x-27 | x+27 | x-3 | x+3 |
Byte 2 | jump | color change | y+81 | y-81 | x-81 | x+81 | set | set |
T01 and Tap appear to use Tajima Ternary.
Where the stitch type is determined as:
00000011 0x03
10000011 0x83
11000011 0xC3
11110011 0xF3
Inclusive or’ed with the last byte.
Note that:
1+3+9+27+81=121
where the unit length is 0.1mm so 12.1mm.The ZSK USA dsz format is stitch-only.
Graphics format.
Stitch Only Format
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Smoothie G-Code Embroidery Format (.fxy)?
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
Stitch Only Format.
The format uses a signed 3 byte-length number type.
See the description here (5) for the overview of the format.
For an example of the format see (11).
The Pfaff pcm format is stitch-only.
The Pfaff pcq format is stitch-only.
The Pfaff pcs format is stitch-only.
The Brother pec format is stitch-only.
The Brother pel format is stitch-only.
The Brother pem format is stitch-only.
The Brother pes format is stitch-only.
struct PEShdr
{
char PESId[8];
DWORD PECOffset;
};
The Brother phb format is stitch-only.
The Brother phc format is stitch-only.
The AutoCAD plt format is stitch-only.
The RGB format is a color-only format to act as an external color file for other formats.
The Janome sew format is stitch-only.
The Husqvarna Viking shv format is stitch-only.
The Sunstar sst format is stitch-only.
The Data Stitch stx format is stitch-only.
The scalable vector graphics (SVG) format is a graphics format maintained by …
The Pfaff t01 format is stitch-only.
The Pfaff t09 format is stitch-only.
The Happy tap format is stitch-only.
The ThreadWorks thr format is stitch-only.
The txt format is stitch-only and isn’t associated with a specific company.
The Barudan u00 format is stitch-only.
The Barudan u01 format is stitch-only.
The Pfaff vip format is stitch-only.
The Pfaff vp3 format is stitch-only.
The Singer xxx format is stitch-only.
The ZSK USA zsk format is stitch-only.
The library is designed to support embedded environments, so it can be used in CNC applications.
We recommend using an Arduino Mega 2560 or another board with equal or greater specs. That being said, we have had success using an Arduino Uno R3 but this will likely require further optimization and other improvements to ensure continued compatibility with the Uno. See below for more information.
There are two main concerns here: Flash Storage & SRAM.
libembroidery continually outgrows the 32KB of Flash storage on the Arduino Uno and every time this occurs, a decision has to be made as to what capabilities should be included or omitted. While reading files is the main focus on arduino, writing files may also play a bigger role in the future. Long term, it would be most practical to handle the inclusion or omission of any feature via a single configuration header file that the user can modify to suit their needs.
SRAM is in extremely limited supply and it will deplete quickly so any dynamic allocation should occur early during the setup phase of the sketch and sparingly or not at all later in the sketch. To help minimize SRAM consumption on Arduino and ensure libembroidery can be used in any way the sketch creator desires, it is required that any sketch using libembroidery must implement event handlers. See the ino-event source and header files for more information.
There is also an excellent article by Bill Earl on the Adafruit Learning System which covers these topics in more depth: .
Since a stitch takes 3 bytes of storage and many patterns use more than 10k stitches, we can’t assume that the pattern will fit in memory. Therefore we will need to buffer the current pattern on and off storage in small chunks. By the same reasoning, we can’t load all of one struct beore looping so we will need functions similar to binaryReadInt16 for each struct.
This means the EmbArray approach won’t work since we need to load each element and dynamic memory management is unnecessary because the arrays lie in storage.
TODO: Replace EmbArray functions with embPattern load functions.
All thread tables and large text blocks are too big to compile directly into the source code. Instead we can package the library with a data packet that is compiled from an assembly program in raw format so the specific padding can be controlled.
In the user section above we will make it clear that this file needs to be loaded on the pattern USB/SD card or the program won’t function.
TODO: Start file with a list of offsets to data with a corresponding table to load into with macro constants for each label needed.
It will be simpler to make one file per EmbArray so we keep an EmbFile* and a length, so no malloc call is necessary. So there needs to be a consistent tmpfile naming scheme.
TODO: For each pattern generate a random string of hexadecimal and append it to the filenames like . Need to check for a file which indicates that this string has been used already.
Due to historical reasons and to remain compatible with the Arduino 1.0 IDE, this folder must be called ``utility’’. Refer to the arduino build process for more info: https://arduino.github.io/arduino-cli/0.19/sketch-build-process/
libembroidery relies on the Arduino SD library for reading files. See the ino-file source and header files for more information.
One problem to the problem of supporting both systems with abundant memory (such as a 2010s or later desktop) and with scarce memory (such as embedded systems) is that they don’t share the same assembly language. To deal with this: there will be two equivalent software which are hand engineered to be similar but one will be in C and the other in the assembly dialects we support.
All assembly will be intended for embedded systems only, since a slightly smaller set of features will be supported. However, we will write a x86
version since that can be tested.
That way the work that has been done to simplify the C code can be applied to the assembly versions.
To build the documentation run make
. This should run no problem on a normal Unix-like environment assuming pandoc is available.
This way: 1. We write one set of documents for all projects. 2. The website can be simple and static, supporting machines that don’t run javascript. 3. We control the styling of each version independently of our editing (Markdown) version 4. The printer-friendly documentation can have nicely rendered fonts and well placed figures.
Bindings for libembroidery are maintained for the languages we use internally in the project, for other languages we consider that the responsibility of other teams using the library.
So libembroidery is going to be supported on:
* C (by default)
* C++ (also by default)
* Java (for the Android application MobileViewer)
* Swift (for the iOS application iMobileViewer)
For C# we recommend directly calling the function directly using the DllImport feature:
[DllImport("libembroidery.so", EntryPoint="readCsv")]
see this StackOverflow discussion for help.
For Python you can do the same using ctypes.
The thread lists that aren’t preprogrammed into formats but are indexed in the data file for the purpose of conversion or fitting to images/graphics.
A right-handed coordinate system is one where up is positive and right is positive. Left-handed is up is positive, left is positive. Screens often use down is positive, right is positive, including the OpenGL standard so when switching between graphics formats and stitch formats we need to use a vertical flip (embPattern_flip
).
0x20
is the space symbol, so when padding either 0 or space is preferred and in the case of space use the literal ’ ’.
libembroidery
.embroider
targets 32-bit and 64 bit systems that comply to POSIX or current Windows/MacOS standards. Practically, this means we only call C99 standard library functions.char header[]
variables.A currently unsolved problem in development that warrants further research is the scenario where a user wants to feed embroider an image that can then be .
We currently need help with:
--full-test-suite
with no segfaults and at least a clear error message (for example “not implemented yet”)..csv
to a late .pes
version. What should the default be when the data doesn’t clarify?Beyond this the development targets are categories sorted into:
Adjectives apply to every following noun so
embroider --satin 0.3,0.6 --thickness 2 --circle 10,20,5 \
--border 3 --disc 30,40,10 --arc 30,50,10,60 output.pes
Creates:
in that order then writes them to the output file output.pes
.
build.bash
.sloccount
on extern/
and .
(and ) so we know the current scale of the project, aim to get this number low. Report the total as part of the documentation.libembroidery
with a Java wrapper.libembroidery
with a Swift wrapper.libembroidery
.libembrodiery_data_internal.s
.embroidery.h
all systems and the function list “c code only”. That way we can share some development between assembly and C versions.