Automated Computed Embroidery

Background detection

POST

Background detection removes a plain background from the image before its colors are reduced. It is part of Optimize and is set in the ACEParaOptimize object (field reference: ACEParaOptimize). It runs in an OptimizePng request and in the optimization that runs automatically before every ACE Create request, for PNG, SVG and AI input. JPG and BMP images are passed to Create without it, so convert them to PNG first.

It is off by default. The ACE client's default preset switches it on with EnableBackgroundReplacement: true, BackgroundDetectionMode: "Auto" and BackgroundTolerance: 30. Send these values to get the same result as in the ACE client. See also Color reduction and Scaling.

What it does

Removed pixels become transparent. Despite its name, EnableBackgroundReplacement does not replace the background with another color, and there is no field for a target color. Removing the background has two advantages:

  • The background no longer uses up one of the colors of TargetColorCount.
  • For a clean logo, the original logo colors can be kept exactly. See Color reduction.

In the embroidery step, removed areas arrive as white. The ACEParaBitmapToVector settings decide whether they are stitched; see Background detection and the embroidery parameters below.

When to use it: for a logo or graphic on a plain background, for example black text on white. Leave it off for photos without a real background.

Order of the steps:

  1. SVG/AI input is converted to an image. AutoRemoveVectorBackground acts here.
  2. EnableCropToContent crops the image.
  3. Background detection removes the background.
  4. The colors are reduced: pre-smoothing, clustering, noise filter and thread table.
Auto and Manual
BackgroundDetectionModeWhich color is removed
"Auto" (default; every value other than "Manual")The server finds the color itself: it takes the most common color in a 3-pixel strip along all four image edges. Only opaque pixels count (alpha 128 or more). Shades that fall into the same bin of 16 values per channel count as one color, and the background color is the average of that bin. SourceR/G/B are ignored. Auto always picks a color, however small its share of the edge.
"Manual" (any case)The color in SourceR, SourceG and SourceB (default 255, 255, 255). Manual always runs, including on images with a transparent border.

Auto does nothing on an image that is already transparent. If the image has an alpha channel and less than a quarter of its outermost pixel ring is opaque, Auto removes nothing. Typical cases are a PNG with a transparent background and an SVG/AI without a background shape. The response does not report this skip. Manual mode is not affected.

Tolerance

BackgroundTolerance is a color difference, not a distance in pixels. A pixel counts as background if its Euclidean RGB distance √(ΔR² + ΔG² + ΔB²) to the background color is no greater than the tolerance. Examples for a white background:

BackgroundToleranceRemoved on a white background
0only the exact color 255, 255, 255
30 (default)white and very light grey, down to about 238, 238, 238. It also removes a pale tint that differs from white by up to 30 in only one channel, for example 255, 255, 225.
150also light and medium-light grey, down to about 169, 169, 169
442 or moreevery opaque pixel (the largest possible distance, black to white, is about 441.7)

A negative value counts as 0. The server sets no upper limit; the ACE client offers 0 – 150. Only whole numbers are accepted, and a decimal value makes the request fail. Start with 30. If a noisy background or a light rim remains, raise the value in small steps. Each step also removes more motif colors that are close to the background color.

Connected to the edge or everywhere
  • RemoveBackgroundEverywhere: false (default): only matching pixels that are connected to the image edge are removed. The removal starts at every matching pixel in the outermost rows and columns and spreads to horizontal and vertical neighbors that also match. Enclosed areas of the same color stay, for example the inside of an "O" or white eyes. Transparent pixels do not connect.
  • RemoveBackgroundEverywhere: true: every matching pixel is removed, anywhere in the image, including motif parts in that color. PreserveWhiteHighlights cannot bring them back.
AutoRemoveVectorBackground

This is a separate, simpler removal for SVG and AI input only. It works independently of EnableBackgroundReplacement and runs while the file is converted to an image. It acts only if that image is completely opaque, for example an SVG with a full-size background rectangle. It removes the most common exact color of the outermost pixel ring where that color is connected to the edge, with a fixed tolerance of 40. BackgroundDetectionMode, SourceR/G/B, BackgroundTolerance and RemoveBackgroundEverywhere do not apply to it.

It has no effect on PNG input, or on SVG files that contain only an embedded picture with a transparency mask. After it has run, the image border is usually transparent, so Auto mode of EnableBackgroundReplacement then usually does nothing. EnableBackgroundReplacement covers the same case and lets you choose the mode and the tolerance.

Watch out
  • Auto can remove motif parts. If the motif fills the image edges, Auto takes a motif color as the background and removes it wherever it touches the edge. Examples are a rectangular badge, a design that runs off the edges, and a tightly cropped motif. EnableCropToContent in the same request crops first, so it can cause the same problem. Check the result with OptimizePng. If motif parts are missing, use Manual mode with the real background color, or switch the removal off.
  • Photos: Auto always finds some color, for example sky or a wall, and removes it wherever it is connected to the edge.
  • Gaps in outlines: if an outline has a gap, the removal can leak through it and remove the area inside as well.
  • Manual mode and transparent margins: in connected mode, the removal cannot reach a background area that transparent pixels separate from the image edge. Use RemoveBackgroundEverywhere: true, or EnableCropToContent: true so that the area touches the edge after cropping.
  • Rims: blended edge pixels that differ from the background by more than the tolerance stay as a thin light or colored rim. A slightly higher tolerance removes more of the rim, but it can also remove motif colors. For SVG and AI logos, RasterizeNoAntiAlias: true reduces the rim; see Color reduction. The optimizer also makes every pixel with alpha below 128 transparent and every other pixel fully opaque. Soft shadows and feathered edges therefore always become hard edges, with or without Background detection.
  • Dark edges with pre-smoothing: removed pixels are stored as transparent black, and pre-smoothing ignores transparency. On photo-like images, a PreSmoothStrength of about 4 or more can therefore make the colors along the motif edge darker. If that happens, use 3 or less. Flat logos are not pre-smoothed.
  • If everything is removed (for example with a very high tolerance and RemoveBackgroundEverywhere: true), OptimizePng fails. The response has Success: false, HTTP status 400 and the RequestData "OptimizePng failed: PNG enthaelt nur transparente Pixel." (the image contains only transparent pixels). A Create request reports no error in this case. It uses your original input unchanged: with its background, without this optimization and at its original size. SVG/AI input cannot be used without this optimization, so the request fails with HTTP 503 and Communication with GiS ASPWebService failed!. Lower the tolerance or set RemoveBackgroundEverywhere to false, and test with OptimizePng first.
  • Cropping uses the tolerance too. EnableCropToContent uses BackgroundTolerance to tell margin from motif, even when EnableBackgroundReplacement is false. On an image with an opaque border, the border color is detected automatically, and colors within the tolerance count as margin. On an image with a transparent border, the crop goes by transparency. With EnableBackgroundReplacement: true, whatever the removal would take away also counts as margin; in Manual mode that is the Source color. The crop-only request uses the background only to find the crop rectangle, and the returned PNG still contains the background. See Optimize.
  • SkipColorReduction: on a Create request with PNG input, the optimizer does not run, so no background is removed. EnableCropToContent still crops, and it still uses the tolerance and the background settings. For SVG/AI input, SkipColorReduction is ignored and the removal runs.
Background detection and the embroidery parameters

ACEParaBitmapToVector contains three settings that sound similar to Background detection: DetermineBackgroundColor, BackgroundColor and BackgroundFill. They act later, when the reduced image is converted into stitch areas, and they do not change the image. They decide which color areas are not stitched:

  • DetermineBackgroundColor "1" (default, automatic): the background color is a color that covers more than 70 % of a 2-pixel strip along the image edges. A color that covers more than half of the strip and twice as much as the next color also counts. If no color is dominant, nothing is left out.
  • DetermineBackgroundColor "0" (specify): the color in BackgroundColor ("R,G,B") is used. Always send both together.
  • In both cases, an area counts as background only if its color matches closely. With ACEParaBitmapToVector.Tolerance 20, that means within about 5 per channel.
  • BackgroundFill "0": every area in the background color is left out, including enclosed areas.
  • BackgroundFill "1" (API default; the ACE client sends "0"): only background areas that touch the image edge are left out, and enclosed areas in the background color are stitched. Despite its name, "1" does not embroider the background around the motif.
  • Values other than "0" and "1" count as "1" for both fields.
  • Areas removed by Background detection arrive here as white (255, 255, 255), whatever color the original background had.

What this means with EnableBackgroundReplacement: true:

  • Most reliable setting: DetermineBackgroundColor: "0" with BackgroundColor: "255,255,255". The removed area is then always recognized, even if the motif covers most of the image edge. "1" usually finds the white too. But if the removed area covers too little of the edge, nothing is left out, and the removed area is stitched as a white fill.
  • Never specify the original background color, such as the beige you removed. The removed area is white, so it would be stitched.
  • BackgroundFill: "1": enclosed white motif parts are stitched, for example eyes, white text and highlights from PreserveWhiteHighlights. Enclosed areas removed with RemoveBackgroundEverywhere: true are also stitched, as a white fill.
  • BackgroundFill: "0": every pure white area is left out, including white motif parts. The exception is white that a thread table maps to a noticeably darker white.
  • A pure white motif part that touches the removed area merges with it and is left out with either value.
{ "ACEParaBitmapToVector": { "Tolerance": "20", "Smoothing": "150", "DetermineBackgroundColor": "0", "BackgroundColor": "255,255,255", "BackgroundFill": "1" } }

To have the background embroidered, setting EnableBackgroundReplacement to false is not enough. With DetermineBackgroundColor: "1", a plain border color is still left out. Also send DetermineBackgroundColor: "0" with a BackgroundColor that does not occur in your design, and check the result with a Create request. These settings also apply when SkipColorReduction is true.

Response

In the OptimizePng response, the removed background is transparent in the PNG in RequestData. The Info field backgroundAutoDisabled is effectively always false, and the quarter rule above does not set it. Check the returned image instead of relying on this flag. See Optimize and JobResponseType.

Parameters

Parameter Type Description Required
ACEParaOptimize.EnableBackgroundReplacement bool true removes the background before color reduction. Removed pixels become transparent; no replacement color is used. Default false (the ACE client's default preset uses true). No
ACEParaOptimize.BackgroundDetectionMode string "Auto" (default): the server detects the background color from a 3-pixel strip along the image edges and ignores SourceR/G/B. It removes nothing if the image has an alpha channel and less than a quarter of its outermost pixel ring is opaque. "Manual" (any case): SourceR/G/B are used. Every other value counts as "Auto". No
ACEParaOptimize.SourceR byte Red value of the background color, 0 – 255, used in Manual mode only. Default 255. A value outside 0 – 255 or a decimal value makes the request fail. No
ACEParaOptimize.SourceG byte Green value of the background color, 0 – 255, used in Manual mode only. Default 255. A value outside 0 – 255 or a decimal value makes the request fail. No
ACEParaOptimize.SourceB byte Blue value of the background color, 0 – 255, used in Manual mode only. Default 255. A value outside 0 – 255 or a decimal value makes the request fail. No
ACEParaOptimize.BackgroundTolerance int Maximum Euclidean RGB distance to the background color. Default 30. On white, 30 removes greys down to about 238 and 150 down to about 169. Negative values count as 0. There is no upper limit; 442 or more removes every opaque pixel. Whole numbers only. EnableCropToContent also uses it. No
ACEParaOptimize.RemoveBackgroundEverywhere bool false (default): only matching areas connected to the image edge are removed, and enclosed areas stay. true: every matching pixel is removed, including motif parts in that color. No
ACEParaOptimize.AutoRemoveVectorBackground bool 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 is connected to the edge, with a fixed tolerance of 40. Default false. No
ACEParaBitmapToVector.DetermineBackgroundColor int Which color the embroidery step leaves out as background. "1" (default): automatic. A color that covers more than 70 % of a 2-pixel strip along the image edges, or more than half of it and twice as much as the next color, counts as background. "0": BackgroundColor is used. Other values count as "1". Removed areas arrive as white, so with EnableBackgroundReplacement use "0" with "255,255,255". No
ACEParaBitmapToVector.BackgroundColor string "R,G,B", for example "255,255,255". Used only with DetermineBackgroundColor "0"; always send the two together. An area must match within about 5 per channel to count as background. No
ACEParaBitmapToVector.BackgroundFill int "0": every area in the background color is left out, including enclosed ones such as white eyes. "1" (API default; the ACE client sends "0"): only background areas that touch the image edge are left out, and enclosed ones are stitched. Neither value embroiders the background around the motif. Other values count as "1". No

Example

{
  "RequestType": "OptimizePng",
  "Client": "ACE",
  "WebApiLicense": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "PictureType": "PNG",
  "PictureBase64": "",
  "ACEParaOptimize": {
    "TargetColorCount": 4,
    "NoiseStrength": 2,
    "PreSmoothStrength": 0,
    "EnableBackgroundReplacement": true,
    "BackgroundDetectionMode": "Manual",
    "SourceR": 245,
    "SourceG": 238,
    "SourceB": 220,
    "BackgroundTolerance": 30,
    "RemoveBackgroundEverywhere": false
  }
}