Automated Computed Embroidery

Color reduction turns an image into a small number of flat color areas, one per thread color. It is one step of Optimize, and the ACEParaOptimize fields on this page control it. It runs in an OptimizePng request and automatically before every ACE Create request. It applies to PNG images (PictureType: "PNG") and to SVG/AI vectors (VectorType: "SVG" or "AI"), which are rasterized first.

JPG and BMP images do not go through this step. OptimizePng rejects them, and a Create request passes them on unchanged, so only the embroidery step's own reduction (ACEParaBitmapOptimize) applies. Convert them to PNG first. After a successful optimization, a Create request sets ACEParaBitmapOptimize.Tolerance to 0, RemoveArea to 0 and MaxColors to 24, so that the embroidery step keeps the optimized colors. Values you send for these three fields are then overridden.

Processing order

1. SVG and AI input is rasterized. RasterizeNoAntiAlias decides how the edges are drawn.
2. Background detection makes the background transparent, if it is enabled.
3. The server checks whether the image is flat artwork (see TargetColorCount). Flat artwork keeps its own colors. Any other image is first smoothed with PreSmoothStrength and then reduced to TargetColorCount colors.
4. MergeSimilarColors (optional) merges nearly identical colors.
5. NoiseStrength removes specks from the reduced result.
6. ThreadTable (optional) replaces the colors with real thread colors.
7. PreserveWhiteHighlights (optional) gives very light pixels their own white.

Every pixel of the result has exactly one of the final colors. Pixels with an alpha value below 128 become fully transparent and all others become fully opaque, so soft shadows and feathered edges turn into hard edges. Scaling sets the embroidery size and does not change the colors.

Value rules

• Color reduction always runs. If you omit ACEParaOptimize, the defaults are used: 8 colors, NoiseStrength 2, PreSmoothStrength 0, all options off and no thread table. To pass an already reduced PNG to a Create request unchanged, use SkipColorReduction.
• The API defaults suit clean logos. The ACE client's supplied default preset is tuned for photos (TargetColorCount 12, NoiseStrength 5, PreSmoothStrength 5) and also switches Background detection on. To get the same result as in the ACE client, send its values explicitly.
• TargetColorCount, NoiseStrength and PreSmoothStrength must be whole numbers. A decimal such as 7.5, null or an empty string makes the whole request fail. To use a default, leave the field out.
• Out-of-range values are moved to the nearest limit. For TargetColorCount, 30 becomes 24 and 0 becomes 1. NoiseStrength and PreSmoothStrength are limited to 0 – 10.
• Send the options as JSON true or false.
• Names are case-sensitive, and this includes the object name ACEParaOptimize. A misspelled field is ignored without an error, and its default is used. A misspelled object name drops all the settings on this page.
• Send PictureType in upper case ("PNG"). OptimizePng accepts any case. However, when a Create request passes the PNG on without optimizing it (because of SkipColorReduction or an optimizer error), a lower-case "png" leaves the embroidery step without an image.

TargetColorCount

Range 1 – 24, default 8. This is the maximum number of colors, and therefore threads, in the result. The server picks the colors that represent the image best and assigns every pixel to the closest of them. More colors keep more detail and shading, but every extra color means another thread and more color changes on the machine. Fewer colors give a simpler, bolder design that is quicker to sew.

Flat artwork and photos behave differently

• Flat artwork (real vector graphics, flat PNG logos) keeps its original colors exactly until a ThreadTable replaces them, as long as TargetColorCount is at least the number of its colors. The value is then an upper limit: a logo with 4 flat colors stays at 4 colors even if you send 12. PreSmoothStrength has no effect in this case.
• How flat artwork is recognized: a main color is an exact color that covers at least 1/2500 of the motif (0.04 %, and at least 8 pixels). A shade that differs from a more frequent main color by less than 4 (CIEDE2000) counts as an edge shade of that color. The image is flat artwork if it has between 2 and TargetColorCount main colors, and the exact colors above the 1/2500 limit together cover at least 80 % of the motif. The motif is all opaque pixels after Background detection.
• If you send fewer colors than the artwork has, it is treated like a photo. Similar colors are merged into averaged colors, and PreSmoothStrength takes effect.
• Photos, PNGs made from JPEG files, scans and images with gradients normally use the full number of colors, and the extra colors go into shades and edge pixels. The colors are averages of groups of similar shades (k-means clustering in CIELAB), so they may not match any single pixel of the original exactly. Send exactly as many colors as you want to sew.
• The result is reproducible. The same image with the same parameters gives the same optimized image in OptimizePng and in a later Create request.

How to count the colors of a logo: a transparent background does not count, and neither does one removed by Background detection. A background that stays in the image counts as one color. With PreserveWhiteHighlights: true, count white or very light parts as one of the logo colors.

Good to know

• Very small color areas are merged. In flat artwork, a color that covers less than 1/2500 of the motif takes the nearest main color, whatever target you send. Sending a larger image does not change this, because the detail must be larger in relation to the motif. To keep small white details, use PreserveWhiteHighlights.
• Almost identical colors are merged. In flat artwork, a color that differs from a main color by less than 4 (CIEDE2000) takes that main color.
• Single-color logos on a transparent background are not recognized as flat artwork, because at least 2 main colors are needed. Send TargetColorCount: 1. With a higher value, edge shades can take up the other colors.
• 1 color gives a silhouette in the average color of the motif, or in the closest thread. The background must be transparent or removed by Background detection. Also send PreserveWhiteHighlights: false, because otherwise white is added as a second color, and PreSmoothStrength: 0.
• Fewer colors than requested are normal for flat artwork. They can also occur with photos when two averaged colors come out identical.

Recommended values

NoiseStrength

Range 0 – 10, default 2, 0 = off. The ACE client calls it "Noise/dithering", but it adds no dithering. It removes isolated specks, scattered pixels and grain from the reduced result by giving them the color of their surroundings. It is a majority filter: each pixel takes the most frequent color in its neighborhood. The value is the number of passes. The neighborhood is 3 × 3 pixels up to value 5, 5 × 5 pixels for 6 – 8, and 7 × 7 pixels for 9 – 10.

• No new colors are created, and the number of colors does not go down: if the filter would remove a color completely, that color keeps one pixel. To get fewer colors, lower TargetColorCount.
• The borders between larger color areas stay in place. Only sharp corners may become slightly rounded.
• Transparent pixels are not changed, so the outline of the motif stays as it is.
• A very regular 50/50 pattern of two colors, such as a fine checkerboard, is only worn away from its edges. For photos, PreSmoothStrength helps against such patterns.

Use it when the reduced image looks grainy, speckled or noisy, which is typical for photos, JPEG-based images, scans and gradients. Tiny spots of color produce very short stitches, many jumps and unnecessary color changes.

Lines that separate two different colors, and outlines along a transparent edge, survive slightly higher values than lines inside a single color.

Watch out

• Fine details can disappear, even at low values. This includes hairlines, thin outlines, the dot on an "i", small eyes and small text.
• Narrow gaps can close, for example the space between two close lines or the inside of a small letter.
• The effect is measured in image pixels. One pixel in the embroidery is the embroidery width divided by the image width in pixels. A logo 600 pixels wide embroidered at 100 mm has about 0.17 mm per pixel, so a 3-pixel dot is about 0.5 mm. At 250 mm the same dot is about 1.25 mm. When Scaling enlarges SVG/AI input, the vector is rasterized again at about 300 DPI, so for an enlarged vector the effect in millimeters stays about the same.

Recommended values

PreSmoothStrength

Range 0 – 10, default 0, 0 = off. This setting smooths the source image before the colors are chosen. It uses an edge-preserving bilateral filter with a window of 2 × value + 1 pixels (3 pixels at 1, 21 pixels at 10). It evens out noise, grain, fine texture and JPEG compression artifacts, while edges between clearly different colors stay largely intact. Because the colors are then found on a calmer image, they are cleaner and form more even areas. The smoothing only influences how the colors are chosen and assigned, so the result still consists of flat colors only.

• Use it for photos, scans, JPEG-based images and other noisy sources. Without it, grain or compression artifacts lead to blotchy areas or use up colors on noise.
• It is not needed for clean logos. It has no effect on flat artwork as long as TargetColorCount is at least the number of its colors. If you reduce a logo to fewer colors than it has, send 0.

Like NoiseStrength, the effect is measured in image pixels, so it is stronger on images with few pixels.

Watch out

• High values round off outlines and can merge small details with their surroundings.
• Dark edges: on images with a transparent background, including a background removed by Background detection, values from about 4 upward can make the colors along the edge of the motif darker. The color hidden under the transparent pixels (black after Background detection) is blended into the edge. The effect is most visible on dark colors, and at high values on medium colors too. If an unwanted dark outline color appears, send 3 or less. The ACE client's default preset uses 5.

Recommended values

ThreadTable

Default: no thread table (field omitted, null or ""). The value is the name of a thread series exactly as GetThreadConeSeries returns it, without .json, for example "Amann-Isacord 40". GetThreadConeList lists the colors of a series. Without a thread table, the design keeps the colors found in the image.

• After the reduction and the noise filter, every color is replaced by the thread from the table that looks most similar. The server uses the smallest CIEDE2000 difference, not the closest RGB values. The optimized PNG then shows the colors of the actual threads.
• Each color gets its own thread. If two colors are closest to the same thread, one of them gets the next-closest free thread. With very similar colors, this second thread can look noticeably different.
• The number of colors does not change. TargetColorCount still sets it.
• A color that the series does not offer is replaced by the closest thread. For example, Madeira-CLASSIC 40 has no pure white, so white areas become its lightest thread, 1003, which is a light grey.
• Small series have few colors, for example Madeira-FIRE FIGHTER (24 colors), Gunold-Polyfire (27), Madeira-POLYNEON FR 40 (34) and Madeira-CLASSIC 12 (45). With many colors in the design, some colors then end up on clearly different threads.
• Unknown name: OptimizePng fails with HTTP 400, Success: false and the RequestData "OptimizePng failed: Garntabelle nicht gefunden: <name>" ("thread table not found"). A Create request shows no error. Instead, the whole optimization is skipped: the design is created from the original image without Background detection, without Scaling and without any other ACEParaOptimize setting, and only the embroidery step's own reduction with your ACEParaBitmapOptimize values applies. For SVG/AI input the Create request fails instead, with HTTP 503 and Communication with GiS ASPWebService failed!. Test a new name with OptimizePng first.

Thread information in the embroidery file. The thread information is written into the embroidery file from ACEParaBitmapToPunch.UseThreadCones. It is enough to send the series in one of the two fields: if UseThreadCones is empty, the server copies ThreadTable into it, and if ThreadTable is empty, the server copies UseThreadCones (without .json) into it, provided the series exists. If you send both, each field is used as sent, so use the same name. This excerpt of a request shows the two fields:

{
  "ACEParaOptimize": { "ThreadTable": "Amann-Isacord 40" },
  "ACEParaBitmapToPunch": { "UseThreadCones": "Amann-Isacord 40" }
}

• For no thread table, leave both empty.
• For every needle, the embroidery file then stores the thread series, the color number, the thread weight and the manufacturer, but not the name of the thread color. Series names longer than 15 characters are shortened in the file.
• In the CreateTC response (JobResponseType), NeedleColor is a string that contains a JSON array with one entry per needle. Each entry has NeedleNumber, Red, Green, Blue, ColorName, ColorNumber, ThreadSize, GarnSorte (unused) and Manufacturer. Despite its name, ColorName holds the thread series, for example "POLYNEON 40". ColorNumber contains only the digits, so 10CG3 appears as 103, while the embroidery file contains the full number. Without a thread table, the text fields are empty.
• With SkipColorReduction, and for JPG and BMP input, the optimization does not run; the embroidery step then matches the image colors to the table itself, with a simpler method.
• The number of needles can be slightly lower than colorCount after OptimizePng, because practically identical colors are sewn with one needle.

PreserveWhiteHighlights

Default false. The ACE client calls it "Preserve white highlights (e.g. eyes)". Without this option, small white details such as eye glints or light reflections can merge into a neighboring color and disappear. With it, very light pixels get their own white color.

• Which pixels: every pixel whose R, G and B are all 240 or higher becomes white. This includes large white areas, very light grey, very pale cream tints and a white background that was not removed, not only small details.
• When it acts: only if the image has at least 8 such pixels after Background detection. Otherwise nothing changes.
• Which white: if the reduced colors already include white, that color is used: with a ThreadTable the thread closest to white (for example 1003, light grey, with Madeira-CLASSIC 40, or 3, RGB 235, 236, 238, with Amann-Isacord 40), otherwise pure white or a color whose R, G and B are all 240 or higher. If not, this white is added.
• White takes a target color only if it is missing. The image is first reduced to TargetColorCount colors. If the result already contains white (see above), the very light pixels use it and all target colors are kept. Only if white is missing are the other colors reduced to TargetColorCount minus 1, and white is added.
  • For a logo with white or very light parts, count white as one of the logo colors.
  • Examples with a transparent or removed background: TargetColorCount: 1 gives 2 colors, the average color plus white. TargetColorCount: 2 on a black-and-white logo gives black and white.
• Specks stay. The white is set after NoiseStrength has run, so single light pixels remain as white specks, for example from JPEG noise or glare in a photo. PreSmoothStrength does not remove them either, because the test uses the original colors.
• With Background detection and RemoveBackgroundEverywhere: true on a white background, enclosed white details are removed before this option acts, and it cannot bring them back.
• Leave it off for photos, JPEG-based images and scans with glare or noise, for single-color embroidery, and when white areas should simply show the fabric.

Are the white highlights stitched? The OptimizePng result shows them. In the embroidery step, however, a removed background arrives as pure white, and ACEParaBitmapToVector decides which areas are left out (see also Background detection):

• With DetermineBackgroundColor: "1" (Automatic) and BackgroundFill: "0", every area of almost pure white counts as background and is left out, so the fabric shows through. Almost pure means that R, G and B are each at most about 5 below 255. The ACE client sends BackgroundFill: "0". On white fabric this often looks fine, but on dark or colored fabric the highlight is missing.
• With the API default BackgroundFill: "1", only white areas that touch the image edge are left out, so enclosed highlights are stitched.
• With most thread tables, the whitest thread is a little darker than pure white, for example Madeira-CLASSIC 1003 or Amann-Isacord 3. The highlights are then stitched even with BackgroundFill: "0".
• A highlight that touches the removed background merges with it and is still left out.
• With the default ACEParaBitmapToPunch.MinimumAreaSize of 5 mm², a round glint smaller than about 2.3 mm across is not stitched. With 1, glints from about 1 mm across are kept. Alternatively, make the design larger.
• Check the result with a Create request, not only with OptimizePng.

RasterizeNoAntiAlias

Default false. The ACE client calls it "Vector: no anti-aliasing (hard edges)". It applies only to SVG and AI input and has no effect on PNG. When a vector is rasterized, its edges normally get blended in-between colors: the edge between red and white, for example, gets pinkish pixels. These shades can use up colors, prevent the original logo colors from being kept exactly, and leave a thin rim when a background is removed.

• AI files are drawn directly without anti-aliasing. Edges get no blended pixels, gradients inside the file stay as they are, and embedded pictures are drawn without smoothing.
• SVG files are drawn normally, and then every pixel is set to the nearest main color of the logo. Pixels below 50 % opacity become fully transparent, and all others become fully opaque. Here a main color must cover at least 0.2 % of the opaque image area (and at least 50 pixels), and an opaque background shape counts as part of that area. This is 5 times the usual 1/2500 limit. On a 50 × 50 mm motif, for example, a detail smaller than about 5 mm² in its own color takes the nearest main color, and enlarging the design does not help. Together with PreserveWhiteHighlights, tiny white glints can be lost this way.
• Use it for flat SVG and AI logos with solid colors, especially if they have an opaque background shape that Background detection removes. For SVG files, a thin rim in another logo color is still possible, but less likely.
• Not for SVG photos or gradients. If the SVG also contains a flat color, for example a white frame, the picture is reduced to its main colors, in the worst case to that single color. A pure photo usually stays unchanged. Gradients may stay almost unchanged or be replaced by a few flat stripes.
• No effect on SVG files that only contain a pixel picture with a transparency mask, which is typical of automatic image-to-SVG converters.
• The option is also applied when a crop-only request rasterizes a vector. The returned PNG keeps the setting of that request, and the option has no effect when you send that PNG later.
• The hard edges have tiny stair steps of about 0.085 mm, because vectors are rasterized at about 300 DPI. They are too small to show in embroidery.

SkipColorReduction

Default false. The ACE client calls it "Skip color reduction (image already optimized)". Use it only for PNG images that already contain only their final thread colors (at most 24).

• Size: with Skip, the embroidery size comes from the resolution stored in the PNG (96 DPI if none is stored), and TargetWidthMm, TargetHeightMm and ScalePercent are ignored. Save the PNG with the matching resolution; see Scaling.
• More than 24 colors: the embroidery step still reduces the image to 24 colors.
• Thread information: ThreadTable does not change the colors, but the server still copies it to an empty ACEParaBitmapToPunch.UseThreadCones, so the file gets the thread numbers.

MergeSimilarColors and MergeSimilarDeltaE

With MergeSimilarColors: true, colors of the reduced result whose CIEDE2000 difference is below MergeSimilarDeltaE are merged into one color, their pixel-weighted average. A chain of similar colors is merged as a whole. The merge runs before the noise filter, and with a ThreadTable the merged colors are matched to threads again. Unlike NoiseStrength, it lowers the number of colors. It helps when a shaded area has been split into several nearly identical colors and looks blotchy. MergeSimilarDeltaE is limited to 1 – 20 and is ignored while MergeSimilarColors is false. Always send a threshold: if it is left out or 0, it counts as 1, which merges practically nothing.

Checking the result

The Info JSON string of an OptimizePng response contains two color values. For the full response, see Optimize.

• colorCount: the number of colors in the optimized PNG, not counting transparent pixels. With a ThreadTable, this is the number of threads.
• mappedYarnColors: with a ThreadTable, the number of different threads that the opaque pixels are closest to before the reduction. It is only an indication, not the thread count of the result. Without a thread table, it is null.

Quick start

• For flat SVG and AI logos, also send RasterizeNoAntiAlias: true. With PreserveWhiteHighlights: true, count white parts as one of the logo colors.
• Some SVG and AI files are not real vector drawings but only contain an embedded photo. Treat them like a noisy photo, because the server does not adjust the values for such files.

Start with these values, check the result with OptimizePng, and then change one setting at a time: