Warning

IN ALPHA DEVELOPMENT: NOT READY FOR SERIOUS USE.

Warning

(UNDER MAJOR RESTRUCTURING, PLEASE WAIT FOR VERSION 2.)

Introduction¶

Basic Features¶

Move a single stitch in an existing pattern¶

In the File’ menu, click `Open…’. When the open dialog appears find and select your file by double clicking the name of the file. Alternatively, left click the file once then click the `Open button.
In the `File’ menu

Tip

For users who prefer

Convert one pattern to another format¶

In the File menu, click Open….
The
In the dropdown menu within the save dialog select the

Advanced Features¶

Other Projects¶

Planning¶

To see what’s planned open the [Projects](https://github.com/Embroidermodder/Embroidermodder/projects/1) tab which sorts all of the GitHub Issues into columns.

Donations¶

Creating software that interfaces with hardware is costly. A summary of some of the costs involved:

Developer time for 2 core developers
Computer equipment and parts
Embroidery machinery
Various electronics for kitbashing Embroiderbot
Consumable materials (thread, fabric, stabilizer, etc…)

If you have found our software useful, please consider funding further development by donating to the project on Open Collective (https://opencollective.com/embroidermodder).

Introduction¶

Embroidermodder is a free machine embroidery application. The newest version, Embroidermodder 2 can:

edit and create embroidery designs
estimate the amount of thread and machine time needed to stitch a design
convert embroidery files to a variety of formats
upscale or downscale designs
run on Windows, Mac and Linux

For more information, see our website (url{https://www.libembroidery.org})).

Embroidermodder 2 is very much a work in progress since we’re doing a ground up rewrite to an interface in Python using the GUI toolkit Tk. The reasoning for this is detailed in the issues tab.

For a more in-depth look at what we are developing read the developer notes footnote{link to dev notes section}. This discusses recent changes in a less formal way than a changelog (since this software is in development) and covers what we are about to try.

To see what we’re focussing on at the moment check this table.

Desktop¶

First you must install the dependencies which aren’t compiled into the source:

git
cmake
A C compiler (we recommend gcc or clang)

on Debian Linux/GNU use:

$ sudo apt install git clang build-essential libsdl2-dev \
 libsdl2-images-dev libsdl2-ttf-dev

If you can’t find a good fit for your system (on Windows use the section below), try compiling the included submodules with:

$ bash build_deps.sh

From here, on most sytems the command:

$ bash build.sh

will build the software. Currently this is the 2.0-alpha, which will have a build code of some kind.

Dependencies and Build¶

Plans¶

Windows Specific Advice¶

This is one of many possible ways to build the software on Windows, this section is to help people who’ve not got a build environment to start with.

Download and install MSYS2 (follow their instructions): https://www.msys2.org/
Boot Mintty from the Start menu.
Use the commands:

Mobile¶

These are currently unsupported (see iMobileViewer and Mobileviewer for iOS and Android respectively), but after the Desktop version is released we’ll work on them.

The Mobile version will share some of the UI and all of the backend, so development of the Desktop version will help us make both.

Documentation¶

The documentation is in the form of the website (included in the docs/ directory) and the printed docs in this file.

Development¶

If you wish to develop with us you can chat via the contact email on the website (https://www.libembroidery.org) or in the issues tab on the github page (https://github.com/Embroidermodder/Embroidermodder/issues). People have been polite and friendly in these conversations and I (Robin) have really enjoyed them. If we do have any arguments please note we have a [Code of Conduct](CODE_OF_CONDUCT.md) so there is a consistent policy to enforce when dealing with these arguments.

The first thing you should try is building from source using the [build advice](link to build) above. Then read some of the [development notes](link to dev notes.md) to get the general layout of the source code and what we are currently planning.

Current¶

What Robin is currently doing.

Getting the code to pass PyLint, that involves getting all source files under 1000 lines, renaming all variables to be in snake case.

Changing the seperation of code between EM and libembroidery.

Translating the Qt widget framework to Tk.

Geometry¶

The geometry is stored, processed and altered via libembroidery. See the Python specific part of the documentation for libembroidery for this. What the code in Embroidermodder does is make the GUI widgets to change and view this information graphically.

For example if we create a circle with radius 10mm and center at (20mm, 30mm) then fill it with stitches the commands would be

from libembroidery import Pattern, Circle, Vector, satin circle = Circle(Vector(20, 30), 10) pattern = Pattern() pattern.add_circle(circle, fill=satin) pattern.to_stitches()

but the user would do this through a series of GUI actions:

Create new file
Click add circle
Use the Settings dialog to alter the radius and center
Use the fill tool on circle
Select satin from the drop down menu

So EM2 does the job of bridging that gap.

There are many codeblocks for changing out the colors in one go, for example:

self.mw.update_all_view_select_box_colors( self.accept[“display_selectbox_left_color”], self.accept[“display_selectbox_left_fill”], self.accept[“display_selectbox_right_color”], self.accept[“display_selectbox_right_fill”], self.preview[“display_selectbox_alpha”])

This could be replaced with a simpler call

self.mw.update_all_view_select_box_colors( self.accept[“display_selectbox_colors”], self.preview[“display_selectbox_alpha”])

where we require that

self.accept[“display_selectbox_colors”] == {
“left_color”: “#color”, “left_fill”: “#color”, “right_color”: “#color”, “right_fill”: “#color”

}

with #color being some valid hex code.

Kivy¶

Once the tkinter interface is up and running we can experiment with different frontends to improve the look of the application. For example, the MIT licensed KIVY would allow us to replace the mobile development in Swift and Java with all Python development:

https://kivy.org/#home

Data/Code Seperation¶

All the “data” is in code files that are within the config/ submodule. So this way we don’t have to deal with awkward data packaging, it’s just available as a single JSON style object called settings available with this import line:

from embroidermodder.config import settings

In order to pass PyLint style guides this will be split up and formatted into Python code but no processing beyond inlining the data into a single dict should be carried out here.

The Settings Dictionary¶

No more than 4 levels of indentation

Only strings, arrays, dicts and integers so matching the JSON standard. Ideally you should be able to copy/paste the data in and out and it would parse as JSON. Currently this fails because we have multi-line strings in Python syntax and inlining.

We may be able to extend the lisp support, which would deal with this. Or we can change multiline strings out for arrays of strings.

Lisp Expression Support¶

In order to safely support user contributed/shared data that can define, for example, double to double functions we need a consistent processor for these descriptions.

Embroidermodder uses a list processor (a subset of the language Lisp which is short for LISt Processor) to accomplish this.

For example the string: (+ (* t 2) 5). is equivalent to the expression: $2*t + 5$.

The benefit of not allowing this to simply be a Python expression is that it is safe against malicious use, or accidental misuse. The program can identify whether the output is of the appropriate form and give finitely many calculations before declaring the function to have run too long (stopping equations that hang).

To see examples of this see parser.py and config/design\_primatives.py.

It’s also worth noting that we don’t use the simpler reverse Polish notation (RPN) approach because:

It’s more compact to use Lisp because a b c + + for example needs a new + sign for each new term as opposed to (+ a b c).
It’s easier to support expressions that are themselves function calls defined by the user (by adding support for defun or lambda.

SVG Icons¶

To make the images easier to alter and restyle we could switch to svg icons. There’s some code in the git history to help with this.

The Actions System¶

In order to simplify the development of a GUI that is flexible and easy to understand to new developers we have a custom action system that all user actions will go via an actuator that takes a string argument. By using a string argument the undo history is just an array of strings.

The C action_hash_data struct will contain: the icon used, the labels for the menus and tooltips and the function pointer for that action. There will be an accompanying argument for this function call, currently being drafted as action_call. So when the user makes a function call it should contain information like the mouse position, whether special key is pressed etc.

Accessibility¶

Software can be more or less friendly to people with dylexia, partial sightedness, reduced mobility and those who don’t speak English. Embroidermodder 2 has, in its design, the following features to help:

icons for everything to reduce the amount of reading required
the system font is configurable: if you have a dyslexia-friendly font you can load it
the interface rescales to help with partial-sightedness
the system language is configurable, unfortunately the docs will only be in English but we can try to supply lots of images of the interface to make it easier to understand as a second language
buttons are remappable: XBox controllers are known for being good for people with reduced mobility so remapping the buttons to whatever setup you have should help

Note that most of these features will be released with version 2.1, which is planned for around early 2023.

Sample Files¶

Various sample embroidery design files can be found in the samples/ folder.

Design¶

These are key bits of reasoning behind why the software is built the way it is.

Removed Elements¶

So I’ve had a few pieces of web infrastructure fail me recently and I think it’s worth noting. An issue that affects us is an issue that can effect people who use our software.

Qt and dependencies¶

Downloading and installing Qt has been a pain for some users (46Gb on possibly slow connections).

I’m switching to OpenGL with GLFW for the windowing which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

Pandoc Documentation¶

The documentation is, well better in that it’s housed in the main repository, but I’m not a fan of the write once build many approach as it means trying to weigh up how 3 versions are going to render.

Can we treat the website being a duplicate of the docs a non-starter? I’d be happier with tex/pdf only and (I know this is counter-intuitive) one per project.

OpenGL¶

OpenGL rendering within the application. This will allow for Realistic Visualization - Bump Mapping/OpenGL/Gradients?

This should backend to a C renderer or something.

Configuration Data Ideas¶

embroidermodder should boot from the command line regardless of whether it is or is not installed (this helps with testing and running on machines without root). Therefore, it can create an initiation file but it won’t rely on its existence to boot: ~/.embroidermodder/config.json.

Switch colors to be stored as 6 digit hexcodes with a texttt{#}.
We’ve got close to a hand implemented ini read/write setup in settings.py.

Distribution¶

When we release the new pip wheel we should also package:

.tar.gz and .zip source archive.
Debian package
RPM package

Only do this once per minor version number.

Scripting Overhaul¶

Originally Embroidermodder had a terminal widget, this is why we removed it:

ROBIN: I think supporting scripting within Embroidermodder doesn't make sense.

All features that use scripting can be part of libembroidery instead.
Users who are capable of using scripting won't need it, they can alter their embroidery files in CSV format, or import pyembroidery to get access.
It makes maintaining the code a lot more complicated, especially if we move away from Qt.
Users who don't want the scripting feature will likely be confused by it, since we say that's what libembroidery, embroider and pyembroidery are for.

How about a simpler ``call user shell`` feature? Similar to texmaker we just call system on a batch or shell script supplied by the user and it processes the file directly then the software reloads the file. Then we aren't parsing it directly.

I don't want to change this without Josh's support because it's a fairly major change.

JOSH: I totally agree.

I like the idea of scripting just so people that know how to code could write their own designs without needing to fully build the app. Scripting would be a very advanced feature that most users would be confused by. Libembroidery would be a good fit for advanced features.

Now we are using Python (again, sort of) this would be a lot more natural,
perhaps we could boot the software without blocking the shell so they can
interact? TODO: Screenshot a working draft to demonstrate.

Perennial Jobs¶

Check for memory leaks
Write new tests for new code.
Get Embroidermodder onto the current version of libembroidery.
PEP7 compliance.
Better documentation with more photos/screencaps.

Developing for Android¶

url{https://developer.android.com/studio/projects/add-native-code}

$ apt install google-android-ndk-installer cmake lldb gradle

Usage¶

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.

For each of the flags described here we will go into greater detail in this manual.

To Flag¶

Circle Flag¶

Ellipse Flag¶

Line Flag¶

Polyline Flag¶

Polygon Flag¶

Satin Flag¶

Stitch Flag¶

Basic Test Suite¶

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:

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:

depending on your preferred debugging approach. Passing this test will be required for us to accept your patch.

Full Test Suite¶

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.)

Ideas¶

Rendering system¶

There are two forms of render that will be produced.

A raster format as ppm so we can have a pixel for pixel output (for example extracting the embedded images in some formats).
The SVG format that will be fairly similar to InkStitch’s format.

We have an EmbImage struct to store the raster format.

currently creates a blank image. Previously the Hilbert curve test managed to create a correctly rendered version.

Tactile art and braille support¶

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:

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.

Mobile Support: MobileViewer and iMobileViewer¶

Embroidermodder 2.0.0-alpha User Manual¶

Introduction¶

Basic Features¶

Move a single stitch in an existing pattern¶

1. In the File menu, click Open…. When the open dialog appears find and select your file by double clicking the name of the file. Alternatively, left click the file once then click the Open button. 2. 3. In the File menu

TIP: For users who prefer

Advanced Features¶

subsection{Other Projects}

subsection{References}

Scripting Overhaul¶

Originally Embroidermodder had a terminal widget, this is why we removed it.

> ROBIN: I think supporting scripting within Embroidermodder doesn’t make > sense. > > All features that use scripting can be part of libembroidery instead. > Users who are capable of using scripting won’t need it, they can alter > their embroidery files in CSV format, or import pyembroidery to get > access. It makes maintaining the code a lot more complicated, especially > if we move away from Qt. Users who don’t want the scripting > feature will > likely be confused by it, since we say that’s what libembroidery, > embroider and pyembroidery are for. > > How about a simpler call user shell feature? Similar to texmaker we > just call system on a batch or shell script supplied by the user and it > processes the file directly then the software reloads the file. Then we > aren’t parsing it directly. > > I don’t want to change this without Josh’s support because it’s a fairly > major change. > > JOSH: I totally agree. > > I like the idea of scripting just so people that know how to code could > write their own designs without needing to fully build the app. > Scripting would be a very advanced feature that most users would be > confused by. Libembroidery would be a good fit for advanced features.

Perennial Jobs¶

Check for memory leaks
Clear compiler warnings on -Wall-ansi-pedantic for C.

Developing for Android¶

https://developer.android.com/studio/projects/add-native-code

apt install google-android-ndk-installer cmake lldb gradle

Bibilography¶

Introduction¶

Basic Features¶

Move a single stitch in an existing pattern¶

In the File menu, click Open.... When the open dialog appears find and select your file by double clicking the name of the file. Alternatively, left click the file once then click the Open button.
.
In the File menu

TIP: For users who prefer

Advanced Features¶

Other Projects¶

References¶

Planning¶

To see what’s planned open the [Projects](https://github.com/Embroidermodder/Embroidermodder/projects/1) tab which sorts all of the GitHub Issues into columns.

Format Support¶

Support for Singer FHE, CHE (Compucon) formats?

Why this document¶

I’ve been trying to make this document indirectly through the Github issues page and the website we’re building but I think a straightforward, plain-text file needs to be the ultimate backup for this. Then I can have a printout while I’m working on the project.

googletests¶

gtests are non-essential, testing is for developers not users so we can choose our own framework. I think the in-built testing for libembroidery was good and I want to re-instate it.

Qt and dependencies¶

I’m switching to SDL2 (which is a whole other conversation) which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

Documentation¶

Can we treat the website being a duplicate of the docs a non-starter? I’d be happier with tex/pdf only and (I know this is counter-intuitive) one per project.

Social Platform¶

So… all the issues and project boards etc. being on Github is all well and good assuming that we have our own copies. But we don’t if Github goes down or some other major player takes over the space and we have to move (again, since this started on SourceForge).

This file is a backup for that which is why I’m repeating myself between them.

JSON data Ideas¶

So:

Port settings.ini to settings.json.
Place settings.json in $HOME/.embroidermodder (or equivalent, see the homedir function in gui.c).
Parse JSON using cJSON (we have the new parseJSON function).
Better structure for settings data so parse and load JSON is easier and there’s less junk in global variables. A structure similar to a Python dict that uses constants like the sketch below.

subsubsection{Why JSON over ini?}

We need to hand-write emph{a} system because the current system is Qt dependent anyway.
This way we can store more complex data structures in the same system including the layout of the widgets which may be user configured (see Blender and GIMP).
Also it’s easier to share information formatted this way between systems because most systems us JSON or XML data: there’s better support for converting complex data this way.

subsubsection{Sketch of a settings system}

begin{lstlisting} #define SETTING_interface_scale 16

…

char int_settings_labels[] = { … “interface scale” /* the sixteenth entry / … “%” / terminator character */ };

…

/* to use the setting */ scale_interface(int_setting[SETTING_interface_scale]);

/* to set setting */ int_setting[SETTING_interface_scale] = 16;

/* to make the JSON storage */ for (i=0; int_settings_labels[i][0] != ‘%’; i++) {

fprintf(setting_file, “"%s" :%d,n”, int_settings_labels[i], int_settings[i]);

}

end{lstlisting}

This would all be in C, and wouldn’t rely on Qt at all. We already use a system like this in texttt{libembroidery} so hopefully devs on both would get the pattern.

subsection{Design}

These are key bits of reasoning behind why the software is built the way it is.

section{Conclusions}

chapter{Color Charts}

section{Built-ins}

subsection{SVG Colors}

section{Threads}

subsection{DXF color table}

subsection{HUS color table}

subsection{JEF color table}

subsection{PCM color table}

subsection{PEC color table}

section{Contributing}

subsection{Version Control}

Being an open source project, developers can grab the latest code at any time and attempt to build it themselves. We try our best to ensure that it will build smoothly at any time, although occasionally we do break the build. In these instances, please provide a patch, pull request which fixes the issue or open an issue and notify us of the problem, as we may not be aware of it and we can build fine.

Try to group commits based on what they are related to: features/bugs/comments/graphics/commands/etc…

See the coding style here (coding-style).

subsection{Get the Development Build going}

When we switch to releases we recommend using them, unless you’re reporting a bug in which case you can check the development build for whether it has been patched. If this applies to you, the current development build is https://github.com/Embroidermodder/Embroidermodder/releases/tag/alpha3[here].

These are key bits of reasoning behind why the GUI is built the way it is.

In a given table the left column is the default symbol and the right string is the translation. If the translate function fails to find a translation it returns the default symbol.

So in US English it is an empty table, but in UK English only the dialectical differences are present.

Ideally, we should support at least the 6 languages spoken at the UN. Quoting url{https://www.un.org}

There are six official languages of the UN. These are Arabic, Chinese, English, French, Russian and Spanish.

We’re adding Hindi, on the grounds that it is one of the most commonly spoken languages and at least one of the Indian languages should be present.

Written Chinese is generally supported as two different symbol sets and we follow that convension.

English is supported as two dialects to ensure that the development team is aware of what those differences are. The code base is written by a mixture of US and UK native English speakers meaning that only the variable names are consistently one dialect: US English. As for documentation: it is whatever dialect the writer prefers (but they should maintain consistency within a text block like this one).

Finally, we have texttt{default}, which is the dominant language of the internals of the software. Practically, this is just US English, but in terms of programming history this is the texttt{C locale}.

Old action system notes¶

Action: the basic system to encode all user input.

This typedef gives structure to the data associated with each action which, in the code, is referred to by the action id (an int from the define table above).

subsection{DESCRIPTION OF STRUCT CONTENTS}

subsection{label}

The action label is always in US English, lowercase, seperated with hyphens.

For example: texttt{new-file}.

section{Flags}

The bit based flags all collected into a 32-bit integer.

begin{table} begin{tabular}{l l} bit(s) & description \ 0 & User (0) or system (1) permissions. \ 1-3 & The mode of input. \ 4-8 & The object classes that this action can be applied to. \ 9-10 & What menu (if any) should it be present in. \ 11-12 & What end{tabular} caption{Flags of EM actions} end{table}

subsection{Description}

The string placed in the tooltip describing the action.

subsection{Original Prompt System}

NOTE: main() is run every time the command is started. Use it to reset variables so they are ready to go.

NOTE: click() is run only for left clicks. Middle clicks are used for panning. Right clicks bring up the context menu.

NOTE: move() is optional. It is run only after enableMoveRapidFire() is called. It will be called every time the mouse moves until disableMoveRapidFire() is called.

NOTE: prompt() is run when Enter is pressed. appendPromptHistory is automatically called before prompt() is called so calling it is only needed for erroneous input. Any text in the command prompt is sent as an uppercase string.

Libembroidery v1.0-alpha¶

(Under construction, please wait for v1.0 release.)

Libembroidery is a low-level library for reading, writing, and altering digital embroidery files in C. It is part of the Embroidermodder Project for open source machine embroidery.

Libembroidery is the underlying library that is used by [Embroidermodder 2](http://embroidermodder.org) and is developed by [The Embroidermodder Team](ref the-embroidermodder-team). A full list of contributors to the project is maintained in [the Embroidermodder 2 github](https://github.com/Embroidermodder/embroidermodder) in the file CREDITS.md. 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.

Libembroidery is documented as part of the [Embroidermodder 2.0 manual]( url{https://www.libembroidery.org/emrm-2.0.0-alpha.pdf}). If you need libembroidery for any non-trivial usage or want to contribute to the library we advise you read the appropriate design sections of the manual first. Copies of this manual will be shipped with the packaged version of libembroidery, but to build it we use the Doxyfile in [the Embroidermodder git repository](https://github.com/Embroidermodder/embroidermodder).

For more basic usage, embroider should have some in-built help starting with:

begin{lstlisting} $ embroider –help end{lstlisting}

subsection{License}

Libembroidery is distributed under the permissive zlib licence, see the LICENCE file.

Demos¶

We’re currently trying out some fill techniques which will be demonstrated here and in the script texttt{qa_test.sh}.

Converts to:

Build¶

libembroidery and EmbroiderModder 2 use CMake builds so if you are building the project to use as a library we recommend you run:

This builds both the static and shared versions of the library as well as the command line program embroider.

subsection{Changelog}

subsection{Ideas}

Stuff that is now supposed to be generated by Doxygen:

todo: Bibliography style to plainnat.
todo: US letter paper version of printed docs.

chapter{Formats}

section{Overview}

subsection{Read/Write Support Levels}

The table of read/write format support levels uses the status levels described here: %if{0}

begin{longtable}{p{4cm} p{8cm}} caption{Read/Write Support Levels.} label{tab:read-write-support} \ textbf{Status Label} & textbf{Description} \

texttt{rw-none} & Either the format produces no output, reporting an error. Or it produces a Tajima dst file as an alternative. \

texttt{rw-poor} & 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. \

texttt{rw-basic} & Simple files in this format run well on machines that use this format. \

texttt{rw-standard} & Files with non-standard features work on machines and we have good documentation on the format. \

texttt{rw-reliable} & All known features don’t cause crashes. Almost all work as expected. \

texttt{rw-complete} & 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. end{longtable}

These can be split into r-basic w-none, for example, if they don’t match.

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.

subsection{Test Support Levels}

begin{longtable}{p{4cm} p{8cm}} caption{Test Support Levels.} label{tab:test-support} \ textbf{Status Label} & textbf{Description} \

texttt{test-none} & No tests have been written to test the specifics of the format. \

texttt{test-basic} & Stitch Lists and/or colors have read/write tests. \

texttt{test-thorough} & All features of that format has at least one test. \

texttt{test-fuzz} & 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. \

texttt{test-complete} & Both thorough and fuzz testing is covered. end{longtable}

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.

subsection{Documentation Support Levels}

begin{longtable}{p{4cm} p{8cm}} caption{Test Support Levels.} label{tab:doc-support} \ textbf{Status Label} & textbf{Description} \

texttt{doc-none} & We haven’t researched this beyond finding example files. \

texttt{doc-basic} & 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. \

texttt{doc-standard} & We know some good sources and/or have tested all the features that appear to exist. They mostly work the way we have described. \

doc-good & 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. \

doc-complete & There is a known official description and our description covers all the same features. end{longtable}

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.

subsection{Overall Support}

Since the overall support level is the combination of these 4 factors, but rather than summing up their values it’s an issue of the minimum support of the 4.

begin{table} begin{tabular}{l l} textbf{Status Label} & textbf{Description} \ read-only & If write support is none and read support is not none. \ write-only & If read support is none and write support is not none. \ unstable & If both read and write support are not none but testing or documentation is none. \ basic & If all ratings are better than none. \ reliable & If all ratings are better than basic. \ complete & If all ratings could not reasonably be better (for example any improvements rely on information that we may never have access to). This is the only status that can be revoked, since if the format changes or new documentation is released it is no longer complete. \ experimental & For all other scenarios. end{tabular} caption{.} end{table}

Overview of documentation support by format.

Brand or Name	Extension	Read Support	Write Support	Documentation Quality	Testing
Toyota	.100	none	none	none	none
Toyota	.10o	basic	none	none	none
Bernina	.art	none	none	none	none
Bitmap Cache	.bmc	basic	none	none	none
Bits and Volts	.bro	basic	none	none	none
Melco	.cnd	none	none	doc-none test-none
Embroidery Thread Color	.col	basic	basic	none	none
Singer	.csd	basic	none	none	none
Comma Separated Values	.csv	none	none	none	none
Barudan	.dat	none	none	none	none
Melco	.dem	none	none	none	none
Barudan	.dsb	basic	none	none	none
Tajima	.dst	basic	none	none	none
ZSK USA	.dsz	basic	none	none	none
Drawing Exchange Format	.dxf	none	none	none	none
Embird	.edr	none	none	none	none
Elna	.emd	none	none	none	none
Melco	.exp	basic	none	none	none
Eltac	.exy	basic	none	none	none
Sierra Expanded	.eys	none	none	none	none
Fortron	.fxy	basic	none	none	none
Smoothie G-Code	.gc	none	none	none	none
Great Notions	.gnc	none	none	none	none
Gold Thread	.gt	none	none	none	none
Husqvarna Viking	.hus	basic	none	none	none
Inbro	.inb	basic	none	none	none
Embroidery Color Format	.inf	none	none	none	none
Janome	.jef	basic	none	none	none
Pfaff	.ksm	basic	none	none	none
Pfaff	.max	none	none	none	none
Mitsubishi	.mit	none	none	none	none
Ameco	.new	none	none	none	none
Melco	.ofm	none	none	none	none
Pfaff	.pcd	none	none	none	none
Pfaff	.pcm	none	none	none	none
Pfaff	.pcq	none	none	none	none
Pfaff	.pcs	buggy	none	none	none
Brother	.pec	none	none	none	none
Brother	.pel	none	none	none	none
Brother	.pem	none	none	none	none
Brother	.pes	basic	none	none	none
Brother	.phb	none	none	none	none
Brother	.phc	none	none	none	none
AutoCAD	.plt	none	none	none	none
RGB	.rgb	none	none	none	none
Janome	.sew	basic	none	none	none
Husqvarna Viking	.shv	none	none	none	none
Sunstar	.sst	none	none	none	none
Data Stitch	.stx	none	none	none	none
Scalable Vector Graphics	.svg	none	basic	none	none
Pfaff	.t01	none	none	none	none
Pfaff	.t09	none	none	none	none
Happy	.tap	basic	none	none	none
ThredWorks	.thr	none	none	none	none
Text File	.txt	none	none	none	none
Barudan	.u00	none	none	none	none
Barudan	.u01	none	none	none	none
Pfaff	`.vip	basic	none	none	none
Pfaff	`.vp3	basic	none	none	none
Singer	.xxx	basic	none	none	none
ZSK USA	.zsk	basic	none	none	none

TODO: Josh, Review this section and move any info still valid or needing work into TODO comments in the actual libembroidery code. Many items in this list are out of date and do not reflect the current status of libembroidery. When finished, delete this file.

Test that all formats read data in correct scale (format details should match other programs)

Add which formats to work with to preferences.

Check for memory leaks

Update all formats without color to check for edr or rgb files

Fix issues with DST (VERY important that DST work well)

TODO: Support for Singer FHE, CHE (Compucon) formats?

subsection{Development}

If you wish to develop with us you can chat via the contact email on the website https://libembroidery.org or in the issues tab on the github page https://github.com/Embroidermodder/Embroidermodder/issues. People have been polite and friendly in these conversations and I (Robin) have really enjoyed them. If we do have any arguments please note we have a Code of Conduct CODE\_OF\_CONDUCT.md so there is a consistent policy to enforce when dealing with these arguments.

The first thing you should try is building from source using the build advice (build) above. Then read some of the manual url{https://libembroidery.org/emrm_alpha_a4.pdf} to get the general layout of the source code and what we are currently planning.

Funding¶

The easiest way to help is to fund development (see the Donate button above), since we can’t afford to spend a lot of time developing and only have limited kit to test out libembroidery on.

Programming and Engineering¶

Should you want to get into the code itself:

Low level C developers are be needed for the base library texttt{libembroidery}.
Low level assembly programmers are needed for translating some of texttt{libembroidery} to texttt{EmbroiderBot}.
Hardware Engineers to help design our own kitbashed embroidery machine texttt{EmbroiderBot}, one of the original project aims in 2013.
Scheme developers and C/SDL developers to help build the GUI.
Scheme developers to help add designs for generating of custom stitch-filled emblems like the heart or dolphi. Note that this happens in Embroidermodder not libembroidery (which assumes that you already have a function available).

Writing¶

We also need people familiar with the software and the general machine embroidery ecosystem to contribute to the documentation (https://github.com/Embroidermodder/website).

We need researchers to find references for the documentation: colour tables, machine specifications etc. The history is murky and often very poorly maintained so if you know anything from working in the industry that you can share: it’d be appreciated!

Creating software that interfaces with hardware is costly. A summary of some of the costs involved:

Developer time for 2 core developers
Computer equipment and parts
Embroidery machinery
Various electronics for kitbashing Embroiderbot
Consumable materials (thread, fabric, stabilizer, etc…)

If you have found our software useful, please consider funding further development by donating to the project on Open Collective (https://opencollective.com/embroidermodder).

section{Why this document}

subsection{Qt and dependencies}

I’m switching to SDL2 (which is a whole other conversation) which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

subsection{Documentation}

Can we treat the website being a duplicate of the docs a non-starter? I’d be happier with tex/pdf only and (I know this is counter-intuitive) one per project.

subsection{Social Platform}

This file is a backup for that which is why I’m repeating myself between them.

subsection{Identify the meaning of these TODO items}

subsection{Progress Chart}

The chart of successful from-to conversions (previously a separate issue) is something that should appear in the README.

subsection{Standard}

The criteria for a good Pull Request from an outside developer has these properties, from most to least important:

% PEP 7, Code Lay-out % footnote{url{https://peps.python.org/pep-0007/#code-lay-out}

begin{itemize} #. No regressions on testing. #. Add a feature, bug fix or documentation that is already agreed on through

GitHub issues or some other way with a core developer.

No GUI specific code should be in libembroidery, that’s for Embroidermodder.
Pedantic/ansi C unless there’s a good reason to use another language.
Meet the style above (i.e. citep{pep7}.
We’ll just fix the style if the code’s good and it’s not a lot of work.
texttt{embroider} should be in POSIX style as a command line program.

#. No dependancies that aren’t standard, i.e. use only the C Standard Library. end{itemize}

section{Image Fitting}

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 .

subsection{To Place}

A emph{right-handed coordinate system}index{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 (texttt{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 texttt{’ ‘}.

subsection{To Do}

We currently need help with:

begin{itemize} #. Thorough descriptions of each embroidery format. #. Finding resources for each of the branded thread libraries (along with a

full citation for documentation).

Finding resources for each geometric algorithm used (along with a full

citation for documentation).

Completing the full texttt{–full-test-suite} with no segfaults and at least a

clear error message (for example not implemented yet).

Identifying best guesses for filling in missing information when going

from, say texttt{.csv} to a late texttt{.pes} version. What should the default be when the data doesn’t clarify?

Improving the written documentation.
Funding, see the Sponsor button above. We can treat this as work and

put far more hours in with broad support in small donations from people who want specific features.

end{itemize}

Beyond this the development targets are categories sorted into:

begin{itemize} #. Basic Features #. Code quality and user friendliness #. embroider CLI #. Documentation #. GUI #. electronics development end{itemize}

subsection{Basic features}

begin{itemize} #. Incorporate #if 0 ed parts of libembroidery.c. #. Interpret how to write formats that have a read mode from the source code and vice versa. #. Document the specifics of the file formats here for embroidery machine specific formats. Find websites and other sources that break down the binary formats we currently don’t understand. #. Find more and better documentation of the structure of the headers for the formats we do understand. end{itemize}

subsection{Code quality and user friendliness}

Document all structs, macros and functions (will contribute directly on the web version).
Incorporate experimental code, improve support for language bindings.
Make stitch x, y into an EmbVector.

subsection{Documentation}

Run 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.

Try to get as much of the source code that we maintain into C as possible so new developers don’t need to learn multiple languages to have an effect. This bars the embedded parts of the code.

subsection{GUI}

Make EmbroideryMobile (Android) also backend to libembroidery with a Java wrapper.
Make EmbroideryMobile (iOS) also backend to libembroidery with a Swift wrapper.
Share some of the MobileViewer and iMobileViewer layout with the main EM2. Perhaps combine those 3 into the Embroidermodder repository so there are 4 repositories total.
Convert layout data to JSON format and use cJSON for parsing.

section{Development}

subsection{Contributing}

If you’re interested in getting involved, here’s some guidance for new developers. Currently The Embroidermodder Team is all hobbyists with an interest in making embroidery machines more open and user friendly. If you’d like to support us in some other way you can donate to our Open Collective page (click the Donate button) so we can spend more time working on the project.

All code written for libembroidery should be ANSI C89 compliant if it is C. Using other languages should only be used where necessary to support bindings.

subsection{Debug}

If you wish to help with development, run this debug script and send us the error log.

begin{lstlisting} #!/bin/bash

rm -fr libembroidery-debug

git clone http://github.com/embroidermodder/libembroidery libembroidery-debug cd libembroidery-debug

cmake -DCMAKE_BUILD_TYPE=DEBUG . cmake –build . –config=DEBUG

valgrind ./embroider –full-test-suite end{lstlisting}

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.

subsection{Binary download}

We need a current embroider command line program download, so people can update without building.

section{Programming principles for the C core}

End arrays of char arrays with the symbol END, the code will never require this symbol as an entry.

Define an array as one of 3 kinds: constant, editable or data.

begin{itemize} #. Constant arrays are defined const and have fixed length matching the data. #. Editable arrays are fixed length, but to a length based on the practical use

of that array. A dropdown menu can’t contain more than 30 items, because we don’t want to flood the user with options. However it can nest indefinately, so it is not restricted to a total number of entries.

#. Data arrays is editable and changes total size at runtime to account for user data. end{itemize}

section{Style rules for arrays}

input{embedded.tex}

input{mobile.tex}

subsection{Ideas}

bibliographystyle{unsrtnat} bibliography{references}

appendix

input{thread_tables.tex}

chapter{License}

input{fdl-1.3.tex}

printindex

end{document}

input{code.tex}

section{The Embroidermodder Project and Team}

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.

The tools and associated documents are:

This website (www.libembroidery.org), which is maintained: https://github.com/Embroidermodder/website.
The manual covering all these projects which is maintained as part of the website and the docstrings within each code project. Current printer-friendly version of this document is here: https://www.libembroidery.org/emrm_current.pdf.
The GUI (embroidermodder), maintained here: https://github.com/Embroidermodder/embroidermodder.
The core library of low-level functions: https://github.com/Embroidermodder/libembroidery.
The Bash CLI needle which is part of the libembroidery source code.
The conversion tool emb_convert which is part of the libembroidery source code.
Mobile embroidery format viewers and tools: https://github.com/Embroidermodder/embroiderymobile.
Specs for an open hardware embroidery machine called Embroiderbot (not started yet) which is also part of the libembroidery source code.

They 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 hyperref{https://https://opencollective.com/embroidermodder} 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. The full list of contributors who wish to be credited is here: https://www.libembroidery.org/docs/credits/

Embroidermodder 2:

Jonathan Greig: hyperref{https://github.com/redteam316}
Josh Varga: hyperref{https://github.com/JoshVarga}
Robin Swift: hyperref{https://github.com/robin-swift}

Embroidermodder 1:

Josh Varga: hyperref{https://github.com/JoshVarga}
Mark Pontius: hyperref{http://sourceforge.net/u/mpontius/profile}

Embroidermodder 1 was started by Mark Pontius in 2004 while staying up all night with his son in his first couple months. When Mark returned to his day job, he lacked the time to continue the project. Mark made the decision to focus on his family and work, and in 2005, Mark gave full control of the project to Josh Varga so that Embroidermodder could continue its growth.

Embroidermodder 2 was conceived in mid 2011 when Jonathan Greig and Josh Varga discussed the possibility of making a cross-platform version. It is currently in active development and will run on GNU/Linux, Mac OS X, Microsoft Windows and Raspberry Pi.

The source code and binaries for Embroidermodder 1 were hosted on Sourceforge, but due to link rot we’ve lost them.

todo{upload a backup here.}

The source code for Embroidermodder 2 was moved to GitHub ([https://github.com/Embroidermodder/Embroidermodder](https://github.com/Embroidermodder/Embroidermodder)) on July 18, 2013.

This website was moved to GitHub ([https://github.com/Embroidermodder/www.libembroidery.org](https://github.com/Embroidermodder/www.libembroidery.org)) on September 9, 2013. Due to us losing the domain name it was renamed to texttt{www.libembroidery.org} from texttt{www.embroidermodder.org}.

The libembroidery library (https://github.com/Embroidermodder/libembroidery) became a seperate project in 2018 as a way of supporting other frontends with the same file parsing and geometry routines.

The source code for Embroidermodder 2 was moved to GitHub on July 18, 2013.

This website was moved to GitHub on September 9, 2013. Due to us losing the domain name it was renamed to www.libembroidery.org from www.embroidermodder.org.

The libembroidery library became a seperate project in 2018 as a way of supporting other frontends with the same file parsing and geometry routines.

section{Changelog}

subsection{From early alpha to beta}

begin{itemize} #. Up and Down keys cycle thru commands in the command prompt. end{itemize}

section{Online Viewer and Converter}

begin{verbatim} !!! warning

EXPERIMENTAL

<script>: /* Call clang generated WASM here. */

</script>

If you only need to convert and view machine embroidery files (like our old Android application) then this page does just that. To access other features of the Embroidermodder Project please see the [downloads.html](Downloads page).

<!– Uses the native file dialog to get the string as a file object that is passed to a function from script above.: If this is not called first, produce an error message. –>

<button onclick=”upload();”>Upload File</button>

<!– Displays the SVG file output as a widget below. This could be by default. –> <button onclick=”show_svg();”>Show</button>

<!– Brings up the native file dialog, call “convert” with the arguments. –> <button onclick=”export_to();”>Export…</button>

This viewer uses no cookies and no external tools, so if you save this webpage to use offline it will still function. Eventually, this webpage can be embedded in both an Android and an iOS app so we have, in total, 3 front-ends: embroider, embroidermodder and the viewer/converter. end{verbatim}

section{Credits for Embroidermodder 2, libembroidery and all other related code}

Please note that this file in not in alphabetical order. If you have contributed and wish to be added to this list, create a new credit bullet. Fill it in with your information and submit it to us. Supply your: your full name or pseudonym and GitHub handle, if available.

Kinds of contribution:

Documentation - for changes to README files, manuals or help files.
Artwork - for artwork other than designs.
Bug Fixes - for small patches of a few lines.
Translation - for large patches to the translation files.
Designs - for an embroidery design sample or parametrized design as a toml file.
Bindings - for programming language bindings for libembroidery.
Commands - for Embroidermodder 2’s in-built terminal.

finally there’s textbf{Core Developer} which is reserved for long term contributors.

Contributors¶

Warning

Need to fix script to generate from data.

— title: The Embroidermodder Project description: Free and Open Source Software for Machine Embroidery. keywords: machine embroidery, embroidery, dst, pes, jef —

Embroidermodder is a free machine embroidery software program. The newest version, Embroidermodder 2 can:

edit and create embroidery designs
estimate the amount of thread and machine time needed to stitch a design
convert embroidery files to a variety of formats
upscale or downscale designs
run on Windows, Mac and Linux

For more in-depth information, see [our website](http://www.libembroidery.org) and get the manuals [here](http://www.libembroidery.org/documentation).

To try out the software in alpha see our current [alpha pre-release](https://github.com/Embroidermodder/Embroidermodder/releases).

Various sample embroidery design files can be found in the src/samples folder.

Embroidermodder is developed by The Embroidermodder Team which is maintained as a list on the website under [“Credits”](http://www.libembroidery.org/credits).

## Screenshots

If you use multiple operating systems, it’s important to choose software that works on all of them.

Embroidermodder 2 runs on Windows, Linux and Mac OS X. Let’s not forget the [Raspberry Pi](http://www.raspberrypi.org).

![features: platforms 1](images/features-platforms-1.png)

### Realistic Rendering

(This feature is currently broken.)

It is important to be able to visualize what a design will look like when stitched and our pseudo ``3D’’ realistic rendering helps achieve this.

Realistic rendering sample #1:

![features real render 1](images/features-realrender-1.png)

Realistic rendering sample #2:

![features real render 2](images/features-realrender-2.png)

Realistic rendering sample #3:

![features real render 3](images/features-realrender-3.png)

Various grid types and auto-adjusting rulers

Making use of the automatically adjusting ruler in conjunction with the grid will ensure your design is properly sized and fits within your embroidery hoop area.

Use rectangular, circular or isometric grids to construct your masterpiece!

Multiple grids and rulers in action:

![features grid ruler](images/features-grid-ruler-1.png)

### Many measurement tools

Taking measurements is a critical part of creating great designs. Whether you are designing mission critical embroidered space suits for NASA or some other far out design for your next meet-up, you will have precise measurement tools at your command to make it happen. You can locate individual points or find distances between any 2 points anywhere in the design!

Take quick and accurate measurements:

![features measure 1](images/features-measure-1.png)

subsubsection{Add text to any design}

Need to make company apparel for all of your employees with individual names on them? No sweat. Just simply add text to your existing design or create one from scratch, quickly and easily. Didn’t get it the right size or made a typo? No problem. Just select the text and update it with the property editor.

Add text and adjust its properties quickly:

![features text 1](images/features-text-1.png)

subsubsection{Supports many formats}

Embroidery machines all accept different formats. There are so many formats available that it can sometimes be confusing whether a design will work with your machine.

Embroidermodder 2 supports a wide variety of embroidery formats as well as several vector formats, such as SVG and DXF. This allows you to worry less about which designs you can use.

subsubsection{Batch Conversion}

(Currently this being ported to the embroider command line program.)

Need to send a client several different formats? Just use libembroidery-convert, our command line utility which supports batch file conversion.

There are a multitude of formats to choose from:

![features formats](images/features-formats-1.png)

subsubsection{Scripting API}

The GUI works by emitting internal text commands, so if you want to alter or add features to the program that aren’t as low level as these commands then you can chain them together in simple scripts. This allows more control over the program than the GUI can offer.

A (no longer current) Embroidermodder 2 command excerpt:

![scripting screenshot](images/features-scripting-1.png)

subsection{Dependencies}

To build Embroidermodder 2 from source you will need at least [the Embroidermodder 2 source code itself](https://github.com/Embroidermodder/Embroidermodder), a build environment including [CMake](https://cmake.org) and [Qt](http://www.qt-project.org) (version >= 6.0). For advice on how to get these, see the following subsections.

You will also need the git submodules, which can be collected by running these lines from the embroidermodder source directory:

begin{lstlisting} git submodule init git submodule update end{lstlisting}

subsubsection{Debian/Ubuntu repository packages}

The Qt, KDE and Valgrind build dependencies can be installed easily by opening a terminal and issuing these commands:

begin{lstlisting} sudo apt-get update sudo apt-get install cmake build-essential qt6-base-dev libqt6gui6 libqt6widgets6

libqt6printsupport6 libqt6core6 libgl-dev libglx-dev libopengl-dev

end{lstlisting}

subsubsection{Fedora repository packages}

_TODO: This is outdated advice._

The Qt, KDE and Valgrind build dependencies can be installed easily by opening a terminal and issuing this command:

` sudo yum install git gdb gcc-c++ qt-devel kdelibs-devel valgrind `

### Windows (MSYS2)

After installing [MSYS2](https://www.msys2.org), run this command in a MINGW64 shell:

`sh pacman -S mingw-w64-clang-x86_64-qt6 cmake gcc make git `

At the time of writing, this will use around 2Gb of disk space. Then continue to [build](#build).

### Windows (Without MinGW or MSYS2)

If you have a development environment and for some reason want to use that over MSYS2 then ensure you run the installers for:

begin{enumerate} #. CMake: hyperref{https://cmake.org/download/#latest} #. Qt: hyperref{http://www.qt-project.org} #. A Text Editor for Code like Visual Studio Code: hyperref{https://code.visualstudio.com/} #. A C compiler, like gcc, cl, clang or tcc. #. Git Bash: hyperref{https://gitforwindows.org/} #. A backend for CMake like Ninja: hyperref{https://ninja-build.org/} end{enumerate}

Remember to add these to your PATH for scripts to use them.

This would give a similar build experience to standard development on Windows, but we recommend you use MSYS2.

Note that our behind-the-scenes Windows build uses Python to get the Qt libraries [like this](https://github.com/Embroidermodder/libembroidery/blob/main/bin/build.sh).

## Build

Assuming you have the dependencies for your system, on all systems with Bash, the following should work:

`sh bash build.sh `

If your system does not have bash, it may still run as sh. Failing that, try typing each line in in turn like this:

```sh git submodule init git submodule update

cmake -S . -B”build” -G”Unix Makefiles” -DCMAKE_BUILD_TYPE=”Debug” cd build cp -r ../assets/* . cmake –build . cat build.log cd .. ```

### Running the Development Version

After building as above, run your own development copy with:

`sh cd build ./embroidermodder2 `

### Troubleshooting

If you have no luck with the above advice and still want to run the development alpha, try reading the build.log in your build/ folder like this:

`sh cat build/build.log `

If, after googling keywords from the errors you’re still stuck post and issue on GitHub here: https://github.com/Embroidermodder/Embroidermodder/issues and supply the build.log file. If something comes up a lot then we can add advice here.

## Development

During the alpha phase we mainly need to focus on getting the C bedrock of this project stable before letting more people put their creations into it. In Beta, non-programming related contributions will be wecomed to the website and reference manual repositories.

### Getting Involved

Anyone interested in changing Embroidermodder or becoming a contributor should go read our [manuals](https://libembroidery.org/documentation), [make issues and submit patches](https://github.com/embroidermodder/refman) as you find them because the project is very weak here. It will also serve as training for submitting patches to the actual source code where changes are harder to critique and revise.

As for helping with specific bugs submitting an issue on GitHub along with the debug-####.txt file generated during your test run would be the best approach. For longer term techniques see the next section.

### Bug Hunting

Warning

IN ALPHA DEVELOPMENT: NOT READY FOR SERIOUS USE.

Embroidermodder is a free and open source machine embroidery application. If our project is successful, it will:

edit and create embroidery designs

estimate the amount of thread and machine time needed to stitch a design

convert embroidery files to a variety of formats

upscale or downscale designs

run on Windows, Mac and Linux

To try out the software in alpha see our downloads page.

Various sample embroidery design files can be found in the github samples folder.

If you use multiple operating systems, it’s important to choose software that works on all of them. Embroidermodder 2 runs on Windows, Linux and Mac OS X. Let’s not forget the Raspberry Pi.

# Documentation

For all of these manuals (except the embroider manpage), the source code is maintained as part of the website [here](https://github.com/Embroidermodder/docs).

## The User Manuals

Note that these URLs are maintained as the permalinks.

For all of these user manuals including the embroider manpage, the source code is maintained as part of the libembroidery project ([https://github.com/Embroidermodder/libembroidery](https://github.com/Embroidermodder/libembroidery)). The documentation, like the code, is mostly common to all subprojects.

Embroidermodder, EmbroideryMobile, PET: [https://www.libembroidery.org/user-manual](https://www.libembroidery.org/user-manual) ([PDF](https://www.libembroidery.org/em2_user_manual.pdf))
embroider: [https://www.libembroidery.org/embroider.txt](https://www.libembroidery.org/embroider.txt)

## The Developer Manual

The Embroidermodder Reference Manual (EMRM) is the main developer resource found here: [https://www.libembroidery.org/refman](https://www.libembroidery.org/refman) with the printer friendly version here: [https://www.libembroidery.org/downloads/emrm.pdf](https://www.libembroidery.org/downloads/emrm.pdf).

section{The Embroidermodder Project Website}

This directory contains most of the broader documentation and automation to stop minor changes flooding each of Embroidermodder’s sub-projects. Including the documentation as webpages for the site itself(hyperref{https://www.libembroidery.org}), each subproject’s user manual but not the reference manual.

This frees the other repositories of the minor-commit heavy mundane tasks of bundling software and separating a “user” build from a “production” build. It also means that those projects aren’t tasked with keeping production history.

For in-depth information about the software please read some of the PDF manual included in the top level of the repository. Finishing the manual is the current top priority in order to fascilitate new developers joining the project.

subsection{Ideas}

A testing site that is maintained under testing.libembroidery.org so builds don’t go straight to the main landing page.

If this reaches the cap of storage offered by a github repository then we’ll have to think of something else since the version history of the binaries could quickly become important if we have any regressions.

# About

section{The Embroidermodder Team}

subsection{Credits for Embroidermodder 2, libembroidery and all other related code} label{credits-for-embroidermodder-2-libembroidery-and-all-other-related-code}

Please note that this file in not in alphabetical order. If you have contributed and wish to be added to this list, create a new credit section and increment the number. Fill it in with your information and submit it to us.

Here is a summary of the values used:

Name: The full name of the contributor starting with given name.
GitHub: The GitHub account name of the contributor.
CoreDeveloper: This is reserved for long term contributors.

#. Documentation: If you have contributed changes to README files or help files, set this to true. #. Artwork: If you have contributed artwork or related changes, set this to true. #. textbf{BugFixes}: If you have contributed bug fixes or added new features, set this to true. #. textbf{Translation}: If you have provided language translations, set this to true. #. textbf{Designs}: If you have contributed an embroidery design sample, set this to true. #. textbf{Bindings}: If you have contributed programming language bindings for libembroidery, set this to true. #. textbf{Commands}: If you have contributed a command for Embroidermodder 2, set this to true.

subsubsection{Contributors}

Jonathan Greig texttt{redteam316} (Core Developer, Artwork, Documentation, Designs, Commands)
Josh Varga texttt{JoshVarga} (Core Developer)
Jens Diemer texttt{jedie} (Documentation)
Kim Howard texttt{turbokim} (Bug Fixes)
Martin Schneider texttt{craftoid} (Documentation)
Edward Greig texttt{Metallicow} (Artwork, Bug Fixes, Commands)
emph{It is a sin to wear the band’s shirt on concert night, Unless you buy it @t the show.}
Sonia Entzinger (Translation)
SushiTee texttt{SushiTee} (Bug Fixes)
Vathonie Lufh texttt{x2nie} (BugFixes, Bindings)
Nina Paley (Designs)
Theodore Gray (Designs)
Jens-Wolfhard Schicke-Uffmann texttt{Drahflow} (Bug Fixes)
Emmett Lauren Garlitz - Some Little Sandy Rd, Elkview, West by GOD Virginia texttt{Oll Em}
``I have a nice cherry chess-top(Glass). But remember, I NEVER played on it.’’
Robin Swift texttt{robin-swift} (Core Developer, Documentation)

begin{titlepage}

vspace*{8cm}

noindenttextbf{Huge Embroidermodder}

vspace{10pt}

noindentrule{linewidth}{2pt}

vspace{10pt}

begin{flushright} Large

Reference Manual

normalsize: The design, analysis and rationale of all Embroidermodder projects.

embversion

vspace{10pt}

url{https://www.libembroidery.org}

publicationdate end{flushright}

vspace{6cm}

begin{flushleft} Large emph{The Embroidermodder Team}

url{embroidermodder@gmail.com}

vspace{10pt}

noindentrule{linewidth}{1pt}

end{flushleft}

end{titlepage}

vspace*{8cm}

begin{quote} Copyright copyright{} 2013-2023 The Embroidermodder Team.

url{https://www.libembroidery.org}

The Embroidermodder Team consists of all contributors to our projects at url{https://github.com/Embroidermodder}. A copy of the contributor list is in the Credits section below and is maintained at url{https://www.libembroidery.org/docs/credits}.

bigskip

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License’’. end{quote}

newpage

vspace*{8cm}

# Introduction

## The Embroidermodder Project and Team

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.

The tools and associated documents are:

The website https://www.libembroidery.org
This reference manual covering the development of all these projects with the current version available here: url{https://www.libembroidery.org/embroidermodder_2.0_manual.pdf}
The GUI Embroidermodder 2 covered in Chapter~ref{GUI}.
The core library of low-level functions: libembroidery, covered in Chapter~ref{libembroidery}
The CLI embroider, which is part of libembroidery
Mobile embroidery format viewers and tools convered in Chapter~ref{Mobile}.
Specs for an open source hardware embroidery machine extension called the Portable Embroidery Tool (PET) which is also part of libembroidery. See Chapter~ref{PET}.

The website, this manual and some scripts to construct the distribution are maintained in %citep{thewebsite}.

They 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 (https://opencollective.com/embroidermodder) 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.

### Core Development Team}

Embroidermodder 2:

Jonathan Greig (https://github.com/redteam316)
Josh Varga (https://github.com/JoshVarga)
Robin Swift (https://github.com/robin-swift)

Embroidermodder 1:

Josh Varga (https://github.com/JoshVarga)
Mark Pontius (http://sourceforge.net/u/mpontius/profile)

### Credits for Embroidermodder 2, libembroidery and all other related code

If you have contributed and wish to be added to this list, alter the README on Embroidermodder github page (https://github.com/Embroidermodder/Embroidermodder) and we’ll copy it to the libembroidery source code since that is credited to The Embroidermodder Team.

include{credits.tex}

## History

### Embroidermodder 1

The Embroidermodder Team is also inspired by the original Embroidermodder that was built by Mark Pontius and the same Josh Varga on SourceForge which unfortunately appears to have died from linkrot. We may create a distribution on here to be the official legacy Embroidermodder code but likely in a seperate repository because it’s GNU GPL v3 and this code is written to be zlib (that is, permissive licensed) all the way down.

One reason why this is useful is that the rewrite by Jonathan Greig, John Varga and Robin Swift for Embroidermodder 2 should have no regressions: no features present in v1 should be missing in v2.

## Features

Embroidermodder 2 has many advanced features that enable you to create awesome designs quicker, tweak existing designs to perfection, and can be fully customized to fit your workflow.

A summary of these features:

Cross Platform
Realistic rendering
Various grid types and auto-adjusting rulers
Many measurement tools
Add text to any design
Supports many formats
Batch Conversion
Scripting API

## Cross Platform

If you use multiple operating systems, it’s important to choose software that works on all of them.

Embroidermodder 2 runs on Windows, Linux and Mac OS X. Let’s not forget the Raspberry Pi (https://www.raspberrypi.org).

![Features: platforms](images/features-platforms-1.png){ align=right }

## Realistic Rendering

It is important to be able to visualize what a design will look like when stitched and our pseudo 3D realistic rendering helps achieve this %(see Figure~ref{real-render}).

Real render examples.

![Features: real render 1](images/features-realrender-1.png)

![Features: real render 2](images/features-realrender-2.png)

![Features: real render 3](images/features-realrender-3.png)

### Various grid types and auto-adjusting rulers

Making use of the automatically adjusting ruler in conjunction with the grid will ensure your design is properly sized and fits within your embroidery hoop area.

Use rectangular, circular or isometric grids to construct your masterpiece!

Multiple grids and rulers in action Figure ref fig grid-ruler.

Grid and ruler examples.

![Features: grids and rulers](images/features-grid-ruler-1.png)

### Many measurement tools

Take quick and accurate measurements:

![Features: measurements](images/features-measure-1.png)

### Add text to any design

Add text and adjust its properties quickly:

![Features: text](images/features-text-1.png)

### Supports many formats

Embroidery machines all accept different formats. There are so many formats available that it can sometimes be confusing whether a design will work with your machine.

Embroidermodder 2 supports a wide variety of embroidery formats as well as several vector formats, such as SVG and DXF. This allows you to worry less about which designs you can use.

### Batch Conversion

Need to send a client several different formats? Just use libembroidery-convert, our command line utility which supports batch file conversion.

There are a multitude of formats to choose from:

![Features: formats](images/features-formats-1.png)

### Scripting API

If you’ve got programming skills and there is a feature that isn’t currently available that you absolutely cannot live without, you have the capability to create your own custom commands for Embroidermodder 2. We provide an QtScript API which exposes various application functionality so that it is possible to extend the application without requiring a new release. If you have created a command that you think is worth including in the next release, just contact us (contact.html) and we will review it for functionality, bugs, and finally inclusion.

An Embroidermodder 2 command excerpt:

!!! warning: Scripting isn’t Javascript-based any more. A more basic “run command” system is in development.

![Features: script](images/features-scripting-1.png)

% scripting screenshot

## Scraps

For Embroidermodder 2.0.0-alpha4, libembroidery 1.0.0-alpha, PET 1.0.0-alpha and EmbroideryMobile 1.0.0-alpha.

Since the document is shipped automatically try to update the revnumber each time you edit using revision.sh.

Test these:

``` sudo apt install latexml texlive-latex-base imagemagick info2man

# For our command line tools: makeinfo embroider.texi -o embroider.info info2man embroider.info > embroider.1 texi2pdf embroider.texi # Or groff macro package for example ms. # These may be housed in libembroidery since they’re to be shipped as part of # the embroider tarball.

# For online documentation: pandoc embroidermodder_refman.tex -f latex -t html -s -o emb_refman.html –bibliography embroidermodder.bib # Or latexml/latexmlpost ```

### Command Language

Printer Command Language (PCL), see %citet{packard1992pcl}.

HP-GL/2 Vector Graphics index{HP-GL/2} described in %citet{packard1992pcl}. Has commands like: texttt{PU} Pen Up, texttt{PR} Plot Relative, texttt{EP} edge polygon.

So commands read like this:

` PA40,10; `

command argument seperator (texttt{,}) argument terminator(texttt{;})

Constructing new commands from old ones in the command language is less natural in the HP-GL/2 language, but a similar layer for us is the tajima DST format (CITE) for existing printers and CNC commands for direct control… where’d we’d use G-Code (CITE) and Linux CNC (CITE).

Could we setpagedevice to a printer in some cases and a similar CUPS service for embroidery machines in others?

All systems are supported by ghostscript, when you account for homebrew (CITE):

` brew update brew upgrade brew install ghostscript brew cleanup `

Vector graphic logos don’t require the SVG Qt library.

### Man Pages

We maintain a traditional manpage for texttt{embroider} using the basic macros.

### Arduino

` apt-get install avr-libc gcc-avr uisp avrdude `

# Libembroidery

(Under construction, please wait for v1.0 release.)

Libembroidery is a low-level library for reading, writing, and altering digital embroidery files in C. It is part of the Embroidermodder Project for open source machine embroidery.

Libembroidery is the underlying library that is used by Embroidermodder 2 and is developed by The Embroidermodder Team %ref{the-embroidermodder-team}. A full list of contributors to the project is maintained in the Embroidermodder 2 github (https://github.com/Embroidermodder/embroidermodder) in the file CREDITS.md. 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.

## Documentation

Libembroidery is documented as part of this reference manual. If you need libembroidery for any non-trivial usage or want to contribute to the library we advise you read the appropriate design sections of the manual first. Copies of this manual will be shipped with the packaged version of libembroidery, but to build it we use the Doxyfile in url{https://github.com/Embroidermodder/embroidermodder} the Embroidermodder git repository.

For more basic usage, embroider should have some in-built help starting with:

` $ embroider --help `

### License

Libembroidery is distributed under the permissive zlib licence, see the LICENCE file.

## Demos

We’re currently trying out some fill techniques which will be demonstrated here and in the script texttt{qa_test.sh}.

includegraphics[width=0.5textwidth]{images/examples/logo.png}

Converts to:

includegraphics[width=0.5textwidth]{images/examples/crossstitch_logo.png}

### Build

libembroidery and EmbroiderModder 2 use CMake builds so if you are building the project to use as a library we recommend you run:

%lstinputlisting{examples/build_libembroidery.sh}

This builds both the static and shared versions of the library as well as the command line program embroider.

citep{packard1992pcl} citep{linuxcncsrc} citep{linuxcnc} citep{adobe1990postscript} citep{postscript1999postscript} citep{eduTechDST} citep{cups} citep{millOperatorsManual} citep{oberg1914machinery} citep{dxf_reference} citep{embroidermodder_source_code} citep{libembroidery_source_code} citep{acatina} citep{kde_tajima} citep{wotsit_archive} citep{wotsit_siterip} citep{fineemb_dst} citep{edutechwiki_dst}

## Graphical User Interface for PC

label{GUI}

### Overview

UNDER MAJOR RESTRUCTURING, PLEASE WAIT FOR VERSION 2

Embroidermodder is a free machine embroidery application. The newest version, Embroidermodder 2 can:

edit and create embroidery designs
estimate the amount of thread and machine time needed to stitch a design
convert embroidery files to a variety of formats
upscale or downscale designs
run on Windows, Mac and Linux

Embroidermodder 2 is very much a work in progress since we’re doing a ground up rewrite to an interface in C using the GUI toolkit SDL2. The reasoning for this is detailed in the issues tab.

For a more in-depth look at what we are developing read our website (https://www.libembroidery.org) which includes these docs as well as the up-to date printer-friendly versions. These discuss recent changes, plans and has user and developer guides for all the Embroidermodder projects.

To see what we’re focussing on right now, see the Open Collective News (https://opencollective.com/embroidermodder).

// fixme This current printer-friendly version is here (https://www.libembroidery.org/downloads/emrm.pdf).

### License

The source code is under the terms of the zlib license: see LICENSE.md in the source code directory.

%A copy of the license is included in Section~ref{GNU-free-documentation-license}.

### Build and Install

Assuming you already have the SDL2 libraries you can proceed to using the fast build, which assumes you want to build and test locally.

The fast build should be:

` bash build.sh `

or, on Windows:

` .\build.bat `

Then run using the run.bat or run.sh scripts in the build/ directory.

Otherwise, follow the instructions below.

If you plan to install the dev version to your system (we recommend you wait for the official installers and beta release first) then use the CMake build instead.

### Install on Desktop

We recommend that if you want to install the development version you use the CMake build. Like this:

``` git submodule –init –update

mkdir build cd build cmake .. cmake –build . sudo cmake –install . ```

These lines are written into the file:

` ./build_install.sh `

On Windows use the next section.

## History

All Embroidermodder downloads (downloads.html) are hosted on SourceForge.

The source code for Embroidermodder 1 (url{http://sourceforge.net/p/embroidermodder/code/HEAD/tree/embroidermodder1}) has always been hosted on Sourceforge.

The source code for Embroidermodder 2 (url{https://github.com/Embroidermodder/Embroidermodder}) was moved to GitHub on July 18, 2013.

The website for Embroidermodder (embroidermodder2/docs folder of https://github.com/Embroidermodder/Embroidermodder) was moved to GitHub on September 9, 2013.

## Contact us

For general questions email: url{mailto:embroidermodder@gmail.com}.

To request a new feature open an issue on the main Embroidermodder GitHub repository (url{https://github.com/Embroidermodder/Embroidermodder/issues}). We’ll move it to the correct repository.

## Downloads

### Alpha Build

This is a highly experimental build: we recommend users wait for the beta release when the basic features are functional.

Visit our GitHub Releases page (url{https://github.com/Embroidermodder/Embroidermodder/releases}) for the current build. Unfortunately, earlier builds went down with the Sourceforge page we hosted them on.

# GUI

Embroidermodder 2 is very much a work in progress since we’re doing a ground up rewrite to an interface in Python using the GUI toolkit Tk. The reasoning for this is detailed in the issues tab.

For a more in-depth look at what we are developing read the developer notes (link to dev notes section). This discusses recent changes in a less formal way than a changelog (since this software is in development) and covers what we are about to try.

## Documentation

The documentation is in the form of the website (included in the docs/ directory) and the printed docs in this file.

### Development

If you wish to develop with us you can chat via the contact email on the website (url{https://www.libembroidery.org}) or in the issues tab on the github page (url{https://github.com/Embroidermodder/Embroidermodder/issues}). People have been polite and friendly in these conversations and I (Robin) have really enjoyed them. If we do have any arguments please note we have a Code of Conduct (texttt{CODE_OF_CONDUCT.md}) so there is a consistent policy to enforce when dealing with these arguments.

The first thing you should try is building from source using the build advice(link to build) above. Then read some of the development notes (link to dev notes.md) to get the general layout of the source code and what we are currently planning.

### Testing

To find unfixed errors run the tests by launching from the command line with:

` $ embroidermodder --test `

then dig through the output. It’s currently not worth reporting the errors, since there are so many but if you can fix anything reported here you can submit a PR.

## Code Optimisations and Simplifications

### Geometry

For example if we create a circle with radius 10mm and center at (20mm, 30mm) then fill it with stitches the commands would be

lstinputlisting{examples/geometry.py}

but the user would do this through a series of GUI actions:

Create new file
Click add circle
Use the Settings dialog to alter the radius and center
Use the fill tool on circle
Select satin from the drop down menu

So EM2 does the job of bridging that gap.

### Postscript Support

In order to safely support user contributed/shared data that can define, for example, double to double functions we need a consistent processor for these descriptions.

Embroidermodder backends to the postscript interpreter included in libembroidery to accomplish this.

For example the string: 5 2 t mul add is equivalent to the expression $2*t + 5$.

To see examples of this see the texttt{assets/shapes/*.ps} files.

### SVG Icons

To make the images easier to alter and restyle we could switch to svg icons. There’s some code in the git history to help with this.

### The Actions System

The C action_hash_data struct will contain: the icon used, the labels for the menus and tooltips and the function pointer for that action. There will be an accompanying argument for this function call, currently being drafted as action_call. So when the user makes a function call it should contain information like the mouse position, whether special key is pressed etc.

### Accessibility

Software can be more or less friendly to people with dyslexia, partial sightedness, reduced mobility and those who don’t speak English. Embroidermodder 2 has, in its design, the following features to help:

icons for everything to reduce the amount of reading required
the system font is configurable: if you have a dyslexia-friendly font you can load it
the interface rescales to help with partial-sightedness
the system language is configurable, unfortunately the docs will only be in English but we can try to supply lots of images of the interface to make it easier to understand as a second language
buttons are remappable: XBox controllers are known for being good for people with reduced mobility so remapping the buttons to whatever setup you have should help

Note that most of these features will be released with version 2.1, which is planned for around early 2023.

### Sample Files

Various sample embroidery design files can be found in the embroidermodder2/samples folder.

### Shortcuts

A shortcut can be made up of zero or more modifier keys and at least one non-modifier key pressed at once.

To make this list quickly assessable, we can produce a list of hashes which are simply the flags ORed together.

The shortcuts are stored in the csv file shortcuts.csv as a 5-column table with the first 4 columns describing the key combination. This is loaded into the shortcuts TABLE. Each tick the program checks the input state for this combination by first translating the key names into indices for the key state, then checking for whether all of them are set to true.

### Removed Elements

So I’ve had a few pieces of web infrastructure fail me recently and I think it’s worth noting. An issue that affects us is an issue that can effect people who use our software.

### Qt and dependencies

Downloading and installing Qt has been a pain for some users (46Gb on possibly slow connections).

I’m switching to FreeGLUT 3 (which is a whole other conversation) which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

### Social Platform

Github is giving me a server offline (500) error and is still giving a bad ping.

This file is a backup for that which is why I’m repeating myself between them.

### OpenGL

OpenGL rendering within the application. This will allow for Realistic Visualization - Bump Mapping/OpenGL/Gradients?

This should backend to a C renderer or something.

### Configuration Data Ideas

Embroidermodder should boot from the command line regardless of whether it is or is not installed (this helps with testing and running on machines without root). Therefore, it can create an initiation file but it won’t rely on its existence to boot: texttt{~/.embroidermodder/config.json}.

Switch colors to be stored as 6 digit hexcodes with a #.
We’ve got close to a hand implemented ini read/write setup in settings.py.

### Distribution

index{distribution}

When we release the new pip wheel we should also package:

texttt{.tar.gz} and texttt{.zip} source archive.
Debian package
RPM package

Only do this once per minor version number.

### Perennial Jobs

Check for memory leaks
Clear compiler warnings on -Wall -ansi -pedantic for C.
Write new tests for new code.
Get Embroidermodder onto the current version of libembroidery.
PEP7 compliance.
Better documentation with more photos/screencaps.

### Full Test Suite

index{testing}

(This needs a hook from Embroidermodder to embroider’s full test suite.)

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.)

subsection{Symbols}

index{symbols}

Symbols use the SVG path syntax.

In theory, we could combine the icons and symbols systems, since they could be rendered once and stored as icons in Qt. (Or as textures in FreeGLUT.)

Also we want to render the patterns themselves using SVG syntax, so it would save on repeated work overall.

section{Features}

subsection{Bindings}

index{bindings}

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 Androidindex{Android} application MobileViewer)
Swift (for the iOSindex{iOS} application iMobileViewer)

For C# index{C#}index{C-sharp} we recommend directly calling the function directly using the DllImport feature:

see this StackOverflow discussion for help: https://stackoverflow.com/questions/11425202/is-it-possible-to-call-a-c-function-from-c-net

For Python you can do the same using ctypes: https://www.geeksforgeeks.org/how-to-call-a-c-function-in-python/

Other Supported Thread Brands¶

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.

Arc Polyester
Arc Rayon
Coats and Clark Rayon
Exquisite Polyester
Fufu Polyester
Fufu Rayon
Hemingworth Polyester
Isacord Polyester
Isafil Rayon
Marathon Polyester
Marathon Rayon
Madeira Polyester
Madeira Rayon
Metro Polyester
Pantone
Robison Anton Polyester
Robison Anton Rayon
Sigma Polyester
Sulky Rayon
ThreadArt Rayon
ThreadArt Polyester
ThreaDelight Polyester
Z102 Isacord Polyester

## GUI Design

Embroidermodder 2 was written in C++/Qt5 and it was far too complex. We had issues with people not able to build from source because the Qt5 libraries were so ungainly. So I decided to do a rewrite in C/SDL2 (originally FreeGLUT, but that was a mistake) with data stored as YAML. This means linking 4-7 libraries depending on your system which are all well supported and widely available.

This is going well, although it’s slow progress as I’m trying to keep track of the design while also doing a ground up rewrite. I don’t want to throw away good ideas. Since I also write code for libembroidery my time is divided.

Overview of the UI rewrite

(Problems to be solved in brackets.)

It’s not much to look at because I’m trying to avoid using an external widgets system, which in turn means writing things like toolbars and menubars over. If you want to get the design the actuator is the heart of it.

Without Qt5 we need a way of assigning signals with actions, so this is what I’ve got: the user interacts with a UI element, this sends an integer to the actuator that does the thing using the current state of the mainwindow struct of which we expect there to be exactly one instance. The action is taken out by a jump table that calls the right function (most of which are missing in action and not connected up properly). It also logs the number, along with key parts of the main struct in the undo history (an unsolved problem because we need to decide how much data to copy over per action). This means undo, redo and repeat actions can refer to this data.

# Introduction

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 textit{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 textit{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 Graphical User Interface: Embroidermodder 2.0.0-alpha

## Overview

## Features

Embroidermodder 2 has many advanced features that enable you to create awesome designs quicker, tweak existing designs to perfection, and can be fully customized to fit your workflow.

A summary of these features:

Cross Platform
Realistic rendering
Various grid types and auto-adjusting rulers
Many measurement tools
Add text to any design
Supports many formats
Batch Conversion
Scripting API

### Cross Platform

If you use multiple operating systems, it’s important to choose software that works on all of them.

Embroidermodder 2 runs on Windows, Linux and Mac OS X. Let’s not forget the Raspberry Pi (http://www.raspberrypi.org).

![Features: platforms](images/features-platforms-1.png)

### Realistic Rendering

It is important to be able to visualize what a design will look like when stitched and our pseudo 3D realistic rendering helps achieve this.

Realistic rendering sample #1:

![Features: Real render](images/features-realrender-1.png)

Realistic rendering sample #2:

![Features: Real render](images/features-realrender-2.png)

Realistic rendering sample #3:

![Features: Real render](images/features-realrender-3.png)

### Various grid types and auto-adjusting rulers

Making use of the automatically adjusting ruler in conjunction with the grid will ensure your design is properly sized and fits within your embroidery hoop area.

Use rectangular, circular or isometric grids to construct your masterpiece!

Multiple grids and rulers in action:

![Features: Real render](images/features-grid-ruler-1.png)

### Many measurement tools

Take quick and accurate measurements:

![Features: measurement](images/features-measure-1.png)

### Add text to any design

Add text and adjust its properties quickly:

![Features: text](images/features-text-1.png)

### Supports many formats

Embroidery machines all accept different formats. There are so many formats available that it can sometimes be confusing whether a design will work with your machine.

Embroidermodder 2 supports a wide variety of embroidery formats as well as several vector formats, such as SVG and DXF. This allows you to worry less about which designs you can use.

### Batch Conversion

Need to send a client several different formats? Just use libembroidery-convert, our command line utility which supports batch file conversion.

There are a multitude of formats to choose from:

![Features: batch conversion](images/features-formats-1.png)

### Scripting API

If you’ve got programming skills and there is a feature that isn’t currently available that you absolutely cannot live without, you have the capability to create your own custom commands for Embroidermodder 2. We provide an QtScript API which exposes various application functionality so that it is possible to extend the application without requiring a new release. If you have created a command that you think is worth including in the next release, just <a href=``contact.html``>contact us</a> and we will review it for functionality, bugs, and finally inclusion.

An Embroidermodder 2 command excerpt:

![Features: scripting](images/features-scripting-1.png)

## Contributing

### Version Control

Try to group commits based on what they are related to: features/bugs/comments/graphics/commands/etc…

See the coding style ref (coding-style)

## Introduction

### Basic Features

### Move a single stitch in an existing pattern

1. In the File’ menu, click `Open…’. When the open dialog appears find and select your file by double clicking the name of the file. Alternatively, left click the file once then click the `Open button. 2. 3. In the `File’ menu

!!! tip: For users who prefer

### Convert one pattern to another format

In the File menu, click Open….
The
In the dropdown menu within the save dialog select the

## Advanced Features

## Other Projects

### Planning

To see what’s planned open the [Projects](https://github.com/Embroidermodder/Embroidermodder/projects/1) tab which sorts all of the GitHub Issues into columns.

### Format Support

Support for Singer FHE, CHE (Compucon) formats?

### Donations

Creating software that interfaces with hardware is costly. A summary of some of the costs involved:

Developer time for 2 core developers
Computer equipment and parts
Embroidery machinery
Various electronics for kitbashing Embroiderbot
Consumable materials (thread, fabric, stabilizer, etc…)

If you have found our software useful, please consider funding further development by donating to the project on Open Collective (https://opencollective.com/embroidermodder).

Warning

(UNDER MAJOR RESTRUCTURING, PLEASE WAIT FOR VERSION 2.)

Embroidermodder is a free machine embroidery application. The newest version, Embroidermodder 2 can:

edit and create embroidery designs
estimate the amount of thread and machine time needed to stitch a design
convert embroidery files to a variety of formats
upscale or downscale designs
run on Windows, Mac and Linux

For more information, see our website (url{https://www.libembroidery.org})).

Embroidermodder 2 is very much a work in progress since we’re doing a ground up rewrite to an interface in Python using the GUI toolkit Tk. The reasoning for this is detailed in the issues tab.

To see what we’re focussing on at the moment check this table.

Date	Event
April-June 2022	Finish the conversion to C/SDL2
July-August 2022	Finish all the targets in the Design, or assign them to 2.1.
September 2022	Bugfixing, Testing, QA. libembroidery 1.0 will be released, then updates will slow down and the Embroidermodder 2 development version will be fixed to the API of this version.
October 2022	Embroidermodder 2 is officially released.

Build and Install¶

Desktop¶

First you must install the dependencies which aren’t compiled into the source:

git
cmake
A C compiler (we recommend gcc or clang)

on Debian Linux/GNU use:

``` $ sudo apt install git clang build-essential libsdl2-dev

libsdl2-images-dev libsdl2-ttf-dev

```

If you can’t find a good fit for your system (on Windows use the section below), try compiling the included submodules with:

` $ bash build_deps.sh `

From here, on most sytems the command:

` $ bash build.sh `

will build the software. Currently this is the 2.0-alpha, which will have a build code of some kind.

### Dependencies and Build

### Plans

### Windows Specific Advice

This is one of many possible ways to build the software on Windows, this section is to help people who’ve not got a build environment to start with.

Download and install MSYS2 (follow their instructions): https://www.msys2.org/
Boot Mintty from the Start menu.
Use the commands:

### Mobile

These are currently unsupported (see iMobileViewer and Mobileviewer for iOS and Android respectively), but after the Desktop version is released we’ll work on them.

The Mobile version will share some of the UI and all of the backend, so development of the Desktop version will help us make both.

### Documentation

The documentation is in the form of the website (included in the docs/ directory) and the printed docs in this file.

### Development

## Overall Structure

## Code Optimisations and Simplifications

### Current

What Robin is currently doing.

Getting the code to pass PyLint, that involves getting all source files under 1000 lines, renaming all variables to be in snake case.

Changing the seperation of code between EM and libembroidery.

Translating the Qt widget framework to Tk.

### Geometry

For example if we create a circle with radius 10mm and center at (20mm, 30mm) then fill it with stitches the commands would be

` from libembroidery import Pattern, Circle, Vector, satin circle = Circle(Vector(20, 30), 10) pattern = Pattern() pattern.add_circle(circle, fill=satin) pattern.to_stitches() `

but the user would do this through a series of GUI actions:

Create new file
Click add circle
Use the Settings dialog to alter the radius and center
Use the fill tool on circle
Select satin from the drop down menu

So EM2 does the job of bridging that gap.

## Settings Dialog

There are many codeblocks for changing out the colors in one go, for example:

` self.mw.update_all_view_select_box_colors( self.accept["display_selectbox_left_color"], self.accept["display_selectbox_left_fill"], self.accept["display_selectbox_right_color"], self.accept["display_selectbox_right_fill"], self.preview["display_selectbox_alpha"]) `

This could be replaced with a simpler call

` self.mw.update_all_view_select_box_colors( self.accept["display_selectbox_colors"], self.preview["display_selectbox_alpha"]) `

where we require that

``` self.accept[“display_selectbox_colors”] == {

“left_color”: “#color”, “left_fill”: “#color”, “right_color”: “#color”, “right_fill”: “#color”

with #color being some valid hex code.

### Kivy

url{https://kivy.org/#home}

### Data/Code Seperation

` from embroidermodder.config import settings `

In order to pass PyLint style guides this will be split up and formatted into Python code but no processing beyond inlining the data into a single dict should be carried out here.

### The Settings Dictionary

No more than 4 levels of indentation

We may be able to extend the lisp support, which would deal with this. Or we can change multiline strings out for arrays of strings.

### Lisp Expression Support

In order to safely support user contributed/shared data that can define, for example, double to double functions we need a consistent processor for these descriptions.

Embroidermodder uses a list processor (a subset of the language Lisp which is short for LISt Processor) to accomplish this.

For example the string: (+ (* t 2) 5) is equivalent to the expression: $2*t + 5$.

To see examples of this see parser.py and config/design_primatives.py.

It’s also worth noting that we don’t use the simpler reverse Polish notation (RPN) approach because:

It’s more compact to use Lisp because a b c + + for example needs a new + sign for each new term as opposed to (+ a b c).
It’s easier to support expressions that are themselves function calls defined by the user (by adding support for defun or lambda.

### SVG Icons

To make the images easier to alter and restyle we could switch to svg icons. There’s some code in the git history to help with this.

### The Actions System

The C texttt{action_hash_data} struct will contain: the icon used, the labels for the menus and tooltips and the function pointer for that action. There will be an accompanying argument for this function call, currently being drafted as texttt{action_call}. So when the user makes a function call it should contain information like the mouse position, whether special key is pressed etc.

### Accessibility

icons for everything to reduce the amount of reading required
the system font is configurable: if you have a dyslexia-friendly font you can load it
the interface rescales to help with partial-sightedness
the system language is configurable, unfortunately the docs will only be in English but we can try to supply lots of images of the interface to make it easier to understand as a second language
buttons are remappable: XBox controllers are known for being good for people with reduced mobility so remapping the buttons to whatever setup you have should help

Note that most of these features will be released with version 2.1, which is planned for around early 2023.

### Current Work

Converting C++ to Python throughout.
OpenGL Rendering * Real rendering to see what the embroidery looks like. * Icons and toolbars. * Menu bar
Libembroidery interfacing: * Get all classes to use the proper libembroidery types within them. So Ellipse has EmbEllipse as public data within it.
Move calculations of rotation and scaling into EmbVector calls.
Get undo history widget back (BUG).
Switch website to a CMake build.
GUI frontend for embroider features that aren’t supported by embroidermodder: flag selector from a table
Update all formats without color to check for edr or rgb files.
EmbroideryFLOSS - Color picker that displays catalog numbers and names
Setting for reverse scrolling direction (for zoom, vertical pan)
Stitching simulation
User designed custom fill
Keyboard zooming, panning
Advanced printing
Libembroidery 1.0
Better integrated help: I don’t think the help should backend to a html file somewhere on the user’s system. A better system would be a custom widget within the program that’s searchable.
New embroidermodder2.ico 16x16 logo that looks good at that scale.
saving dst, pes, jef
Settings dialog: notify when the user is switching tabs that the setting has been changed, adding apply button is what would make sense for this to happen.
Update language translations
Replace KDE4 thumbnailer.
Import raster image
Statistics from 1.0, needs histogram.
SNAP/ORTHO/POLAR
Cut/copy allow post-selection
Layout into config
Notify user of data loss if not saving to an object format.
Add which formats to work with to preferences.
Cannot open file with # in the name when opening multiple files but works with opening a single file.
Closing settings dialog with the X in the window saves settings rather than discarding them.
Otto theme icons: units, render, selectors, what’s this icon doesn’t scale
Layer manager and Layer switcher dock widget
test that all formats read data in correct scale (format details should match other programs).
Custom filter bug – doesn’t save changes in some cases.
Get flake8, pylint and tests to pass.
Sphinx documentation from docstrings or similar.

For more details read on into the Design section.

### Sample Files

Various sample embroidery design files can be found in the embroidermodder2/samples folder.

### Design

These are key bits of reasoning behind why the software is built the way it is.

### CAD command review

%cad_desc.csv

### Removed Elements

So I’ve had a few pieces of web infrastructure fail me recently and I think it’s worth noting. An issue that affects us is an issue that can effect people who use our software.

### Qt and dependencies

Downloading and installing Qt has been a pain for some users (46Gb on possibly slow connections).

I’m switching to FreeGLUT 3 (which is a whole other conversation) which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

### Social Platform

Github is giving me a server offline (500) error and is still giving a bad ping.

This file is a backup for that which is why I’m repeating myself between them.

### Pandoc Documentation

Can we treat the website being a duplicate of the docs a non-starter? I’d be happier with tex/pdf only and (I know this is counter-intuitive) one per project.

### OpenGL

OpenGL rendering within the application. This will allow for Realistic Visualization - Bump Mapping/OpenGL/Gradients?

This should backend to a C renderer or something.

### Configuration Data Ideas

Switch colors to be stored as 6 digit hexcodes with a texttt{#}.
We’ve got close to a hand implemented ini read/write setup in settings.py.

### Distribution

When we release the new pip wheel we should also package:

.tar.gz and .zip source archive.
Debian package
RPM package

Only do this once per minor version number.

### Scripting Overhaul

Originally Embroidermodder had a terminal widget, this is why we removed it.

` > ROBIN: I think supporting scripting within Embroidermodder doesn't make sense. > > All features that use scripting can be part of libembroidery instead. > Users who are capable of using scripting won't need it, they can alter their embroidery files in CSV format, or import pyembroidery to get access. > It makes maintaining the code a lot more complicated, especially if we move away from Qt. > Users who don't want the scripting feature will likely be confused by it, since we say that's what libembroidery, embroider and pyembroidery are for. > > How about a simpler ``call user shell feature? Similar to texmaker we just call system on a batch or shell script supplied by the user and it processes the file directly then the software reloads the file. Then we aren’t parsing it directly. > > I don’t want to change this without Josh’s support because it’s a fairly major change. > > JOSH: I totally agree. > > I like the idea of scripting just so people that know how to code could write their own designs without needing to fully build the app. Scripting would be a very advanced feature that most users would be confused by. Libembroidery would be a good fit for advanced features. > > Now we are using Python (again, sort of) this would be a lot more natural, > perhaps we could boot the software without blocking the shell so they can > interact? TODO: Screenshot a working draft to demonstrate. ```

### Perennial Jobs

Check for memory leaks
Write new tests for new code.
Get Embroidermodder onto the current version of libembroidery.
PEP7 compliance.
Better documentation with more photos/screencaps.

### Developing for Android

url{https://developer.android.com/studio/projects/add-native-code}

` $ apt install google-android-ndk-installer cmake lldb gradle `

### The Command Line Interface: embroider

### Usage

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.

%.. literalinclude:: help_msg.txt

For each of the flags described here we will go into greater detail in this manual.

### To Flag

### Circle Flag

### Ellipse Flag

### Line Flag

### Polyline Flag

### Polygon Flag

### Satin Flag

### Stitch Flag

### Basic Test Suite

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 `

` $ gdb --args embroider --verbose --test `

depending on your preferred debugging approach. Passing this test will be required for us to accept your patch.

### Full Test Suite

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.

### Ideas

### Rendering system

There are two forms of render that will be produced.

A raster format as ppm so we can have a pixel for pixel output (for example extracting the embedded images in some formats).
The SVG format that will be fairly similar to InkStitch’s format.

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.

#### Tactile art and braille support

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.

This is less important than getting better machine support but given the high social impact I think it should be a priority.

### The Low Level API: Libembroidery 1.0.0-alpha

### API Reference

### convert

### Mobile Support: MobileViewer and iMobileViewer

### Embroidermodder 2.0.0-alpha User Manual

### Introduction

### Basic Features

### Move a single stitch in an existing pattern

TIP: For users who prefer

### Convert one pattern to another

In the File menu, click Open….
The
In the dropdown menu within the save dialog select the

### Advanced Features

### Other Projects

### References

### Ideas

### Why this document

### Issues

### Fix before Version 2

So I’ve had a few pieces of web infrastructure fail me recently and I think it’s worth noting. An issue that affects us is an issue that can effect people who use our software.

Googletests require a web connection to update and they update on each compilation.
Downloading and installing Qt has been a pain for some users (46Gb on possibly slow connections). I think it was davieboy64?
The documentation is, well better in that it’s housed in the main repository, but I’m not a fan of the write once build many approach as it means trying to weigh up how 3 versions are going to render.
Github is giving me a server offline (500) error and is still giving a bad ping.
OpenGL rendering within the application. This will allow for Realistic Visualization - Bump Mapping/OpenGL/Gradients?
JSON configuration (Started, see texttt{head -n 50 src/mainwindow.cpp}.) Ok this is changing slightly. embroidermodder should boot from the command line regardless of whether it is or is not installed (this helps with testing and running on machines without root). Therefore, it can create an initiation file but it won’t rely on its existence to boot: this is what we currently do with settings.ini.
Get undo history widget back (BUG).
Switch website to a CMake build.
Mac Bundle, .tar.gz and .zip source archive.
NSIS installer for Windows, Debian package, RPM package
GUI frontend for embroider features that aren’t supported by embroidermodder: flag selector from a table
Update all formats without color to check for edr or rgb files.
EmbroideryFLOSS - Color picker that displays catalog numbers and names
Setting for reverse scrolling direction (for zoom, vertical pan)
Stitching simulation
User designed custom fill
Keyboard zooming, panning
Advanced printing
Libembroidery 1.0
Better integrated help: I don’t think the help should backend to a html file somewhere on the user’s system. A better system would be a custom widget within the program that’s searchable.
New embroidermodder2.ico 16x16 logo that looks good at that scale.
saving dst, pes, jef
Settings dialog: notify when the user is switching tabs that the setting has been changed, adding apply button is what would make sense for this to happen.
Update language translations
Replace KDE4 thumbnailer.
Import raster image
Statistics from 1.0, needs histogram.
SNAP/ORTHO/POLAR
Cut/copy allow post-selection
Layout into config
Notify user of data loss if not saving to an object format.
Add which formats to work with to preferences.
Cannot open file with # in the name when opening multiple files but works with opening a single file.
Closing settings dialog with the X in the window saves settings rather than discarding them.
Otto theme icons: units, render, selectors, what’s this icon doesn’t scale
Layer manager and Layer switcher dock widget
Test that all formats read data in correct scale (format details should match other programs).
Custom filter bug – doesn’t save changes in some cases.

### Fix for Version 2.1

### Fix eventually

### googletests

gtests are non-essential, testing is for developers not users so we can choose our own framework. I think the in-built testing for libembroidery was good and I want to re-instate it.

### Qt and dependencies

I’m switching to SDL2 (which is a whole other conversation) which means we can ship it with the source code package meaning only a basic build environment is necessary to build it.

### Documentation

Can we treat the website being a duplicate of the docs a non-starter? I’d be happier with tex/pdf only and (I know this is counter-intuitive) one per project.

### Social Platform

This file is a backup for that which is why I’m repeating myself between them.

### JSON data Ideas

So:

Port settings.ini to settings.json.
Place settings.json in $HOME/.embroidermodder (or equivalent, see the homedir function in texttt{gui.c}).
Parse JSON using cJSON (we have the new parseJSON function).
Better structure for settings data so parse and load JSON is easier and there’s less junk in global variables. A structure similar to a
Python dict that uses constants like the sketch below.

### Why JSON over ini?

We need find _a_ new system because the current system is Qt dependent anyway.
This way we can store more complex data structures in the same system including the layout of the widgets which may be user configured (see Blender and GIMP).
Also it’s easier to share information formatted this way between systems because most systems us JSON or XML data: there’s better support for converting complex data this way.

### Sketch of a settings system

This would all be in C, and wouldn’t rely on Qt at all. We already use a system like this in libembroidery so hopefully devs on both would get the pattern.

subsection{Design}

These are key bits of reasoning behind why the software is built the way it is.

subsection{Scripting Overhaul}

Originally Embroidermodder had a terminal widget, this is why we removed it.

begin{quote} ROBIN: I think supporting scripting within Embroidermodder doesn’t make sense.

All features that use scripting can be part of libembroidery instead. Users who are capable of using scripting won’t need it, they can alter their embroidery files in CSV format, or import pyembroidery to get access. It makes maintaining the code a lot more complicated, especially if we move away from Qt. Users who don’t want the scripting > feature will likely be confused by it, since we say that’s what libembroidery, embroider and pyembroidery are for.

How about a simpler call user shell feature? Similar to texmaker we just call system on a batch or shell script supplied by the user and it processes the file directly then the software reloads the file. Then we aren’t parsing it directly.

I don’t want to change this without Josh’s support because it’s a fairly major change.

JOSH: I totally agree.

I like the idea of scripting just so people that know how to code could write their own designs without needing to fully build the app. Scripting would be a very advanced feature that most users would be confused by. Libembroidery would be a good fit for advanced features. end{quote}

### Perennial Jobs

Check for memory leaks
Clear compiler warnings on -Wall-ansi-pedantic for C.

subsection{Developing for Android}

https://developer.android.com/studio/projects/add-native-code

` apt install google-android-ndk-installer cmake lldb gradle `

### Bibilography

### Introduction

### Basic Features

### Move a single stitch in an existing pattern

In the File menu, click Open…. When the open dialog appears find and select your file by double clicking the name of the file. Alternatively, left click the file once then click the Open button.
.
In the File menu

TIP: For users who prefer

### Convert one pattern to another format

In the File menu, click Open….
The
In the dropdown menu within the save dialog select the

### Advanced Features

### Other Projects

### References

### Planning

To see what’s planned open the [Projects](https://github.com/Embroidermodder/Embroidermodder/projects/1) tab which sorts all of the GitHub Issues into columns.

### Format Support

Support for Singer FHE, CHE (Compucon) formats?

### Embroidermodder Project Coding Standards

A basic set of guidelines to use when submitting code.

### Naming Conventions

Name variables and functions intelligently to minimize the need for comments. It should be immediately obvious what information it represents. Short names such as x and y are fine when referring to coordinates. Short names such as i and j are fine when doing loops.

Variable names should be “camelCase”, starting with a lowercase word followed by uppercase word(s). C++ Class Names should be “CamelCase”, using all uppercase word(s). C Functions that attempt to simulate namespacing, should be nameSpace\_camelCase.

All files and directories shall be lowercase and contain no spaces.

### Code Style

Tabs should not be used when indenting. Setup your IDE or text editor to use 4 spaces.

### Braces

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) {

Use exceptions sparingly.

Do not use ternary operator (?:) in place of if/else.

Do not repeat a variable name that already occurs in an outer scope.

### Version Control

Try to group commits based on what they are related to: features/bugs/comments/graphics/commands/etc…

### Comments

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. In any C code, you must use:

` /* C Style Comments */ /* TODO: This code clearly needs more work or further review. */ /* BUG: This code is definitely wrong. It needs fixed. */ /* HACK: This code shouldn't be written this way or I don't feel right about it. There may a better solution */ /* WARNING: Think twice (or more times) before changing this code. I put this here for a good reason. */ /* NOTE: This comment is much more important than lesser comments. */ `

## Ideas

### Why this document

### Issues

#### Fix before Version 2

So I’ve had a few pieces of web infrastructure fail me recently and I think it’s worth noting. An issue that affects us is an issue that can effect people who use our software.

Googletests require a web connection to update and they update on each compilation.
Downloading and installing Qt has been a pain for some users (46Gb on possibly slow connections). I think it was davieboy64?
Github is giving me a server offline (500) error and is still giving a bad ping.
OpenGL rendering within the application. This will allow for Realistic Visualization - Bump Mapping/OpenGL/Gradients?
JSON configuration (Started, see texttt{head-n50src/mainwindow.cpp.}) Ok this is changing slightly. embroidermodder should boot from the command line regardless of whether it is or is not installed (this helps with testing and running on machines without root). Therefore, it can create an initiation file but it won’t rely on its existence to boot: this is what we currently do with settings.ini.
Get undo history widget back (BUG).
Switch website to a CMake build.
Mac Bundle, .tar.gz and .zip source archive.
NSIS installer for Windows, Debian package, RPM package
GUI frontend for embroider features that aren’t supported by embroidermodder: flag selector from a table
Update all formats without color to check for edr or rgb files.
EmbroideryFLOSS - Color picker that displays catalog numbers and names
Setting for reverse scrolling direction (for zoom, vertical pan)
Stitching simulation
User designed custom fill
Keyboard zooming, panning
Advanced printing
Libembroidery 1.0
Better integrated help: I don’t think the help should backend to a html file somewhere on the user’s system. A better system would be a custom widget within the program that’s searchable.
New embroidermodder2.ico 16x16 logo that looks good at that scale.
saving dst, pes, jef
Settings dialog: notify when the user is switching tabs that the setting has been changed, adding apply button is what would make sense for this to happen.
Update language translations
Replace KDE4 thumbnailer.
Import raster image
Statistics from 1.0, needs histogram.
SNAP/ORTHO/POLAR
Cut/copy allow post-selection
Layout into config
Notify user of data loss if not saving to an object format.
Add which formats to work with to preferences.
Cannot open file with # in the name when opening multiple files but works with opening a single file.
Closing settings dialog with the X in the window saves settings rather than discarding them.
Otto theme icons: units, render, selectors, what’s this icon doesn’t scale
Layer manager and Layer switcher dock widget
test that all formats read data in correct scale (format details should match other programs).
Custom filter bug – doesn’t save changes in some cases.

#### Social Platform

This file is a backup for that which is why I’m repeating myself between them.

### JSON data Ideas

So:

Port settings.ini to settings.json.
Place settings.json in $HOME/.embroidermodder (or equivalent, see the homedir function in gui.c).
Parse JSON using cJSON (we have the new parseJSON function).
Better structure for settings data so parse and load JSON is easier and there’s less junk in global variables. A structure similar to a Python dict that uses constants like the sketch below.

#### Why JSON over ini?

We need to hand-write emph{a} system because the current system is Qt dependent anyway.
This way we can store more complex data structures in the same system including the layout of the widgets which may be user configured (see Blender and GIMP).
Also it’s easier to share information formatted this way between systems because most systems us JSON or XML data: there’s better support for converting complex data this way.

#### Sketch of a settings system

%.. literalinclude:: examples/settings_system.c

This would all be in C, and wouldn’t rely on Qt at all. We already use a system like this in texttt{libembroidery} so hopefully devs on both would get the pattern.

### Design

These are key bits of reasoning behind why the software is built the way it is.

## Conclusions

# Color Charts

## Built-ins

### SVG Colors

## Threads

### DXF color table

### HUS color table

### JEF color table

### PCM color table

### PEC color table

## Contributing

### Version Control

Try to group commits based on what they are related to: features/bugs/comments/graphics/commands/etc…

See the coding style here (coding-style).

### Get the Development Build going

### To Do

Beta * Libembroidery 1.0. * Better integrated help: I don’t think the help should backend to a html file somewhere on the user’s system. A better system would be a custom widget within the program that’s searchable. * EmbroideryFLOSS - Color picker that displays catalog numbers and names. * Custom filter bug – doesn’t save changes in some cases. * Advanced printing. * Stitching simulation.
2.x/ideas * User designed custom fill.

These are key bits of reasoning behind why the GUI is built the way it is.

## Translation of the user interface

In a given table the left column is the default symbol and the right string is the translation. If the translate function fails to find a translation it returns the default symbol.

So in US English it is an empty table, but in UK English only the dialectical differences are present.

Ideally, we should support at least the 6 languages spoken at the UN. Quoting https://www.un.org

> _There are six official languages of the UN. These are Arabic, Chinese, English, French, Russian and Spanish._

We’re adding Hindi, on the grounds that it is one of the most commonly spoken languages and at least one of the Indian languages should be present.

Written Chinese is generally supported as two different symbol sets and we follow that convension.

### Old action system notes

Action: the basic system to encode all user input.

This typedef gives structure to the data associated with each action which, in the code, is referred to by the action id (an int from the define table above).

### DESCRIPTION OF STRUCT CONTENTS

### label

The action label is always in US English, lowercase, seperated with hyphens.

For example: texttt{new-file}.

## Flags

The bit based flags all collected into a 32-bit integer.

bit(s) | description |

|----|———————–| | 0 | User (0) or system (1) permissions. | | 1-3 | The mode of input. | | 4-8 | The object classes that this action can be applied to. | | 9-10 | What menu (if any) should it be present in. | | 11-12 | What |

caption{Flags of EM actions}

### Description

The string placed in the tooltip describing the action.

### Original Prompt System

NOTE: main() is run every time the command is started. Use it to reset variables so they are ready to go.

NOTE: click() is run only for left clicks. Middle clicks are used for panning. Right clicks bring up the context menu.

NOTE: move() is optional. It is run only after enableMoveRapidFire() is called. It will be called every time the mouse moves until disableMoveRapidFire() is called.

# Libembroidery v1.0-alpha

(Under construction, please wait for v1.0 release.)

Libembroidery is a low-level library for reading, writing, and altering digital embroidery files in C. It is part of the Embroidermodder Project for open source machine embroidery.

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.

## Documentation

For more basic usage, embroider should have some in-built help starting with:

` $ embroider --help `

### License

Libembroidery is distributed under the permissive zlib licence, see the LICENCE file.

### Demos

We’re currently trying out some fill techniques which will be demonstrated here and in the script texttt{qa_test.sh}.

includegraphics[width=0.5textwidth]{images/logo-spirals.png}

Converts to:

includegraphics[width=0.5textwidth]{images/logo_spirals_cross_stitch.png}

### Build

libembroidery and EmbroiderModder 2 use CMake builds so if you are building the project to use as a library we recommend you run:

This builds both the static and shared versions of the library as well as the command line program embroider.

### Changelog

### Ideas

Stuff that is now supposed to be generated by Doxygen:

todo: Bibliography style to plainnat.
todo: US letter paper version of printed docs.

# Formats

## Overview

### Read/Write Support Levels

The table of read/write format support levels uses the status levels described here: