Automated Computed Embroidery

An embroidery machine sews areas of solid color, and every color in a design is one thread. A photo, or a logo saved as JPEG, contains thousands of slightly different shades. Before such an image can be turned into embroidery, the ACE service reduces it to a small number of flat color areas. The settings for this step go in the ACEParaOptimize object of a request with "Client": "ACE".

What the optimization does

The server processes the image in this order:

1. Rasterization (SVG and AI only): the vector file is converted to a PNG. With RasterizeNoAntiAlias it is drawn with hard edges.
2. Crop to content (optional, EnableCropToContent): the empty margin around the motif is cut off.
3. Size: the server reads the pixel size and resolution (96 DPI if the PNG stores no resolution). With EnableResample it then calculates the target size. SVG/AI may be drawn again at a higher resolution for large target sizes.
4. Background detection (optional, EnableBackgroundReplacement): the background becomes transparent, so it does not use up any of the target colors.
5. Pre-smoothing (PreSmoothStrength): the source is smoothed before the colors are chosen. This applies to photo-like images only. Flat artwork is not smoothed.
6. Color reduction to at most TargetColorCount colors. Flat artwork keeps its original colors. Photo-like images get averaged colors.
7. Merge similar colors (optional, MergeSimilarColors, off by default).
8. Noise filter (NoiseStrength): isolated specks and grain take the color of their surroundings.
9. Thread table (optional, ThreadTable): every color is replaced by the closest thread of the chosen thread series.
10. Preserve white highlights (optional, PreserveWhiteHighlights): very light pixels are set to one white color. It takes one of the target colors only if the result would otherwise contain no white.
11. Output: a PNG with the reduced colors. The pixels are not resampled. The stored resolution gives the PNG the requested size, or the source resolution if EnableResample is off.

Details, value tables and pitfalls: Color reduction (steps 1 and 5 to 10), Scaling (size and resolution) and Background detection (step 4).

Two ways the optimization runs

• On its own, with "RequestType": "OptimizePng". The response contains the optimized PNG and its key figures. No embroidery data is created. Use this request as a preview to tune the settings.
• Automatically before every ACE Create request (CreateTC, CreatePNG, CreateStatPNG, CreateACEPng, CreateACEVector). The server runs the same optimization with the ACEParaOptimize of that request and creates the embroidery from the optimized PNG. To get the colors of your preview, send the same ACEParaOptimize as in the OptimizePng request.
  • It runs for PNG input (PictureType "PNG") and for SVG/AI input. SVG/AI input is replaced by the optimized PNG. JPG, BMP and DXF are passed on without this optimization, so convert JPG and BMP files to PNG first.
  • It also runs if you leave out ACEParaOptimize. The API defaults are then used.
  • After a successful optimization the server sets ACEParaBitmapOptimize.Tolerance to 0, RemoveArea to 0 and MaxColors to 24, so the embroidery step does not reduce the colors a second time. Any values you send in these three fields are replaced.
  • ThreadTable matches the colors to threads. In a Create request the server also copies the name to an empty ACEParaBitmapToPunch.UseThreadCones, so the thread numbers are written into the embroidery file; see Color reduction.
  • Create reports no optimization errors. If the optimization fails, for example because of an unknown ThreadTable or because background detection removed every pixel, the original image is used. None of the ACEParaOptimize settings are applied, and the color reduction of the embroidery step (ACEParaBitmapOptimize) works with the values you sent. SVG/AI input cannot be used without the optimization, so the Create request fails with HTTP 503 and Communication with GiS ASPWebService failed!. Test new settings with OptimizePng first.
  • SkipColorReduction: true (PNG only): the PNG is passed on unchanged. It is only cropped if EnableCropToContent is also true. The color reduction of the embroidery step is switched off in the same way. Use this only for PNGs that already contain only their final thread colors (at most 24). For SVG/AI input it is ignored.

The OptimizePng request

• Send exactly one source: PictureBase64 with PictureType: "PNG", or VectorBase64 with VectorType: "SVG" or "AI". Type values are not case-sensitive.
• Send plain Base64, without a data-URL prefix such as data:image/png;base64,.
• ACEParaOptimize is optional. OptimizePng does not need ACEParaBitmapOptimize, ACEParaBitmapToVector, ACEParaBitmapToPunch or ACEParaVector, and ignores them if you send them. The one exception is ACEParaBitmapToPunch.UseThreadCones: if ThreadTable is empty, that series is used as ThreadTable.
• ServerVersion is not evaluated and can be left out.

Errors return Success: false with HTTP status 400. RequestData then contains the message:

Response

The response is a JobResponseType. On success:

• RequestData: the optimized PNG as Base64.
• Info: a JSON string. Parse it a second time to read its fields.

{
  "pixelWidth": 1200,
  "pixelHeight": 900,
  "widthMm": 100.0,
  "heightMm": 75.0,
  "colorCount": 12,
  "mappedYarnColors": null,
  "backgroundAutoDisabled": false
}

• The PNG is transparent where the background was removed and where the source was already transparent. Pixels below 50 % opacity count as transparent, and all other pixels become fully opaque.
• The PNG has at most TargetColorCount colors, and flat artwork often has fewer. The exception is TargetColorCount 1 with PreserveWhiteHighlights, which can give 2 colors.
• Check Success as well as the HTTP status; see Crop only below.

Crop only

With both SkipColorReduction: true and EnableCropToContent: true, OptimizePng only cuts off the empty margin:

• The response contains the cropped PNG with no color reduction, no scaling and no background removal. The pixels inside the cropped area are unchanged, and so is the stored resolution.
• SVG/AI input is rasterized first (with RasterizeNoAntiAlias, if set), so the response is always a PNG. Send that PNG as PictureBase64 in your next requests.
• Margin is detected by transparency if the image border is mostly transparent (less than a quarter of the outermost pixels opaque). Otherwise it is detected by the border color within BackgroundTolerance. With EnableBackgroundReplacement: true, anything background detection would remove also counts as margin. See Background detection.
• Info has the same fields, with colorCount 0, mappedYarnColors 0 and backgroundAutoDisabled false. Two more fields are added: cropped (false if there was nothing to crop; the PNG is then returned uncropped) and rasterized (true for SVG/AI input).
• If the crop fails, for example because the image cannot be decoded, Success is false and RequestData starts with Crop failed:. The HTTP status is not set to an error in this case.
• Crop-only requests use no license quota, but a valid WebApiLicense is still required.

Why crop in a separate request: if EnableCropToContent is set in a normal optimization or Create request, TargetWidthMm and TargetHeightMm still describe the uncropped image. To give the motif itself a size, first send a crop-only request. Then send the cropped PNG with the target size.

SkipColorReduction: true without EnableCropToContent is ignored by OptimizePng: the full optimization runs and is billed.

Billing

• Each successful OptimizePng request uses license quota. How many units it uses depends on your license type; see ZSK Web API license.
• Failed requests and crop-only requests use no quota.
• The optimization inside a Create request is not billed on its own. Only the Create request is billed.

Rules for ACEParaOptimize values

• Field names are case-sensitive. A misspelled field is silently ignored and its default is used. This also applies to the object name: a misspelled ACEParaOptimize means all defaults.
• A field you leave out uses its default. If the object is left out or null, all defaults are used.
• Whole numbers: TargetColorCount, NoiseStrength, PreSmoothStrength, BackgroundTolerance, SourceR/G/B and MergeSimilarDeltaE. A decimal value such as 7.5 in these fields makes the whole request fail. Decimals are accepted in ScalePercent, TargetWidthMm and TargetHeightMm (for example 85.5).
• No null or empty string in number and true/false fields. In any of them, for example ScalePercent or EnableResample, it makes the whole request fail, and no JobResponseType is returned. To use a default, leave the field out. Only the text fields ThreadTable and BackgroundDetectionMode accept null.
• The values "OptimizePng", "ACE", PictureType, VectorType and BackgroundDetectionMode are not case-sensitive in OptimizePng. For Create requests, send PictureType in upper case ("PNG"); see Color reduction.
• The server sets KmeansAttempts itself and ignores any value you send.

API defaults and the ACE client

The API defaults suit clean logos. The default preset of the ACE client is tuned for photos:

For the same result as in the ACE client, or for photos, send these values explicitly.

Recommended starting values

• Counting logo colors: a transparent or removed background does not count. A background that stays in the design counts as one color. With PreserveWhiteHighlights: true, add 1 for a logo with white parts.
• For a logo or graphic on a plain background, set EnableBackgroundReplacement: true. For photos without a real background, set it to false.
• For flat SVG/AI logos that get extra colors along their edges, also set RasterizeNoAntiAlias: true.
• Some SVG and AI files contain only an embedded photo. Treat them like a noisy photo; the server does not detect this.

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

Related sections

• Color reduction: target colors, noise filter, pre-smoothing, thread table, white highlights, hard vector edges
• Scaling: embroidery size, resolution, PNG versus SVG/AI
• Background detection: Auto and Manual mode, tolerance, interaction with the embroidery parameters
• ACEParaOptimize: field reference
• ACEParameter, ExampleRequest: the embroidery parameters of Create requests