Auto-digitize options recipe

Auto-digitize options recipe

The autodigitize_options XML element configures how the API converts bitmap or vector artwork into machine files. It allows specification of output dimensions and thread color control.

XML structure

<autodigitize_options      <!-- Root element: auto digitize options -->

   width="100"                   <!-- Optional: Target width (in mm) -->
   height="100"                  <!-- Optional: Target height (in mm) -->

   thread_file="threadchart.tch"    <!-- Optional: Thread chart file name, must exist in <files> -->

>

   <threads>                     <!-- Optional list of nominated threads -->
      <thread ... />             <!-- Thread color definition -->
      <thread ... />
      <thread ... />
   </threads>

</autodigitize_options>

Usage

The <autodigitize_options> element is used in the input of:

  1. api/bitmapArtTrueview
  2. api/bitmapArtDesign
  3. api/vectorArtTrueview
  4. api/vectorArtDesign

Attributes

These attributes define how auto-digitizing should interpret and render the input image...

Attribute
Optional
Details
width / height
✅
Target output size in millimeters.
  1. If neither is provided, output size is calculated from the image DPI and pixel dimensions. Default DPI is assumed to be 96 if missing or invalid.
  2. If one is provided, the other is automatically calculated to maintain aspect ratio.
  3. If both are provided, design fits within the rectangle while preserving aspect ratio.
⚠️ Due to DPI rounding and unit conversions, minor inaccuracies in size may occur.
thread_file 
✅
  1. Name of a thread chart file (TCH) used for matching colors during digitizing.
  2. Must match a filename in the <files> section.
  3. Ignored if <threads> is also present (see below).
threads
✅
  1. A list of nominated thread colors to be used in the output design.
  2. Takes precedence over thread_file if both are provided.
  3. Each <thread> defines a specific color to match against the processed artwork.

Remarks

Width & height

  1. If both width and height are provided, the resulting design will fit within the given dimensions while preserving the original aspect ratio.
  2. If only one dimension is specified, the other is automatically calculated to maintain the aspect ratio.
  3. If neither is specified, the design size is derived using the image DPI.
  4. Note: Some images have missing or inconsistent DPI metadata. EWA uses the NET library’s DPI reading (same as the file property in Windows). The default DPI is 96 if none is found.
  5. Minor precision loss may occur when converting between DPI, inches, and millimeters – so the final size may differ slightly from the requested width and height.

Thread color handling

  1. The API first processes the artwork – e.g. reduces colors – to prepare it for auto-digitizing.
  2. If <threads> or thread_file is specified, the API matches artwork colors to the nominated threads.
  3. If neither is provided, the API attempts to match processed colors to its default palette. If a perfect match is not found, new colors are added to the palette without additional metadata – e.g. no brand or code.

Processing flow summary

  1. Artwork is processed – e.g. color reduction.
  2. Color matching is applied using the above logic.
  3. Stitches are generated based on the processed image and selected threads.

Artwork limitations

The API only accepts requests smaller than 20MB. Large artwork files take too long to process and use too many server resources. To avoid this, EWA has set the following restrictions:

Limitation

Value

Note

Maximum file size

2MB

 

Maximum pixel count

5,000,000 pixels

For vector file, EWA calculates pixel count in 300DPI.

Maximum area size

22,500 square millimetres

 

Maximum processing time

90 seconds

 

    • Related Articles

    • Auto-Recovery dialogue box keeps on prompting when opening Embroidery Studio e4.5

      Auto-Recovery Dialogue Box With this Auto Recovery dialog box, it pops up when you restart Embroidery Studio e4.5 software after an abnormal shutting down of the software. When you restart Embroidery Studio e4.5, it pops up this Auto Recovery dialog ...

    • Understanding auto-digitizing

      In the Embroidery Web API, auto-digitizing uses technology from EmbroideryStudio to convert images into embroidery designs. The process is as follows... Upload an image (bitmap or vector). The Embroidery Engine generates an EMB file (Wilcom’s native ...

    • Auto-digitizing calls

      AutoDigitizing is a paid feature not included in standard API plans. It converts an image → EMB → TrueView PNG / machine file. It uses specific API calls. It is charged per call because these requests are resource-intensive. Usage can be tracked in ...

    • Reporting auto-digitizing problems

      Auto-digitizing converts uploaded images into embroidery designs (EMB) and TrueView previews. Sometimes the results may not match expectations – for example, if the image is too large, too fuzzy, or even a photograph. When this happens, it’s ...

    • EWA API getting started

      These notes guide developers through the initial setup, authentication, API calling structure, and development tools available for integrating the Wilcom Embroidery Web API into web applications. ✅ Step 1: Sign up and get API credentials Visit the ...