Automated Computed Embroidery

Scaling sets the physical size of the design in millimeters. The settings are part of ACEParaOptimize. They apply in the stand-alone OptimizePng request and in the optimization that runs automatically before every ACE Create request. Scaling does not change the colors. For the processing order and the other optimization steps, see Optimize.

Switching scaling on

Scaling runs only with ACEParaOptimize.EnableResample: true. Without it, ScalePercent, TargetWidthMm and TargetHeightMm are ignored, and the design keeps its 100 % size (see below).

• A mm value greater than 0 takes priority over ScalePercent, for PNG and for SVG/AI. A mm value of 0 or less counts as not set.
• All three fields accept decimals, for example 85.5.
• The optimizer applies any size greater than 0. The 10 mm minimum of the ACE client exists only in the client.
• In Create requests, leave ACEParaBitmapOptimize.Resolution at 0. A value above 0 replaces the resolution that the optimizer writes into the PNG, so it overrides the scaling.

Pixel images and vector files

• PNG: only the resolution changes, and the pixels stay the same. The server writes the new resolution into the PNG (pHYs chunk), and the embroidery step takes the size from there. The size is applied exactly, but enlarging adds no detail: each pixel just becomes a larger piece of the design. For example, a logo 600 pixels wide scaled to 250 mm has about 0.42 mm per pixel.
• SVG/AI: the file is rasterized at 300 DPI. If the target size needs more pixels than that raster has, the file is drawn again at 300 DPI for the target size, so it stays sharp. The long side is capped at 8192 pixels, which is about 694 mm at 300 DPI. Above that, the size is still applied, but the resolution drops below 300 DPI. When you reduce the size, the file is not drawn again and only the resolution changes. An SVG or AI file that only contains an embedded photo does not get sharper.
• JPG/BMP: not scaled. OptimizePng rejects them with HTTP 400 and Invalid PictureType JPG. PNG is supported. Create passes them on without this optimization, so ACEParaOptimize has no effect. Convert them to PNG first.

Where the 100 % size comes from

ScalePercent refers to this 100 % size. For an SVG/AI document outside the limits, the percentage refers to the limited size, not to the document size. For example, an SVG whose long side is 20 mm starts at about 43 mm, so ScalePercent: 100 gives about 43 mm. If you need an exact size, use TargetWidthMm / TargetHeightMm.

Cropping and size

The size describes the whole image, including transparent or background margins. The created design only contains the motif. Without cropping, the motif therefore comes out smaller than the size you set.

• With EnableCropToContent: true in the same request, the mm values still describe the uncropped image: the motif gets the scale it would have inside an image of that size. In that case, send both TargetWidthMm and TargetHeightMm, in the proportions of the uncropped image. If you send only one of them, the missing side is calculated from the cropped proportions, and the motif is distorted. ScalePercent works the same with or without cropping.
• For SVG/AI, cropping and enlarging in the same request draws the motif at less than 300 DPI, so it is less sharp. Instead, fit the document size (viewBox or artboard) tightly around the motif in your graphics program, then send the vector with the target size and without cropping.
• To set the size of the motif itself, crop it first in a separate request:
  1. Send OptimizePng with SkipColorReduction: true and EnableCropToContent: true. This request does no color reduction and no scaling, and it uses no license quota. RequestData contains the cropped PNG. Info contains pixelWidth, pixelHeight, widthMm, heightMm (the motif at 100 %), cropped and rasterized.
  2. Send the cropped PNG with EnableResample: true and the target size, either to OptimizePng or to a Create request. EnableCropToContent is no longer needed.
• Send the same background settings in both requests. In step 1 they decide what counts as margin, and in step 2 what is removed. See Background detection.
• cropped: false means that nothing was trimmed. The motif already fills the image, the image contains only background, or the crop could not be done. The size then refers to the full image.
• For SVG/AI, the crop request returns a PNG (rasterized: true). In step 2 it is scaled like any PNG and is not drawn again, so large sizes do not get sharper.

Crop-only request (step 1):

{
  "RequestType": "OptimizePng",
  "Client": "ACE",
  "WebApiLicense": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "PictureType": "PNG",
  "PictureBase64": "<Base64 PNG>",
  "ACEParaOptimize": {
    "SkipColorReduction": true,
    "EnableCropToContent": true
  }
}

Interplay with other settings

• SkipColorReduction: true switches scaling off in only two cases:
  • Create with PNG input. The optimizer does not run, and the design uses the resolution stored in the PNG (96 DPI if none). To get a specific size, write the matching resolution into the PNG yourself.
  • OptimizePng together with EnableCropToContent: true. This is the crop-only request (see above).
  In all other cases, SkipColorReduction is ignored and scaling is applied: OptimizePng without cropping, and Create with SVG/AI.
• NoiseStrength and PreSmoothStrength work in image pixels. For a PNG, their effect in millimeters grows when you enlarge the design. For a vector that is drawn again at the new size, their effect stays about the same. See Color reduction.
• Embroidery parameters in ACEParaBitmapToPunch (line width, satin stitch width, minimum sizes) refer to the finished size. After scaling, the same values can give a different result. For example, a stroke that is satin at 100 % can become a step fill at 200 %.

Checking the size

• OptimizePng: Info.widthMm / heightMm are the physical size of the returned PNG, rounded to 0.01 mm. They are calculated from the requested size, not measured from the motif. Without EnableResample, they are the 100 % size. With EnableCropToContent in the same request, they are the requested size reduced to the cropped area. pixelWidth / pixelHeight are the pixels of the returned PNG. For a PNG they are unchanged (apart from cropping). For a vector that was drawn again, they are the new raster size.
• CreateTC and CreateStatPNG: Info.widthMm / heightMm are measured from the created design, so check the final size there. CreateACEPng and CreateACEVector return no Info.
• If the optimizer fails, Create silently continues with the original image and without scaling. A size in Info that does not match is then the only sign.

The example below scales a PNG of 1200 × 600 pixels to a width of 120 mm. The PNG stores no resolution, so its 100 % size is 317.5 × 158.75 mm. The height follows at 60 mm, and the PNG then has 254 DPI, which is 0.1 mm per pixel. Info is returned as a JSON string (see JobResponseType). Decoded, it looks like this:

{
  "pixelWidth": 1200,
  "pixelHeight": 600,
  "widthMm": 120.0,
  "heightMm": 60.0,
  "colorCount": 6,
  "mappedYarnColors": null,
  "backgroundAutoDisabled": false
}

To create the embroidery at this size, send the same ACEParaOptimize object with a Create request (see Example request). The full field list is in ACEParaOptimize.