Automated Computed Embroidery

ACEParaOptimize

POST

The optional ACEParaOptimize object controls the server-side image optimization applied before punching: color reduction (K-means in Lab space), optional thread-color mapping (CIEDE2000), background removal to transparency, noise filtering and DPI-only scaling. It is used by the standalone OptimizePng request and also runs automatically before every Create request. Omit the object, or any single field, to use the defaults below. All numeric values are clamped server-side to the listed ranges.

Field	Type	Default	Range	Description
TargetColorCount	int	8	1-24	Target number of colors K for the K-means reduction.
NoiseStrength	int	2	0-10 (0 = off)	Majority/mode filter passes on the label map after clustering (removes speckle without new colors).
PreSmoothStrength	int	0	0-10 (0 = off)	Edge-preserving bilateral pre-smoothing of the source before clustering.
MergeSimilarColors	bool	false	true / false	Merge perceptually near-identical palette colors after reduction.
MergeSimilarDeltaE	int	0	1-20 (if merge on)	CIEDE2000 threshold for the merge; ignored when MergeSimilarColors is false.
ThreadTable	string	null	table name / null	Yarn-table file name without extension (e.g. "Amann-Isacord 40"). Enables CIEDE2000 thread mapping; null = free Lab palette. Unknown name returns an error.
EnableResample	bool	false	true / false	Enable scaling. Scaling is DPI-only: pixels stay unchanged, physical size set via the PNG resolution (pHYs).
ScalePercent	double	100	> 0	Scale as a percent of the original size. Ignored when a target mm value is set.
TargetWidthMm	double	0	> 0 to apply	Target physical width in mm; a missing side is filled proportionally.
TargetHeightMm	double	0	> 0 to apply	Target physical height in mm. For SVG/AI a larger target re-rasterizes at ~300 DPI (long side capped at 8192 px).
EnableBackgroundReplacement	bool	false	true / false	Detect and remove the background to transparency (before clustering).
BackgroundDetectionMode	string	"Auto"	Auto / Manual	Auto = infer the background color by border sampling; Manual = use SourceR/G/B.
SourceR	byte	255	0-255	Manual background color - red channel (Manual mode only).
SourceG	byte	255	0-255	Manual background color - green channel.
SourceB	byte	255	0-255	Manual background color - blue channel.
BackgroundTolerance	int	30	0-150	Euclidean RGB tolerance for matching background pixels.
RemoveBackgroundEverywhere	bool	false	true / false	Remove the background color everywhere within tolerance, not only the region flood-filled from the border.
AutoRemoveVectorBackground	bool	false	true / false	For fully-opaque SVG/AI imports: make the border background transparent at raster time.

Example

{
  "RequestType": "OptimizePng",
  "ACEParaOptimize": {
    "TargetColorCount": 24,
    "NoiseStrength": 5,
    "PreSmoothStrength": 0,
    "ThreadTable": "Amann-Isacord 40",
    "EnableResample": true,
    "TargetWidthMm": 120.0,
    "TargetHeightMm": 120.0,
    "EnableBackgroundReplacement": true,
    "BackgroundDetectionMode": "Manual",
    "SourceR": 244, "SourceG": 209, "SourceB": 157,
    "BackgroundTolerance": 30,
    "RemoveBackgroundEverywhere": false
  }
}