The optional ACEParaOptimize object controls the server-side image optimization that runs before the embroidery is created: color reduction (k-means in CIELAB), optional thread-color mapping (CIEDE2000), background removal to transparency, noise filtering and scaling. It is used by the standalone OptimizePng request and also runs automatically before every ACE Create request with PNG, SVG or AI input. JPG input is not optimized. How the settings work, with value tables and pitfalls, is described in Optimize, Color reduction, Scaling and Background detection.
Rules
- Omit the object, or any single field, to use the defaults below. The optimization also runs if the object is omitted.
- Field names are case-sensitive. A misspelled field is ignored without an error, and its default is used.
- Integer fields need whole numbers: a decimal value such as
7.5 makes the whole request fail. Decimals are accepted only in ScalePercent, TargetWidthMm and TargetHeightMm.
null or an empty string in a number or true/false field makes the whole request fail. Only the text fields ThreadTable and BackgroundDetectionMode accept null. To use a default, leave the field out.- Only some values are limited by the server; the Range column says what happens to values outside the range.
Color reduction
| Field | Type | Default | Range | Description |
|---|
TargetColorCount | int | 8 | 1 – 24; values outside are moved to the nearest limit | Maximum number of colors (threads) in the result. Flat artwork keeps its original colors if the value is at least its number of colors. |
NoiseStrength | int | 2 | 0 – 10 (0 = off); values outside are moved to the nearest limit | Majority filter on the reduced result: removes specks and grain without creating new colors. Adds no dithering. |
PreSmoothStrength | int | 0 | 0 – 10 (0 = off); values outside are moved to the nearest limit | Edge-preserving bilateral smoothing of the source before the colors are chosen. Only for photo-like images; flat artwork is not smoothed. |
MergeSimilarColors | bool | false | true / false | Merges colors of the reduced result whose CIEDE2000 difference is below MergeSimilarDeltaE. |
MergeSimilarDeltaE | int | 0 | 1 – 20 while MergeSimilarColors is true; 0 then counts as 1 | CIEDE2000 threshold for the merge. Always send a value together with MergeSimilarColors. Ignored while MergeSimilarColors is false. |
ThreadTable | string | null | series name / null / "" | Thread series exactly as GetThreadConeSeries returns it, without .json (e.g. "Amann-Isacord 40"). Every color is replaced by the most similar thread. An unknown name makes OptimizePng fail; in a Create request the whole optimization is then skipped without an error. If ACEParaBitmapToPunch.UseThreadCones is empty, the server copies this name there, so the embroidery file also gets the thread numbers. If ThreadTable is empty, a series sent in UseThreadCones is used here. |
PreserveWhiteHighlights | bool | false | true / false | Pixels whose R, G and B are all 240 or higher are set to one white color. It takes one of the TargetColorCount colors only if the result would otherwise contain no white; see Color reduction. |
RasterizeNoAntiAlias | bool | false | true / false | SVG/AI only: rasterizes with hard edges, without blended edge colors. For flat vector logos, not for SVG photos or gradients. No effect on PNG. |
SkipColorReduction | bool | false | true / false | Create requests with PNG input: the PNG is passed on unchanged (at most 24 colors), and color reduction, thread table, background detection and scaling are skipped. Ignored for SVG/AI and for OptimizePng alone. Together with EnableCropToContent, OptimizePng only crops the image and uses no license quota. |
Cropping and scaling
| Field | Type | Default | Range | Description |
|---|
EnableCropToContent | bool | false | true / false | Cuts off the empty margin around the motif, by transparency or by the border color within BackgroundTolerance. In the same request, TargetWidthMm/TargetHeightMm still describe the uncropped image; to size the motif, crop in a separate request first. |
EnableResample | bool | false | true / false | Switches scaling on. PNG: only the resolution (pHYs) changes, the pixels stay the same. SVG/AI: drawn again at 300 DPI for larger targets (long side at most 8192 px). |
ScalePercent | double | 100 | > 0; 0 or less counts as 100 | Size as a percentage of the 100 % size. Used only if neither TargetWidthMm nor TargetHeightMm is greater than 0. |
TargetWidthMm | double | 0 | > 0 to apply; 0 or less = not set | Target width in mm. If only one side is sent, the other follows proportionally. |
TargetHeightMm | double | 0 | > 0 to apply; 0 or less = not set | Target height in mm. If both sides are sent, both are used as given, so a pair that does not match the image proportions distorts the design. |
Background detection
| Field | Type | Default | Range | Description |
|---|
EnableBackgroundReplacement | bool | false | true / false | Removes the background before color reduction. Removed pixels become transparent; despite the name, no replacement color is used. |
BackgroundDetectionMode | string | "Auto" | "Auto" / "Manual" | Auto: the server detects the background color in a strip along the image edges and ignores SourceR/G/B; it removes nothing if the image border is mostly transparent. Manual (any case): uses SourceR/G/B. Any other value counts as Auto. |
SourceR | byte | 255 | 0 – 255; values outside make the request fail | Background color, red channel (Manual mode only). |
SourceG | byte | 255 | 0 – 255; values outside make the request fail | Background color, green channel (Manual mode only). |
SourceB | byte | 255 | 0 – 255; values outside make the request fail | Background color, blue channel (Manual mode only). |
BackgroundTolerance | int | 30 | 0 or more; negative values count as 0, no upper limit (the ACE client offers 0 – 150) | Maximum Euclidean RGB distance to the background color. On white, 30 removes greys down to about 238 and 150 down to about 169. EnableCropToContent also uses it. |
RemoveBackgroundEverywhere | bool | false | true / false | false: only matching areas connected to the image edge are removed. true: every matching pixel is removed, including motif parts in that color. |
AutoRemoveVectorBackground | bool | false | true / false | SVG/AI only, independent of EnableBackgroundReplacement: if the rasterized image is completely opaque, the most common color of the outermost pixel ring is made transparent where it touches the edge (fixed tolerance). |
KmeansAttempts is set by the server; a value you send is ignored.